Model dependencies and parallelism in dbt

Introduction

Model dependencies help dbt know which data models rely on others. Parallelism lets dbt run independent models at the same time to save time.

When you have multiple data models where some need results from others before running.

When you want to speed up your data build by running models that don't depend on each other at the same time.

When you want to avoid errors by making sure models run in the right order.

When you want to organize your data pipeline clearly by showing how models connect.

When you want to optimize resource use by running many models in parallel safely.

Syntax

dbt

# model_a.sql
select * from source_table

# model_b.sql
select * from {{ ref('model_a') }} where condition

# model_c.sql
select * from {{ ref('model_a') }}

# model_d.sql
select * from {{ ref('model_b') }} join {{ ref('model_c') }} on ...

# Run command with parallelism:
dbt run --models model_a model_b model_c model_d --threads 4

Use {{ ref('model_name') }} to tell dbt that one model depends on another.

The --threads option controls how many models run at the same time.

Examples

Here, active_customers depends on base_customers. dbt runs base_customers first.

dbt

# Example 1: Simple dependency
# base_customers.sql
select * from raw.customers

# active_customers.sql
select * from {{ ref('base_customers') }} where active = true

Since sales_data and product_data don't depend on each other, dbt can run them in parallel.

dbt

# Example 2: Parallel models with no dependencies
# sales_data.sql
select * from raw.sales

# product_data.sql
select * from raw.products

If you run dbt run without specifying models, dbt runs all models respecting dependencies.

dbt

# Example 3: Edge case - empty model list
# Running dbt with no models specified runs all models in dependency order.

A single model with no dependencies runs immediately and alone.

dbt

# Example 4: Single model with no dependencies
# standalone_model.sql
select 1 as id

Sample Program

This example shows four models with dependencies. Model B and C depend on A. Model D depends on B and C. Running with 4 threads lets dbt run independent models at the same time.

dbt

# dbt_project.yml
name: 'my_project'
version: '1.0'

# models/my_project/model_a.sql
select 1 as id

# models/my_project/model_b.sql
select id from {{ ref('model_a') }} where id = 1

# models/my_project/model_c.sql
select id from {{ ref('model_a') }}

# models/my_project/model_d.sql
select b.id from {{ ref('model_b') }} b join {{ ref('model_c') }} c on b.id = c.id

# Command to run models with parallelism
# dbt run --threads 4

# Expected output in terminal:
# Running with dbt=1.x.x
# Found 4 models, 0 tests, 0 snapshots, 0 analyses, 0 macros
# 
# 1 of 4 START table model my_project.model_a................ [RUN]
# 1 of 4 OK created table model my_project.model_a........... [OK in 0.1s]
# 2 of 4 START table model my_project.model_b................ [RUN]
# 3 of 4 START table model my_project.model_c................ [RUN]
# 2 of 4 OK created table model my_project.model_b........... [OK in 0.1s]
# 3 of 4 OK created table model my_project.model_c........... [OK in 0.1s]
# 4 of 4 START table model my_project.model_d................ [RUN]
# 4 of 4 OK created table model my_project.model_d........... [OK in 0.1s]
# 
# Finished running 4 table models in 1.0s.

Important Notes

Time complexity depends on the number of models and their dependencies; dbt builds a graph to manage order.

Space complexity is mainly the storage used by the models' data.

Common mistake: forgetting to use {{ ref() }} causes dbt to run models in wrong order or fail.

Use parallelism to speed up builds when models are independent; use dependencies to ensure correct order.

Summary

Model dependencies tell dbt which models need others to run first.

Parallelism lets dbt run models without dependencies at the same time to save time.

Use {{ ref('model_name') }} to set dependencies and --threads to control parallel runs.