How to read a data lineage graph without getting lost

Every useful reading starts with one node and one question. If the question is why a number is wrong, the direction is upstream and the target is the thing that produced it. If the question is what a change will break, the direction is downstream and the target is the object being changed. Trying to read a lineage graph without fixing both is how people end up scrolling for ten minutes and learning nothing.

Convention matters here. Most tools, dbt included, put upstream on the left and downstream on the right, with arrows following the flow of data. Before you trust that, confirm it on a node you already understand, because a graph rendered top to bottom or with reversed arrows will lead you to exactly the wrong conclusion.

Then follow one path at a time to the end. Breadth-first reading of a lineage graph produces a memorised picture and no understanding. Depth-first reading of one path produces a sentence you can say out loud, which is the actual deliverable.

An arrow says data moved. It does not say how, and the how is what determines the failure mode. A direct copy breaks on a rename. An aggregation breaks on a grain change and silently produces wrong totals on a duplicate. A join edge breaks on a key change or a null, and its failure looks like missing rows rather than an error. A filter edge is the one that quietly drops the records you are looking for.

This is why an edge carrying a joinType and a one-line description is worth more than three extra nodes. When the edge says aggregation, sum per day excluding refunds, a reader with domain knowledge spots a wrong assumption in seconds. When the edge says only that two tables are connected, the same reader has to open the SQL.

The same applies to grain changes. An edge that moves from one row per event to one row per customer per day is where most metric disputes are born, and it is invisible unless somebody wrote it on the edge.

A cycle. Data lineage is acyclic by definition, so a loop means either the graph is wrong or two distinct objects have been merged into one node, usually because they share a name across environments. Datadef refuses to validate a canvas containing one, and prints the offending path rather than a generic error, because the path is what tells you which node was merged.

Edges pointing at nothing. Links that reference deleted nodes survive in graphs that are maintained by hand, and they inflate the apparent connectivity of the map. validate_canvas counts them separately so they can be cleaned rather than argued with.

A fan. One node with five or more edges converging on it is the third check, and validate_canvas names it: that many edges on one node draws a bundle of long curves across the canvas. It usually means a cross-cutting concern, a catalog or an orchestrator, has been wired to everything it relates to rather than named once in a note. The right reading is not that the node is important, it is that the drawing has hidden the flow.

And one no validator reports: a hub with many downstream consumers and nobody named. That is the highest-risk object on the picture, because every change to it is a change to everything and there is no first responder. The absence of an owner is not a structural defect, which is precisely why a first reading is worth doing by a person.

validate_canvas findings

  error   cycle            Data flows in a circle: fct_orders ->
                           dim_customers -> fct_orders. Data
                           lineage must be acyclic.

  error   orphan-lineage   3 lineage link(s) reference deleted
                           nodes.

  warning edge-fan-out     stg_customers (11 edges). That many
                           edges converging on one node draws a
                           fan of long curves across the canvas.

  warning dense-canvas     47 data nodes and 63 connections.
                           Past roughly 30 data nodes a diagram
                           tends to be searched rather than read.

If the picture does not fit on a screen at a zoom where labels are legible, you are not looking at a diagram, you are looking at a database rendered as boxes. That is a fine reference and a poor explanation, and no amount of layout tuning changes it.

The threshold is lower than people expect. Datadef raises its dense-canvas warning past thirty data nodes, on the reasoning that a larger picture gets searched rather than read, and keeps it a warning rather than an error because sometimes the detail is the point. When it is not the point, collapse to the level people actually discuss: group the fifteen staging models into one staging zone, keep the marts named individually, and name the consumers. A map that fits on a screen is one people return to, and returning is what makes it worth maintaining.

• Data lineage on one canvas
• Column-level lineage explained
• Data lineage vs impact analysis
• Generate a data lineage diagram