Column-Level Data Lineage for Analytics Engineers (Straight From Your dbt Models)

As an analytics engineer you are asked the same two questions all week: why is this number what it is, and what happens if I change that column? Model-level lineage tells you which models are involved. Column-level lineage tells you which columns, and what happened to them. Here is a workflow for using it in dbt, without a warehouse connection.

Open the dbt Column Lineage Tool

Why model lineage is not enough

In dbt, model-level lineage is built in. It tells you that fct_orders depends on stg_orders and stg_payments. It does not tell you that total_revenue is a sum of a column that came from payments.amount after a currency conversion in an intermediate model.

That level of detail decides whether a debugging session takes five minutes or two hours.

What you need

Only your models folder. A tool that reads the SQL of each model can work out column links without running dbt or connecting to the warehouse. The dbt column lineage tool does this in your browser: drop the folder, open the Columns tab and pick a model.

Workflow 1: debug a wrong number

A stakeholder says monthly revenue looks too low.

Step 1: find the column

Open the mart that feeds the report. Click the revenue column.

Step 2: walk upstream

The left side shows the columns it is built from, hop by hop. Each link is marked copied or calculated, and you can hover to read the expression.

Step 3: look for the changing step

Chains of copies are rarely the problem. Look for the first calculated link: a filter, a join that multiplies rows, a CASE that drops a category or a cast that rounds. Fix it there.

-- the cause is often one line in staging
select id as order_id, amount as order_amount
from {{ source('shop', 'orders') }}
where status = 'completed'   -- drops refunds and pending orders

Workflow 2: rename a column safely

You want to rename customer_id to account_id in a staging model.

  • Open the Columns tab for that staging model and click customer_id.
  • Read the right-hand list: every column in other models built from it, directly or through other models.
  • Change exactly those, and nothing else.

Searching the repository for customer_id would also return unrelated columns that share the name. Lineage returns only the dependants.

Workflow 3: review a pull request

A pull request changes a calculation in an intermediate model. Drop the branch's models into the visualizer and click the changed column. The right-hand list tells you which marts it reaches. If a mart appears that the description does not mention, ask about it in the review.

Workflow 4: document a metric

Ask "what does this metric include?" for your top five metrics and keep the chain as documentation. Because the chain is generated from the code, you can regenerate it whenever the models change instead of maintaining a diagram.

What it can and cannot see

Column links are read from the SQL, following aliases, casts, CASE expressions, functions, CTEs and subqueries. It is best effort. Be aware of these limits:

  • A SELECT * is expanded only when the source columns are defined in your files. In dbt this often means columns from a source() call show as unknown unless you provide a CREATE TABLE for them.
  • Macros and Jinja loops that generate columns cannot be followed, because the final SQL is not in the file.
  • Descriptions and tests from YAML are not read.

The Issues tab lists statements that could not be read, so you know which models need a manual check.

Making your models easier to trace

  • Prefer explicit column lists over SELECT * in staging models.
  • Keep calculations in intermediate models with clear names rather than hiding them in marts.
  • Avoid generating columns with macros unless you need to.

Where this fits

dbt's own tooling covers documentation and model lineage, and its hosted offering covers column lineage on certain plans. A browser-based column tracer fills the gap when you want an answer now, with no setup. See the best free dbt lineage tools for how the options compare, and what column-level data lineage is for the concept.

Open the dbt Column Lineage Tool

Related tool pages

  • SQL Lineage Analyzer for a Folder of SQL Files: Upload a folder of SQL files or a dbt project and get table and column lineage across every file, a run order and impact analysis. Free, runs in your browser.
  • dbt Lineage Viewer for Your SQL Models: Drop your dbt models folder and see the lineage graph from sources through staging to marts, with column links. No dbt run, no warehouse. Free, private.
  • SQL Column Lineage Tool: See which source columns build every column of a view or table across many SQL files. Trace to the raw table or forward to dependants. Free, in your browser.
  • SQL File Dependency Analyzer: Find out which SQL file must run before which, from the tables each file creates and reads. Get a run order, circular dependencies and tables nothing uses.
  • SQL Impact Analysis: What Breaks If a Table Changes: Pick a table and see everything downstream that depends on it, and every upstream source it is built from. Works across a whole folder of SQL files, free.
  • SQL File Lineage Tool: Free SQL file lineage tool: drop a folder of .sql files and see which file feeds which table, column by column. Nothing is uploaded.

Also try

How to use the dbt Column Lineage Tool: step by step

  1. Drop your dbt models folder into the column lineage tool.
  2. Open Columns, choose a model and click a column.
  3. Read the source columns on the left and the dependants on the right.

When to use the dbt Column Lineage Tool

  • Debug a metric back to its source column
  • Rename a staging column safely
  • Review a changed calculation
  • Document how a metric is built

Example

Input: models/marts/fct_orders.sql with order_total = quantity * unit_price

Output: order_total ← stg_order_items.quantity, stg_order_items.unit_price ← source.order_items

Frequently asked questions

How do I see column-level lineage in dbt?

Drop your models folder into a tool that reads SQL, open the Columns tab and click a column. It lists the source columns and the dependent columns.

Do I need a warehouse connection?

No. The lineage is read from the model SQL, so no warehouse, manifest or credentials are needed.

Why is a column missing from the lineage?

It may be created by a macro or Jinja loop, or come from a SELECT * on a table not defined in your files. Such cases are listed under Issues.

Can I use it to plan a column rename?

Yes. Click the column and read the list of dependants. Those are the columns you need to update.

Tip: Hover a link to read the exact expression. The first calculated link in a chain is usually where a value changes meaning.