Lineage Agent Guide

This guide explains how to use the Lineage Agent in Alation AI to explore data lineage and understand column transformations.

Estimated cost0.5–1ACUper object

A few metered actions per documented object (the lineage fetch plus the agent’s writing call). At 0.25 ACU per metered action; confirm actual spend on the Usage page.

What the Lineage Agent Does

The Lineage Agent helps you understand how data flows through your pipelines:

Find data dependencies - What tables feed into this table? What uses this table?
Trace column transformations - How is this column calculated? What SQL logic creates this table?
Create documentation - Save lineage analysis as a document for future reference

What You Can Ask

Find Dependencies

"What tables feed into the orders table?"
"Show me upstream dependencies for table ID 1234"

Trace Transformations

"How is the revenue_total column calculated?"
"What transformations happen to this table's data?"

Create Documentation

"Create lineage documentation for table ID 1234"
"Generate a lineage document for the orders table"

Tools

The Lineage Agent has access to these tools:

Tool	What It Does
`get_search_context`	Find tables or columns by name in the catalog
`get_filter_context`	Fetch existing documentation by ID
`get_lineage`	Fetch upstream or downstream lineage graph
`generate_lineage_documentation`	Analyze SQL transformations for a table’s columns
`get_document_templates`	List available templates for creating documents
`update_catalog_object`	Link a document to a table’s custom field

get_lineage

Retrieves the lineage graph showing what objects are connected upstream (sources) or downstream (consumers).

Supports:

Table-level lineage (otype="table")
Column-level lineage (otype="attribute" with column IDs)
Filtering by object type

generate_lineage_documentation

Analyzes SQL dataflows to trace how each column in a table is derived from source columns.

Important: This tool only works for tables.

What it returns:

Executive summary of what the table represents
Column transformations (calculations, aggregations, renames)
Passthrough columns (unchanged from source)
Untraced columns (where SQL couldn’t be analyzed)
Data quality notes (filters, joins, conditions)
Source tables and downstream consumers

Document Creation

You can optionally save the analysis as a document. This is recommended because:

Avoids re-processing the same SQL analysis repeatedly
Stores the results for future reference
Can be linked to the table for easy access

To create a document, provide:

folder_id - Where to save the document
document_hub_id - Which document hub
template_id - Which template to use

Template Setup

To save lineage documentation, you need a document template with specific custom fields:

Field Name	Field Type	Description
Source Tables	OBJECT_SET	Leaf tables where data originates
Downstream Tables	OBJECT_SET	Tables that consume this table’s data
Upstream Layers	RICH_TEXT	Visual representation of the data pipeline layers
Downstream Tables Detail	RICH_TEXT	Downstream tables with links
Downstream BI Objects	RICH_TEXT	BI reports and dashboards using this table
Column Transformations	RICH_TEXT	How each column is calculated (aggregations, renames, CASE logic)
Passthrough Columns	RICH_TEXT	Columns that pass through unchanged from source
Untraced Columns	RICH_TEXT	Columns where lineage couldn’t be determined from SQL
Data Quality Notes	RICH_TEXT	Filters, joins, and conditions that affect data quality

Limitations

Limitation	Notes
Tables only	Transformation analysis (`generate_lineage_documentation`) only works for tables
Max nodes	Maximum 1000 nodes per lineage query
Max depth	Maximum traversal depth of 20 levels