Data Lineage Graph

A data lineage graph shows where each table, column or metric comes from and what depends on it. This sample traces an e-commerce stack: two Postgres tables and Stripe charges flow through dbt staging models into a customer dimension and an orders fact, which feed three consumers.

Lineage graphs are not UML. UML covers software structure and behaviour; lineage is one of the other standard data-engineering views used alongside it, usually generated by tools such as dbt docs, OpenLineage/Marquez, DataHub or Unity Catalog.

1. The Diagram

1. Sources. Raw tables replicated from production (CDC) and a SaaS API. Nobody should query these directly in reports.
2. Staging. One model per source table: renames, type casts, deduplication, PII masking. Lineage here is one-to-one.
3. Marts. dim_customers combines customers with their first order date; fct_orders combines orders, payments and the customer key. Fan-in shows business logic.
4. Consumers. Dashboards and an ML feature set. The fan-out from the marts is the blast radius of any change.

Example question: Stripe renames a field. Follow stripe.charges rightwards and you get the exact list of models and dashboards to check: stg_payments, fct_orders, the revenue dashboard and the LTV report.

2. How to Read It

Arrows point downstream. Colour the layers consistently so readers see the stage at a glance. Most tools let you click a node and highlight its upstream and downstream sets, which is the real power of lineage: a static picture is a summary, the interactive graph is the tool.

3. Variant: Column-Level Lineage

Table lineage says fct_orders depends on three tables. Column lineage says precisely which columns: net_revenue_usd is computed from amount_cents, refund_cents and rate_to_usd. That level answers audit questions ("prove this revenue number") and tells you that dropping stg_orders.currency only matters through the join. Column lineage is parsed from SQL, so it breaks on dynamic SQL or Python transforms that tools cannot read.

4. Pros, Cons, and When to Use

Pros

• Answers impact analysis instantly: what breaks if this changes?
• Provides provenance for audits, finance and regulators (BCBS 239, SOX).
• Generated automatically, so it stays current when built from metadata.
• Helps find dead models with no downstream consumers.
• Speeds up incident triage by tracing a bad number back to its source.

Cons

• Large estates produce hairballs with thousands of nodes; filter by depth.
• Automatic parsers miss Python, stored procedures and dynamic SQL.
• Says nothing about schedules, freshness or run order (use a DAG).
• Column lineage tools are often paid or platform-specific.
• Hand-drawn versions go stale within weeks.

When to use

• Planning schema changes and deprecations.
• Data incident root-cause analysis.
• Compliance evidence and PII tracking.

When not to use

• Explaining task order or retries.
• Designing new architecture before any SQL exists (use a DFD or architecture diagram).

5. As Diagrams-as-Code

Mermaid flowchart LR with subgraphs per layer (dbt generates the equivalent automatically with dbt docs generate):

flowchart LR
  subgraph Sources
    src_orders[(postgres.orders)]; src_cust[(postgres.customers)]; src_chg[(stripe.charges)]
  end
  subgraph Staging
    stg_orders; stg_customers; stg_payments
  end
  subgraph Marts
    dim_customers; fct_orders
  end
  src_orders --> stg_orders
  src_cust --> stg_customers
  src_chg --> stg_payments
  stg_customers --> dim_customers
  stg_orders --> dim_customers
  stg_orders --> fct_orders
  stg_payments --> fct_orders
  dim_customers --> fct_orders
  fct_orders --> rev[Revenue dashboard]
  fct_orders --> ltv[Customer LTV report]
  dim_customers --> ltv
  dim_customers --> churn[churn_model features]

6. Related

• Architecture Diagrams — notation reference for boxes-and-arrows views
• Data Lineage — concepts and tooling
• Unity Catalog Lineage — lineage captured by Databricks
• dbt — the transformation tool used in this sample
• Data Flow Diagram: Order System — sibling sample
• Pipeline DAG Diagram — sibling sample
• Lambda vs Kappa Diagram — sibling sample
• Streaming Topology Diagram — sibling sample
• Medallion Lakehouse Diagram — sibling sample
• Data Engineering diagrams — section overview