Skip to main content

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:

  1. dbt run
  2. dbt 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 build Solution
  • 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:

  1. Source: raw_transactions
  2. Staging: stg_transactions
  3. 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:

  1. dbt run executes stg_transactions. (The duplicate data enters staging).
  2. dbt run executes fct_daily_balances. (The duplicate data propagates to the final fact table).
  3. The dbt run command finishes successfully.
  4. dbt test executes. It finds the duplicate in stg_transactions and 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:

  1. It builds stg_transactions.
  2. It immediately TESTS stg_transactions.
  3. The test FAILS (because of the duplicate).
  4. 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 run then dbt 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 run for fast, local developer iteration. Use dbt build for all CI/CD and Production orchestration schedules.