Lineage Agent Guide
This guide explains how to use the Lineage Agent in Alation AI to explore data lineage and understand column transformations.
What the Lineage Agent Does
Section titled “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
Section titled “What You Can Ask”Find Dependencies
Section titled “Find Dependencies”"What tables feed into the orders table?""Show me upstream dependencies for table ID 1234"Trace Transformations
Section titled “Trace Transformations”"How is the revenue_total column calculated?""What transformations happen to this table's data?"Create Documentation
Section titled “Create Documentation”"Create lineage documentation for table ID 1234""Generate a lineage document for the orders table"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
Section titled “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
Section titled “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
Section titled “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 documentdocument_hub_id- Which document hubtemplate_id- Which template to use
Template Setup
Section titled “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
Section titled “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 |