Skip to main content

About dbt build command

The dbt build command will:

In DAG order, for selected resources or an entire project.

Details​

Artifacts: The build task will write a single manifest and a single run results artifact. The run results will include information about all models, tests, seeds, and snapshots that were selected to build, combined into one file.

(Applies to dbt v2.0 and later)

dbt Information Schema: Use --generate-info-schema to write the dbt Information Schema to target/info_schema/ in a versioned subdirectory (currently v1/). The Information Schema exposes your project's metadata as queryable SQL tables (similar to a database's INFORMATION_SCHEMA) so you can query models, sources, and more without parsing manifest.json.

dbt build --generate-info-schema

To populate column types and column-level lineage in dbt.node_columns and dbt.column_lineage, combine with --static-analysis strict. Without it, dbt.node_columns and dbt.column_lineage contain no column types and no lineage.

dbt build --generate-info-schema --static-analysis strict

Skipping on failures: Tests on upstream resources will block downstream resources from running, and a test failure will cause those downstream resources to skip entirely. E.g. If model_b depends on model_a, and a unique test on model_a fails, then model_b will SKIP.

  • Don't want a test to cause skipping? Adjust its severity or thresholds to warn instead of error
  • In the case of a test with multiple parents, where one parent depends on the other (e.g. a relationships test between model_a + model_b), that test will block-and-skip children of the most-downstream parent only (model_b).
  • If you have a test with multiple parents that are independent of each other, dbt skips the downstream node only if that node depends on all of those parents.
(Applies to dbt v2.0 and later)

Checks: dbt build runs checks before it compiles or runs any models. Checks are SQL queries you write against the dbt Information Schema to enforce your team's project standards. For example, a check might be that every model has a description. A check passes when its query returns no rows. A failing check stops the build before anything is materialized, unless the check's severity is set to warn.

(Applies to dbt v1.12 and later)

Skipping on model errors: By default, if a model fails, all downstream models are skipped. Set on_error: continue on a model to allow its downstream models to run even when that model fails.

(Applies to dbt v1.12 and later)

Selecting resources: The build task supports standard selection syntax (--select, --exclude), as well as a --resource-type flag that offers a final filter (just like list). Whichever resources are selected, those are the ones that build will run/test/snapshot/seed.

  • Remember that tests support indirect selection, so dbt build -s model_a will both run and test model_a. What does that mean? Any tests that directly depend on model_a will be included, so long as those tests don't also depend on other unselected parents. See test selection for details and examples.

Flags: The build task supports all the same flags as run, test, snapshot, and seed. For flags that are shared between multiple tasks (e.g. --full-refresh), build will use the same value for all selected resource types that support it (e.g. both models and seeds will be full refreshed).

Snapshots ignore full refresh

Snapshots ignore both the full_refresh config and the --full-refresh flag. A command such as dbt build --full-refresh or dbt snapshot --full-refresh that includes a snapshot node runs the snapshot as normal — it won't drop or recreate the snapshot table, so existing snapshot history is preserved.

(Applies to dbt v2.0 and later)

The --skip-checks flag​

The build command supports --skip-checks to bypass the checks gate.

dbt build --skip-checks

To disable a single check rather than the entire gate, set enabled: false on that check's config:

checks:
  - name: all_models_have_descriptions
    config:
      enabled: false

The --empty flag​

The build command supports the --empty flag for building schema-only dry runs. The --empty flag limits the refs and sources to zero rows. dbt will still execute the model SQL against the target data warehouse but will avoid expensive reads of input data. This validates dependencies and ensures your models will build properly.

The render method​

The .render() method is generally used to resolve or evaluate Jinja expressions (such as {{ source(...) }}) during runtime.

When using the --empty flag, dbt may skip processing ref() or source() for optimization. To avoid compilation errors and to explicitly tell dbt to process a specific relation (ref() or source()), use the .render() method in your model file. For example:

models.sql
{{ config(
    pre_hook = [
        "alter external table {{ source('sys', 'customers').render() }} refresh"
    ]
) }}

select ...

Tests​

When dbt build is executed with unit tests applied, the models will be processed according to their lineage and dependencies. The tests will be executed as follows:

This saves on warehouse spend as the model will only be materialized if the unit tests pass successfully.

Unit tests and data tests can be selected using --select test_type:unit or --select test_type:data for dbt build (same for the --exclude flag).

Examples​

$ dbt build
Running with dbt=1.9.0-b2
Found 1 model, 4 tests, 1 snapshot, 1 analysis, 341 macros, 0 operations, 1 seed file, 2 sources, 2 exposures

18:49:43 | Concurrency: 1 threads (target='dev')
18:49:43 |
18:49:43 | 1 of 7 START seed file dbt_jcohen.my_seed............................ [RUN]
18:49:43 | 1 of 7 OK loaded seed file dbt_jcohen.my_seed........................ [INSERT 2 in 0.09s]
18:49:43 | 2 of 7 START view model dbt_jcohen.my_model.......................... [RUN]
18:49:43 | 2 of 7 OK created view model dbt_jcohen.my_model..................... [CREATE VIEW in 0.12s]
18:49:43 | 3 of 7 START test not_null_my_seed_id................................ [RUN]
18:49:43 | 3 of 7 PASS not_null_my_seed_id...................................... [PASS in 0.05s]
18:49:43 | 4 of 7 START test unique_my_seed_id.................................. [RUN]
18:49:43 | 4 of 7 PASS unique_my_seed_id........................................ [PASS in 0.03s]
18:49:43 | 5 of 7 START snapshot snapshots.my_snapshot.......................... [RUN]
18:49:43 | 5 of 7 OK snapshotted snapshots.my_snapshot.......................... [INSERT 0 5 in 0.27s]
18:49:43 | 6 of 7 START test not_null_my_model_id............................... [RUN]
18:49:43 | 6 of 7 PASS not_null_my_model_id..................................... [PASS in 0.03s]
18:49:43 | 7 of 7 START test unique_my_model_id................................. [RUN]
18:49:43 | 7 of 7 PASS unique_my_model_id....................................... [PASS in 0.02s]
18:49:43 |
18:49:43 | Finished running 1 seed, 1 view model, 4 tests, 1 snapshot in 1.01s.

Completed successfully

Done. PASS=7 WARN=0 ERROR=0 SKIP=0 TOTAL=7

Functions​

Available from dbt v1.11 and up

The build command builds user-defined functions as part of the DAG execution. To build or rebuild only functions in your project, run dbt build --select "resource_type:function". For example:

dbt build --select "resource_type:function"
dbt-fusion 2.0.1
 Succeeded [  0.98s] function dbt_schema.whoami (function)
 Succeeded [  1.12s] function dbt_schema.area_of_circle (function)

Was this page helpful?

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

0
Loading