Lineage Endpoints
The lineage endpoints provide column-level lineage tracking and impact analysis across your entire Olytix Core project. Trace data flow from sources through transformations to metrics.
POST /api/v1/unified/lineage/build
Build the complete column-level lineage graph. This computes lineage for all artifacts: sources, models, cubes, and metrics.
Request
curl -X POST "http://localhost:8000/api/v1/unified/lineage/build" \
-H "Authorization: Bearer YOUR_API_KEY"
With Project Path
curl -X POST "http://localhost:8000/api/v1/unified/lineage/build?project_path=/path/to/project" \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"success": true,
"nodes": [
{
"unique_id": "source.ecommerce.raw.orders.order_id",
"node_type": "source_column",
"artifact_name": "orders",
"column_name": "order_id",
"data_type": "INTEGER",
"sql_expression": null,
"certified": false
},
{
"unique_id": "model.ecommerce.fct_orders.total_amount",
"node_type": "model_column",
"artifact_name": "fct_orders",
"column_name": "total_amount",
"data_type": "DECIMAL(10,2)",
"sql_expression": "SUM(line_item_amount)",
"certified": true
},
{
"unique_id": "cube.ecommerce.orders.total_revenue",
"node_type": "measure",
"artifact_name": "orders",
"column_name": "total_revenue",
"data_type": null,
"sql_expression": "SUM(total_amount)",
"certified": true
}
],
"edges": [
{
"source_id": "source.ecommerce.raw.orders.amount",
"target_id": "model.ecommerce.stg_orders.amount",
"edge_type": "direct",
"transformation_sql": null
},
{
"source_id": "model.ecommerce.stg_orders.amount",
"target_id": "model.ecommerce.fct_orders.total_amount",
"edge_type": "aggregated",
"transformation_sql": "SUM(amount)"
},
{
"source_id": "model.ecommerce.fct_orders.total_amount",
"target_id": "cube.ecommerce.orders.total_revenue",
"edge_type": "measure_source",
"transformation_sql": null
}
],
"statistics": {
"total_nodes": 156,
"total_edges": 203,
"source_columns": 45,
"model_columns": 78,
"measures": 20,
"dimensions": 25,
"metrics": 8
},
"computed_at": "2024-01-20T10:30:00Z"
}
Edge Types
| Edge Type | Description |
|---|---|
direct | Column passes through unchanged |
renamed | Column renamed but data unchanged |
derived | Column computed from source columns |
aggregated | Aggregation applied (SUM, COUNT, etc.) |
joined | Column from a joined table |
filtered | Column filtered in transformation |
measure_source | Source column for a measure |
dimension_source | Source column for a dimension |
metric_source | Source measure for a metric |
calculated | Calculated field |
POST /api/v1/unified/lineage/column
Get lineage for a specific column. Supports both upstream (where does this column come from) and downstream (what uses this column) queries.
Request - Upstream Lineage
curl -X POST http://localhost:8000/api/v1/unified/lineage/column \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"column_id": "model.ecommerce.fct_orders.total_amount",
"direction": "upstream",
"max_depth": 10,
"max_nodes": 100
}'
Request - Downstream Lineage
curl -X POST http://localhost:8000/api/v1/unified/lineage/column \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"column_id": "source.ecommerce.raw.orders.customer_id",
"direction": "downstream",
"max_depth": 5,
"max_nodes": 50
}'
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
column_id | string | Yes | Unique ID of the column node |
direction | string | No | upstream or downstream (default: upstream) |
max_depth | number | No | Maximum traversal depth (default: 10) |
max_nodes | number | No | Maximum nodes to return (default: 1000) |
Response
{
"success": true,
"root_id": "model.ecommerce.fct_orders.total_amount",
"nodes": [
{
"unique_id": "source.ecommerce.raw.orders.amount",
"node_type": "source_column",
"artifact_name": "orders",
"column_name": "amount",
"data_type": "DECIMAL(10,2)",
"sql_expression": null,
"certified": false
},
{
"unique_id": "model.ecommerce.stg_orders.amount",
"node_type": "model_column",
"artifact_name": "stg_orders",
"column_name": "amount",
"data_type": "DECIMAL(10,2)",
"sql_expression": null,
"certified": false
},
{
"unique_id": "model.ecommerce.fct_orders.total_amount",
"node_type": "model_column",
"artifact_name": "fct_orders",
"column_name": "total_amount",
"data_type": "DECIMAL(10,2)",
"sql_expression": "SUM(amount)",
"certified": true
}
],
"edges": [
{
"source_id": "source.ecommerce.raw.orders.amount",
"target_id": "model.ecommerce.stg_orders.amount",
"edge_type": "direct",
"transformation_sql": null
},
{
"source_id": "model.ecommerce.stg_orders.amount",
"target_id": "model.ecommerce.fct_orders.total_amount",
"edge_type": "aggregated",
"transformation_sql": "SUM(amount)"
}
],
"node_count": 3,
"edge_count": 2,
"computed_at": "2024-01-20T10:30:00Z"
}
POST /api/v1/unified/lineage/impact
Analyze the downstream impact of changes to a column. Returns all dependent columns, measures, dimensions, and metrics that would be affected.
Request
curl -X POST http://localhost:8000/api/v1/unified/lineage/impact \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"column_id": "source.ecommerce.raw.orders.customer_id",
"max_depth": 10
}'
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
column_id | string | Yes | Unique ID of the column to analyze |
max_depth | number | No | Maximum traversal depth (default: 10) |
Response
{
"success": true,
"source_column": {
"unique_id": "source.ecommerce.raw.orders.customer_id",
"node_type": "source_column",
"artifact_name": "orders",
"column_name": "customer_id",
"data_type": "INTEGER",
"sql_expression": null,
"certified": false
},
"impacted_columns": [
{
"unique_id": "model.ecommerce.stg_orders.customer_id",
"node_type": "model_column",
"artifact_name": "stg_orders",
"column_name": "customer_id",
"data_type": "INTEGER",
"sql_expression": null,
"certified": false
},
{
"unique_id": "model.ecommerce.fct_orders.customer_id",
"node_type": "model_column",
"artifact_name": "fct_orders",
"column_name": "customer_id",
"data_type": "INTEGER",
"sql_expression": null,
"certified": true
}
],
"impacted_measures": [
{
"unique_id": "cube.ecommerce.orders.customer_count",
"node_type": "measure",
"artifact_name": "orders",
"column_name": "customer_count",
"data_type": null,
"sql_expression": "COUNT(DISTINCT customer_id)",
"certified": true
}
],
"impacted_dimensions": [
{
"unique_id": "cube.ecommerce.orders.customer_id",
"node_type": "dimension",
"artifact_name": "orders",
"column_name": "customer_id",
"data_type": "INTEGER",
"sql_expression": null,
"certified": true
}
],
"impacted_metrics": [
{
"unique_id": "metric.ecommerce.unique_customers",
"node_type": "metric",
"artifact_name": "unique_customers",
"column_name": null,
"data_type": null,
"sql_expression": null,
"certified": true
}
],
"total_impacted": 5,
"warnings": [
"Certified measure 'customer_count' will be affected",
"Certified metric 'unique_customers' will be affected"
]
}
GET /api/v1/unified/lineage/measure/{cube_name}/{measure_name}
Get complete lineage for a specific measure. Traces from the measure back to its source columns.
Request
curl -X GET "http://localhost:8000/api/v1/unified/lineage/measure/orders/total_revenue" \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"success": true,
"cube_name": "orders",
"measure_name": "total_revenue",
"nodes": [
{
"unique_id": "source.ecommerce.raw.orders.amount",
"node_type": "source_column",
"artifact_name": "orders",
"column_name": "amount",
"data_type": "DECIMAL(10,2)",
"sql_expression": null,
"certified": false
},
{
"unique_id": "model.ecommerce.fct_orders.total_amount",
"node_type": "model_column",
"artifact_name": "fct_orders",
"column_name": "total_amount",
"data_type": "DECIMAL(10,2)",
"sql_expression": "amount",
"certified": true
},
{
"unique_id": "cube.ecommerce.orders.total_revenue",
"node_type": "measure",
"artifact_name": "orders",
"column_name": "total_revenue",
"data_type": null,
"sql_expression": "SUM(total_amount)",
"certified": true
}
],
"edges": [
{
"source_id": "source.ecommerce.raw.orders.amount",
"target_id": "model.ecommerce.fct_orders.total_amount",
"edge_type": "direct",
"transformation_sql": null
},
{
"source_id": "model.ecommerce.fct_orders.total_amount",
"target_id": "cube.ecommerce.orders.total_revenue",
"edge_type": "measure_source",
"transformation_sql": "SUM(total_amount)"
}
],
"source_columns": [
"source.ecommerce.raw.orders.amount"
]
}
GET /api/v1/unified/lineage/metric/{metric_name}
Get complete lineage for a specific metric. Traces from the metric back through measures to source columns.
Request
curl -X GET "http://localhost:8000/api/v1/unified/lineage/metric/monthly_revenue" \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"success": true,
"metric_name": "monthly_revenue",
"nodes": [
{
"unique_id": "source.ecommerce.raw.orders.amount",
"node_type": "source_column",
"artifact_name": "orders",
"column_name": "amount",
"data_type": "DECIMAL(10,2)",
"sql_expression": null,
"certified": false
},
{
"unique_id": "cube.ecommerce.orders.total_revenue",
"node_type": "measure",
"artifact_name": "orders",
"column_name": "total_revenue",
"data_type": null,
"sql_expression": "SUM(total_amount)",
"certified": true
},
{
"unique_id": "metric.ecommerce.monthly_revenue",
"node_type": "metric",
"artifact_name": "monthly_revenue",
"column_name": null,
"data_type": null,
"sql_expression": null,
"certified": true
}
],
"edges": [
{
"source_id": "source.ecommerce.raw.orders.amount",
"target_id": "cube.ecommerce.orders.total_revenue",
"edge_type": "measure_source",
"transformation_sql": null
},
{
"source_id": "cube.ecommerce.orders.total_revenue",
"target_id": "metric.ecommerce.monthly_revenue",
"edge_type": "metric_source",
"transformation_sql": null
}
],
"source_measures": [
"cube.ecommerce.orders.total_revenue"
],
"source_columns": [
"source.ecommerce.raw.orders.amount"
]
}
GET /api/v1/unified/lineage/visualization
Get the lineage graph in a format suitable for visualization. Returns nodes and edges formatted for rendering in a graph UI.
Request
curl -X GET "http://localhost:8000/api/v1/unified/lineage/visualization" \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"nodes": [
{
"id": "source.ecommerce.raw.orders.amount",
"label": "orders.amount",
"type": "source_column",
"group": "sources",
"metadata": {
"artifact": "orders",
"column": "amount",
"data_type": "DECIMAL(10,2)"
}
},
{
"id": "cube.ecommerce.orders.total_revenue",
"label": "orders.total_revenue",
"type": "measure",
"group": "cubes",
"metadata": {
"artifact": "orders",
"column": "total_revenue",
"certified": true
}
}
],
"edges": [
{
"source": "source.ecommerce.raw.orders.amount",
"target": "cube.ecommerce.orders.total_revenue",
"type": "measure_source",
"label": "SUM"
}
]
}
Error Responses
400 Bad Request - Lineage Not Built
{
"detail": "Lineage not built. Call /lineage/build first."
}
404 Not Found
{
"detail": "Column 'model.ecommerce.fct_orders.invalid_column' not found in lineage graph"
}