How to Understand dbt Model Dependencies (ref, source and the DAG)
Most dbt confusion comes down to one thing: not being sure what depends on what. The good news is that dbt makes dependencies explicit. Once you understand how ref() and source() create them, a project of any size becomes readable. This guide explains the mechanics, the common layers, and practical ways to read and check dependencies.
Open the dbt Model Dependency Graph
Dependencies come from two functions
A dbt model is a SQL select statement in its own file. When it needs data from another model, it calls ref(). When it needs a raw table that dbt does not build, it calls source().
-- models/marts/fct_orders.sql
select
o.order_id,
o.customer_id,
sum(p.amount) as total_revenue
from {{ ref('stg_orders') }} o
left join {{ ref('stg_payments') }} p using (order_id)
group by 1, 2Here fct_orders depends on stg_orders and stg_payments. dbt reads every ref() across the project, builds a directed graph and runs models in an order that respects it. That graph is the DAG: directed because each link has a direction, acyclic because a model cannot depend on itself through a loop.
Why ref() beats a hard-coded table name
If you wrote the table name directly, dbt would not know about the dependency. ref() both records it and resolves the correct schema for each environment. It is the reason lineage can be drawn from your code at all.
The usual layers
Most projects arrange models in layers, and dependencies mostly flow one way:
- Sources: raw tables loaded by other tools, declared with source().
- Staging: one model per source table that renames, casts and cleans.
- Intermediate: models that join or reshape staging models for reuse.
- Marts: business-ready tables, often facts and dimensions.
- Reporting: tables shaped for a specific dashboard or team.
Healthy projects rarely let a mart read directly from a source, or a staging model read from a mart. When you see arrows going against this flow, it is worth asking why.
Reading upstream and downstream
Two words do most of the work. Upstream means "what this model is built from". Downstream means "what is built from this model". Upstream explains why a number looks wrong, and downstream tells you what a change will affect.
In the dbt command line you can select by direction with a plus sign: +fct_orders means the model and everything upstream, and fct_orders+ means the model and everything downstream.
dbt ls --select +fct_orders # the model and its parents
dbt ls --select fct_orders+ # the model and its childrenSeeing it instead of listing it
Lists are accurate but hard to take in. A graph makes the same information visible at a glance. You can drop your models folder into a dbt lineage visualizer, click a model, and choose Upstream or Downstream to see exactly those sets highlighted. The tool reads ref() and source() from your SQL files, so it needs no warehouse connection.
Three dependency problems worth checking
Hidden fan-out
One staging model feeding twenty marts is a risk: a small change there touches everything. Click it and check the downstream count.
Skipped layers
A mart reading a source directly bypasses the cleaning done in staging, so the same raw column may be cast differently in two places.
Circular logic
dbt refuses to run a true cycle, but you can still have models that are almost circular through several steps. A lineage tool that flags circular dependencies helps you spot a tangled design early.
A short reading routine for any project
When you open an unfamiliar project, do this: find the final tables, follow one important column upstream to its source, then check what the most-used staging model feeds. In ten minutes you learn how the project is organised and where it is fragile.
For the click-by-click version, see how to visualize dbt project dependencies.
Reading dependencies in a pull request
Dependencies are most useful during review. When a pull request adds or changes a model, check three things in the graph. Does the new model depend only on models from the layer below it? Does it add a new source() that should be declared? And what is the downstream count of anything it modifies? A change to a model with one downstream consumer is routine. A change to a model with fifty needs an extra reviewer and a test plan.
Putting a screenshot or share link of the affected neighbourhood in the pull request description saves reviewers from reconstructing it themselves.
Limits to remember
Dependencies written with Jinja that builds a model name dynamically cannot be traced from the SQL text, and models that read tables outside dbt without source() will not appear as sources. Always check the list of unreadable statements a tool reports.
Open the dbt Model Dependency Graph
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 Model Dependency Graph: step by step
- Pick one important mart and list its ref() and source() calls.
- Follow each parent upstream until you reach sources.
- Check the downstream count of the most reused staging model.
When to use the dbt Model Dependency Graph
- Learn how dbt builds its dependency graph
- Check what a model is built from
- Find fragile, high fan-out models
- Review layer discipline in a project
Example
Input: models/ with ref() and source() calls
Output: A dependency graph with upstream and downstream views per model
Frequently asked questions
What is a dbt model dependency?
A dependency exists when one model selects from another model through ref(), or from a raw table through source(). dbt uses these to build the DAG and run models in order.
What does upstream and downstream mean in dbt?
Upstream is what a model is built from. Downstream is what is built from the model.
How do I see dbt dependencies without running dbt?
A tool that reads your SQL files can follow ref() and source() and draw the graph without a warehouse connection.
Why does my project have a model with hundreds of downstream models?
It is likely a widely reused staging or intermediate model. Check it carefully before changing it, because the change reaches everything downstream.
Tip: Use +model and model+ selectors for quick lists, and a graph when you need to explain the result to someone else.