Downstream Lineage

Downstream lineage traces the consumers of a data entity -- revealing which tables, reports, dashboards, and pipelines use data from a given source. This is critical for impact analysis before making schema changes.

Get Downstream Lineage

Retrieve all direct downstream edges for an entity:

GET /v1/lineage/entity/{entityId}/downstream?tenantId={tenantId}

curl "http://localhost:8086/v1/lineage/entity/550e8400-e29b-41d4-a716-446655440001/downstream?tenantId=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TOKEN"

Response

[
  {
    "id": "edge-010",
    "sourceEntityId": "tbl-raw-orders",
    "sourceEntityFqn": "warehouse.raw.orders",
    "sourceEntityType": "table",
    "targetEntityId": "tbl-dim-orders",
    "targetEntityFqn": "warehouse.analytics.dim_orders",
    "targetEntityType": "table",
    "lineageType": "DIRECT",
    "lineageSource": "PIPELINE",
    "confidence": 1.0
  },
  {
    "id": "edge-011",
    "sourceEntityId": "tbl-raw-orders",
    "sourceEntityFqn": "warehouse.raw.orders",
    "sourceEntityType": "table",
    "targetEntityId": "tbl-fact-revenue",
    "targetEntityFqn": "warehouse.analytics.fact_revenue",
    "targetEntityType": "table",
    "lineageType": "DIRECT",
    "lineageSource": "QUERY_ANALYSIS",
    "confidence": 0.92
  }
]

Downstream Visualization Graph

For a graph-structured downstream view with depth traversal:

GET /api/v1/lineage/visualization/graph/{entityId}/downstream?maxDepth=5

curl "http://localhost:8086/api/v1/lineage/visualization/graph/550e8400-e29b-41d4-a716-446655440001/downstream?maxDepth=5" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "graph": {
    "nodes": [
      {
        "id": "tbl-dim-orders",
        "name": "analytics.dim_orders",
        "type": "TABLE",
        "depth": 1
      },
      {
        "id": "tbl-fact-revenue",
        "name": "analytics.fact_revenue",
        "type": "TABLE",
        "depth": 1
      },
      {
        "id": "report-monthly-sales",
        "name": "Monthly Sales Dashboard",
        "type": "DASHBOARD",
        "depth": 2
      }
    ],
    "edges": [
      {
        "sourceId": "tbl-raw-orders",
        "targetId": "tbl-dim-orders",
        "lineageType": "DIRECT"
      },
      {
        "sourceId": "tbl-raw-orders",
        "targetId": "tbl-fact-revenue",
        "lineageType": "DIRECT"
      },
      {
        "sourceId": "tbl-fact-revenue",
        "targetId": "report-monthly-sales",
        "lineageType": "DIRECT"
      }
    ]
  },
  "metadata": {
    "entityId": "tbl-raw-orders",
    "direction": "DOWNSTREAM",
    "maxDepth": 5,
    "actualDepth": 2,
    "totalNodes": 3,
    "totalEdges": 3
  }
}

Downstream Column Lineage

Trace where a specific column's data flows downstream:

GET /v1/catalog/lineage/column/downstream?tableFqn={fqn}&columnName={col}&depth=5

curl "http://localhost:8086/v1/catalog/lineage/column/downstream?tableFqn=warehouse.raw.orders&columnName=customer_id&depth=5" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000"

Response

{
  "rootTable": "warehouse.raw.orders",
  "rootColumn": "customer_id",
  "nodes": [
    {
      "tableFqn": "warehouse.analytics.dim_orders",
      "columnName": "customer_id",
      "depth": 1,
      "transformation": "DIRECT_COPY"
    },
    {
      "tableFqn": "warehouse.analytics.customer_metrics",
      "columnName": "cust_id",
      "depth": 2,
      "transformation": "RENAME"
    }
  ],
  "edges": [
    {
      "sourceTable": "warehouse.raw.orders",
      "sourceColumn": "customer_id",
      "targetTable": "warehouse.analytics.dim_orders",
      "targetColumn": "customer_id",
      "transformation": "DIRECT_COPY"
    },
    {
      "sourceTable": "warehouse.analytics.dim_orders",
      "sourceColumn": "customer_id",
      "targetTable": "warehouse.analytics.customer_metrics",
      "targetColumn": "cust_id",
      "transformation": "RENAME"
    }
  ]
}

Impact Analysis

The downstream lineage powers the impact analysis feature. Before making a schema change, analyze which downstream assets will be affected:

GET /api/v1/lineage/visualization/impact-analysis/{entityId}?changeType=SCHEMA_CHANGE&maxDepth=10

curl "http://localhost:8086/api/v1/lineage/visualization/impact-analysis/550e8400-e29b-41d4-a716-446655440001?changeType=SCHEMA_CHANGE&maxDepth=10" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TOKEN"

See Lineage Visualization for full impact analysis documentation.

Use Cases

Schema change impact -- Before dropping or renaming a column, see every downstream table and report affected
Deprecation planning -- Identify all consumers of a table being decommissioned
Change management -- Route notifications to owners of downstream assets when source data changes

Source Reference

Component	File
Downstream lineage endpoint	`LineageController.java` -- `getDownstreamLineage()`
Downstream visualization	`LineageVisualizationController.java` -- `getDownstreamLineage()`
Column downstream trace	`ColumnLineageController.java` -- `traceDownstream()`
Impact analysis	`VisualizationImpactAnalysisService.java`

Upstream Lineage Full Lineage Graph