dbt build vs run + test
If you look at older dbt tutorials (from 2020 or earlier), you will constantly see instructors telling you to execute your pipeline using two separate commands:
dbt rundbt test
This is an outdated and dangerous workflow.
Modern dbt projects should almost exclusively use the dbt build command for production orchestration. Understanding the difference between these commands is critical for a Data Engineer.
Topics Covered
- The Flaw in
run+test - The
dbt buildSolution - Topological Execution Order
- When to use
dbt run
1. The Flaw in "run" + "test"
Let's assume our Indian banking app has a simple 3-step DAG:
- Source:
raw_transactions - Staging:
stg_transactions - Marts:
fct_daily_balances
Assume a bug in the source system creates a duplicate transaction record.
If you orchestrate your pipeline using the old method:
dbt run
dbt test
Here is exactly what happens:
dbt runexecutesstg_transactions. (The duplicate data enters staging).dbt runexecutesfct_daily_balances. (The duplicate data propagates to the final fact table).- The
dbt runcommand finishes successfully. dbt testexecutes. It finds the duplicate instg_transactionsand throws a bright red ERROR!
The Damage is Done: The test caught the error, but it was too late. The corrupt data has already been written to fct_daily_balances, and the CEO's Tableau dashboard is currently displaying inflated bank balances.
2. The dbt build Solution
In dbt version 1.0, dbt Labs introduced the dbt build command to solve this exact problem.
dbt build does everything. It runs models, seeds, snapshots, and tests—all in a single command. But the magic is in how it orders them.
dbt build
Here is exactly what happens with dbt build:
- It builds
stg_transactions. - It immediately TESTS
stg_transactions. - The test FAILS (because of the duplicate).
- dbt halts execution for this branch of the DAG. It explicitly SKIPS building
fct_daily_balances.
The Result: The test caught the error, and it prevented the corrupt data from reaching the final fact table. The CEO's dashboard is safe (it simply shows yesterday's clean data until the engineering team fixes the bug).
3. Topological Execution Order
dbt build executes nodes in strict topological order. It walks through your DAG node-by-node, executing the model, then executing the tests attached to that specific model, before moving on to the children.
If a test fails, all downstream children are skipped.
This is the concept of a Data Quality Gate, and it is the single most important architectural pattern in modern data engineering.
4. When to use dbt run
If dbt build is so superior, why do dbt run and dbt test still exist?
They are strictly developer tools.
If Developer Priya is writing a complex SQL macro locally in her sandbox environment, and she just wants to quickly compile and execute the SQL to see if there are syntax errors, she types dbt run. She doesn't want to wait 5 minutes for 100 data tests to execute while she is actively writing code.
However, once her code is merged into the main branch, the production orchestration tool (e.g., dbt Cloud or Apache Airflow) should strictly use dbt build.
Summary
- The Old Way (
dbt runthendbt test): Allows corrupt data to propagate to final presentation tables before the tests catch the error. - The Modern Way (
dbt build): Executes models and tests in topological order. If an upstream test fails, it skips downstream models, acting as a Data Quality Gate. - Use
dbt runfor fast, local developer iteration. Usedbt buildfor all CI/CD and Production orchestration schedules.