Data Lineage Guide

Lineage in a diagram vs lineage in a data catalog

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

Catalogs have a lineage tab and diagrams show lineage, so the two get compared as competing purchases. They are not the same artifact. A catalog is an index built for search: what exists, where it lives, who owns it, is it certified. A diagram is an explanation built for one reader and one flow. Teams that treat them as substitutes usually end up with a catalog nobody outside the data team opens.

Try it free
6 min readFor teams choosing between documenting flows and buying an index

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

161/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Two artifacts, two readers

The catalog reader arrives with the name of a thing. They want to know whether the table is the certified one, when it last refreshed, what the columns mean, and who to ask. Search is the primary interface, and the answer is a page about one asset.

The diagram reader arrives with a question about a journey. An auditor asking how the reported figure was produced, a new analytics engineer trying to understand a domain, a finance lead asking why two numbers disagree. None of them can start from an asset name, because the thing they know is the number on a dashboard.

That difference explains why catalog lineage views frequently disappoint. They render lineage per asset, expanding a hop at a time, which is the right interaction for an asset-centric index and the wrong one for a question spanning eight hops across three systems.

What each one does that the other cannot

The catalog wins on coverage and freshness of the inventory. It knows about tables nobody drew, it updates by scanning, it holds column descriptions, certification status, and access policy, and it answers questions about assets you have never heard of. No diagram scales to that, and pretending otherwise produces a wall of boxes.

The diagram wins on narrative, curation, and reach. It shows the hops that are not in the warehouse, the ingestion tool and the dashboard calculation and the export that no scanner sees. It can be annotated with the reason a hop exists. It can be embedded in the Confluence page, the Notion doc, or the README where the reader already is, which is the single biggest determinant of whether documentation gets read.

Datadef sits firmly on the diagram side and says so: no warehouse connection, no query-log harvesting. A table node carries the real object name, a one-line description, its columns with types and primary or foreign key flags, and three governance fields, dataOwner, dataSteward, and teamInCharge. A pipeline node carries the technology and the schedule that runs it. That is deliberately a subset of what a catalog holds, and it is the subset a reader needs to follow a flow without opening anything else.

{
  "tool": "canvas_add_nodes",
  "nodes": [
    {
      "type": "table",
      "label": "fct_revenue_daily",
      "description": "Grain: one row per day. Refunds excluded.",
      "family": "gold",
      "dataOwner": "Priya N.",
      "dataSteward": "Finance Data",
      "teamInCharge": ["revenue-analytics"],
      "columns": [
        { "name": "date_day", "type": "date", "isPrimaryKey": true },
        { "name": "revenue", "type": "numeric", "description": "net of refunds" }
      ]
    },
    {
      "type": "pipeline",
      "label": "build_revenue_marts",
      "pipelineType": "transformation",
      "technology": "dbt",
      "schedule": "0 2 * * *"
    }
  ]
}

Running both without duplicating work

Let the catalog own asset facts, because it can refresh them automatically. Let the diagram own flow facts, because a human decided which hops matter and why. When they disagree about an asset, the catalog wins, and the diagram should link out rather than restate the column descriptions.

Generate the parts you can. Where flows are defined in code, a repository connection can regenerate the diagram and an architecture doc daily, so the picture follows the branch instead of a person. Structural changes redraw the diagram, unchanged commits do not, and nodes you positioned by hand keep their positions across syncs.

Then place the diagram where the readers are. A live embed renders the current canvas in a wiki page or README from one markdown line, and viewers need no account, so the auditor and the finance lead see the same version the data team sees.

The index is not the explanation

A catalog answers what exists. A diagram answers how it works. If your catalog rollout stalled because nobody outside the data team logs in, the missing artifact is probably a readable flow map, not more scanning.

A first week that produces both

Pick the metric two teams currently disagree about. It is a better starting point than an inventory sweep because it has a named audience, a finish line, and someone who will confirm the answer.

Draw that one flow end to end, including the hops no scanner sees: the ingestion tool, the calculation in the dashboard tile, the export that lands in a spreadsheet. Four facts per hop, system, object, transformation in one line, owner. Then, in the catalog, certify the two or three tables the flow passes through and write the grain sentence into their descriptions. That is the smallest piece of catalog work that is worth anything, and it is aimed rather than exhaustive.

Cross-reference them once. The node descriptions on the diagram name the catalog objects exactly as the catalog names them, so a reader can search for what they just saw, and the certified tables in the catalog carry the sentence a reader needs before querying. Neither artifact restates the other, and both were produced by answering one question that someone was already asking.

FAQ

What is the difference between a data catalog and a lineage diagram?

A catalog is a searchable inventory of assets with ownership, descriptions, and governance metadata, kept current by scanning. A lineage diagram is a curated explanation of how one flow works end to end, including hops outside the warehouse, aimed at a reader who starts from a question rather than an asset name.

Does a diagram replace a data catalog?

No. A diagram cannot inventory thousands of assets or keep column descriptions current by itself. It covers the explanation job the catalog is weak at, particularly for readers outside the data team, and the two work best with the diagram linking out to catalog entries.

Why do catalog lineage views often go unused?

Because they are asset-centric and expand one hop at a time, while the questions people bring span many hops and start from a number on a dashboard. That interaction suits an index and does not produce a narrative someone can follow or present.

Which should a team build first?

Whichever answers the question currently costing money. An audit, a migration, or a metric dispute is answered by documenting a small number of flows. Discovery problems, where people cannot find or trust the tables they need, are answered by an inventory.

How do I stop the diagram and the catalog from contradicting each other?

Give each one a scope and write it down. The catalog owns asset-level facts such as column descriptions, certification, and ownership, and stays the place to look them up. The diagram owns flow-level facts, including the hops the catalog cannot see: the ingestion tool, the dashboard calculation, the scheduled export. When the two disagree about an asset, the catalog wins.