SQL Lineage vs dbt Lineage: What's the Difference?
People use "SQL lineage" and "dbt lineage" as if they were the same thing. They overlap, but they answer different questions. dbt lineage tells you which models depend on which. SQL lineage reads the statements and can tell you which columns depend on which, even in a project that has no dbt at all. Knowing the difference tells you which one you need for the question in front of you.
The short answer
dbt lineage is built from the references you write between models. SQL lineage is built by reading the SQL. The first is about models, the second can go down to columns. A dbt project can use both.
What dbt lineage is
When dbt parses a project it finds every ref() and source() call and turns them into a graph. A model that selects from ref('stg_orders') depends on stg_orders. That is the DAG you see in dbt docs and the one that decides the order models run in. You can query it too, for example dbt ls --select +fct_orders for a model and its parents.
The graph connects models, sources, seeds and snapshots. It does not draw columns. It also depends on you writing ref() and source() correctly: a table named directly in the SQL is invisible to it.
What SQL lineage is
SQL lineage tools parse the statements. They read what a CREATE TABLE AS, INSERT ... SELECT, MERGE or view definition selects from and writes to, so they work on plain SQL scripts, stored procedures and legacy warehouses where dbt was never used. Because they see the SELECT list, they can also trace column lineage: this output column is built from that source column, copied or calculated.
A concrete example
-- models/marts/dim_customers.sql
select
customer_id,
lower(email) as email,
order_count
from {{ ref('int_customer_orders') }}dbt lineage says: dim_customers depends on int_customer_orders. SQL lineage says that, and also that dim_customers.email is built from int_customer_orders.email with lower(), so it is calculated, not copied, and that customer_id and order_count are copied unchanged. If you plan to change the email column, only the second view tells you what reads it.
Side by side
- **Unit:** dbt lineage works on models. SQL lineage can work on tables and columns.
- **Source of truth:** dbt reads ref() and source(). SQL lineage reads the SQL text.
- **Works without dbt:** no for dbt lineage, yes for SQL lineage.
- **Best question:** dbt lineage answers "what is the build order and which models depend on this one?". SQL lineage answers "which columns feed this column, and what breaks if I change it?".
Where each one falls short
dbt lineage cannot see a column, a table referenced by name outside ref(), or anything that is not part of a dbt project. SQL lineage works from text, so it struggles where the SQL is generated: a macro that builds a column list, or dynamic SQL assembled from strings at run time. It also cannot know about objects in your warehouse that no loaded file creates.
Do you need both?
For a pure dbt project, the dbt graph covers the build order and model dependencies, and column lineage adds the answer to change questions. For a mixed estate of dbt models, stored procedures and scripts, SQL lineage is the one that covers all of it. In practice you want the model graph for orientation and the column view for changes.
How the SQL lineage analyzer combines them
The SQL lineage analyzer reads both. It follows ref() and source() as dbt does, so sources, staging models and marts appear as a graph, and it reads each SELECT to trace columns. It runs on the files alone, so there is no dbt run and no warehouse connection, and your SQL stays in your browser. dbt YAML files add descriptions and tests to the tables and columns. Limits: Jinja is not rendered, so macros are not expanded, and a column produced by a macro that generates columns is not followed.
From there, see how to visualize a dbt project without running dbt and table-level vs column-level lineage.
Related tool pages
- 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.
- SQL Query Visualizer: Free SQL query visualizer: paste a query or drop SQL files and see tables, joins and columns as a clear diagram. Runs in your browser, no upload.
Also try
How to use the SQL Lineage Analyzer: step by step
- Drop your dbt project or SQL folder into the SQL lineage analyzer.
- Use the graph for the model dependencies.
- Open Columns and pick a column to see what builds it and what reads it.
When to use the SQL Lineage Analyzer
- Decide which kind of lineage you need
- Explain the difference to a teammate
- Cover a project that mixes dbt and plain SQL
- Answer change questions that need columns
Example
Input: models/ folder: raw schema, staging views, marts, reports (7 .sql files)
Output: A graph of 10 tables and views, 40 column links and the order to run the files
Frequently asked questions
What is the difference between SQL lineage and dbt lineage?
dbt lineage is built from ref() and source() calls and connects models. SQL lineage reads the SQL itself, so it works without dbt and can trace individual columns.
Does dbt show column-level lineage?
The graph in dbt docs connects models, not columns. Column-level lineage needs the SELECT statements to be read, which is what SQL lineage tools do.
Can I use SQL lineage on a dbt project?
Yes. The SQL lineage analyzer follows ref() and source() and also traces columns, without running dbt.
Does SQL lineage work without dbt?
Yes. It reads plain SQL files with CREATE TABLE AS, views, INSERT ... SELECT and MERGE statements.
What does SQL lineage miss?
SQL that is generated at run time, such as macros that build columns or dynamic SQL, and any object that no loaded file creates.
Tip: If your question contains the word column, you need SQL lineage. If it contains the word run order, the model graph is enough.