dbt Defer Explained: How to Use --defer with a Practical Example

📘 Introduction

dbt --defer is useful when you want to test a small part of a dbt project without rebuilding all upstream models in your local or CI environment.

We use the same dlnerds_university Medallion Architecture example project from previous dbt posts, so the project structure stays familiar.

In this tutorial, you will learn dbt defer with a practical example. We will use dim_student, a Gold model in 03_gold, which depends on the Silver model student_cleaned in 02_silver.

The goal is simple: build or test dim_student locally while dbt can still use an already-built production version of student_cleaned when that upstream model does not exist in your local target schema.

💡 What is dbt defer?

dbt defer lets dbt resolve some ref() calls to objects from another environment, usually production, based on a previous dbt artifact such as manifest.json.

This helps when you only want to work on one model. Without defer, dbt may look for all referenced upstream models in your local target schema. If those upstream models were not built locally, your run can fail.

With --defer --state, dbt can use the manifest from a previous production run and point unselected upstream references to production objects when appropriate.

🧭 Example scenario

Imagine this project structure:

dlnerds_university/
├── dbt_project.yml
├── models/
│   ├── 01_bronze/
│   │   └── sources.yml
│   ├── 02_silver/
│   │   ├── student_cleaned.sql
│   │   └── student_cleaned.yml
│   └── 03_gold/
│       └── dim_student.sql
└── state/
    └── prod/
        └── manifest.json

You changed dim_student, but you do not want to build the upstream Silver model student_cleaned locally. You already have a production dbt artifact at state/prod/manifest.json.

This is a perfect use case for defer:

dbt build --select dim_student --defer --state state/prod

✅ Prerequisites

☑️ A working dbt project
☑️ Raw source tables already defined in models/01_bronze/sources.yml
☑️ The upstream model student_cleaned exists in production
☑️ A production dbt artifact such as state/prod/manifest.json is available
☑️ Basic knowledge of ref(), dbt build, and model selection

🎓 Want to go deeper with dbt?

If you want to understand dbt project structure, model dependencies, and production-style workflows in more detail, the Academy and the dbt book go deeper into hands-on dbt projects with practical examples.

If you’d like to dive deeper into dbt (data build tool), our book Building Modern Data Pipelines with dbt: From Raw Data to Gold Standard with the Medallion Architecture provides a hands-on guide to designing modern data pipelines. It covers dbt’s core concepts and best practices, including building Bronze, Silver, and Gold layers with the Medallion Architecture. It also serves as a hands-on study guide for the dbt Analytics Engineering Certification.

View on Amazon

⚙️1️⃣ Create the dim_student model