Data Lineage Diagram: How to Read and Build One

A data lineage diagram is a directed graph where nodes are data assets (tables, models, columns, dashboards) and edges are dependencies pointing from a source to whatever consumes it. You read it by following the arrows: upstream is to the left or top, downstream is to the right or bottom, and any path between two nodes is a dependency chain. The hard part is not reading one; it is keeping it accurate, which is why hand-drawn diagrams go stale and automated lineage has become the standard.

The two building blocks: nodes and edges

Every lineage diagram is made of two things.

Nodes are data assets. At minimum these are tables and views: raw.stripe.charges, stg_stripe_charges, fct_orders. A richer diagram also includes upstream sources (the Stripe connector), downstream exposures (a specific dashboard or report), and at the finest resolution, individual columns like fct_orders.revenue.

Edges are dependencies. An edge from stg_stripe_charges to fct_orders means the mart is built from the staging model. Edges are directed: they always point from source to consumer, which is what lets you reason about upstream and downstream.

How to read a lineage diagram

Once you know nodes and edges, reading the graph is a matter of direction and traversal.

• Upstream means follow the arrows backward, toward the sources. The upstream of the revenue tile is fct_orders, then stg_stripe_charges, then raw.stripe.charges. This is how you trace a number to its origin.
• Downstream means follow the arrows forward, toward the consumers. The downstream of raw.stripe.charges is every model and dashboard that ultimately depends on it. This is your blast radius for a change or an incident.
• A path between two nodes is a dependency chain. If there is no path, the two assets are independent and a change to one cannot affect the other.

A useful habit is to pick a node and ask both questions. "What feeds this?" gives you the trace-to-source. "What does this feed?" gives you the downstream impact. The same diagram answers both depending on which way you walk it.

What to include in a lineage diagram

A diagram is only useful if it includes the right layers. Leave out the ends and you lose the most important answers.

The most common mistake is stopping at the dbt boundary. dbt's own graph runs from sources to models but knows nothing about the raw loads before its sources or the BI tools after its marts. A diagram that begins at stg_ and ends at fct_ cannot answer "which dashboard breaks if this raw load fails," which is the question stakeholders actually ask. A complete lineage map extends past both ends of the dbt boundary.

Table-level vs column-level diagrams

At table resolution, each node is a table and the graph shows pipeline structure. This is readable and good for understanding order and rough impact. At column resolution, each node is a field and an edge like raw.stripe.charges.amount -> stg_stripe_charges.amount_usd -> fct_orders.revenue shows exactly how one value flows.

Column-level diagrams are denser but far more precise. They let you answer "if I rename customers.email, which exact columns downstream reference it?" without flagging every unrelated column in the same tables. For change planning, column-level lineage is the resolution that actually prevents broken dashboards, and it is worth understanding how column-level lineage is resolved before you rely on a vendor's claim to have it.

Why hand-drawn diagrams go stale

Teams often start with a diagram in a slide deck or a whiteboard photo. It is accurate the day it is drawn and wrong within weeks. Warehouses change constantly:

• An engineer adds a new model that joins an existing one, creating an edge no one updated.
• A column gets renamed, so the trace-to-source in the diagram now points at a field that does not exist.
• A mart gets split into two, doubling the nodes.
• A dashboard gets repointed to a different table.

Nobody updates the slide. Within a sprint the diagram is decorative, and worse, it is confidently wrong, which is more dangerous than having no diagram at all. The maintenance cost of manual lineage scales with the size and churn of the warehouse, and it always loses.

The automated approach

Automated lineage rebuilds the diagram from what actually runs, so it cannot drift away from reality. There are three signals it draws on:

1. dbt metadata. The manifest.json encodes ref() and source() edges accurately inside the project.
2. Warehouse query logs. Snowflake's QUERY_HISTORY and column-resolved ACCESS_HISTORY, BigQuery's INFORMATION_SCHEMA.JOBS and audit logs, and Redshift and Postgres statement logs reveal every query that ran, including the ad-hoc and BI-tool queries that live past the dbt boundary.
3. Static SQL parsing. Parsing model SQL resolves FROM, JOIN, CTEs, and select expressions into both table and column edges.

Combining these produces a diagram that updates as the warehouse changes, includes both ends past the dbt boundary, and supports column-level resolution. Reading the warehouse this way is read-only by design: the graph is built from query history and metadata, never by writing to your tables.

From diagram to action

A good lineage diagram is not a static picture; it is an interactive graph you query. You click raw.stripe.charges and immediately see everything downstream. You click the revenue tile and see the chain back to the source column. You highlight a column you are about to drop and the diagram lights up every dependent asset.

If you want a lineage diagram of your own warehouse that stays current instead of going stale, you can see how Datatrail builds and renders the graph from a read-only connection to Snowflake, BigQuery, Redshift, or Postgres, with both table and column-level edges traced from real query history.