dbt build 명령어

dbt build 명령어는 DAG 순서로 선택된 리소스 또는 전체 프로젝트에 대해 모델 실행·테스트·스냅샷·시드·사용자 정의 함수를 빌드해요. 단일 실행으로 하나의 manifest와 하나의 run results 아티팩트를 생성해요.

출처: 문서

본문

dbt build 명령어는 다음을 수행해요:

모델 실행
테스트 실행
스냅샷 실행
시드 실행
사용자 정의 함수 빌드(dbt v1.11 이상)

DAG 순서로, 선택된 리소스 또는 전체 프로젝트에 대해.

상세

Artifacts: build 작업은 단일 manifest와 단일 run results 아티팩트를 기록해요. run results에는 빌드하도록 선택된 모든 모델·테스트·시드·스냅샷에 대한 정보가 하나의 파일로 합쳐져 포함돼요.

(dbt v2.0 이상 적용) dbt Information Schema: --generate-info-schema를 사용해 dbt Information Schema를 버전이 있는 하위 디렉터리(현재 v1/)의 target/info_schema/에 기록해요. Information Schema는 프로젝트의 메타데이터를 쿼리 가능한 SQL 테이블(데이터베이스의 INFORMATION_SCHEMA와 유사)로 노출해서, manifest.json을 파싱하지 않고도 모델·소스 등을 조회할 수 있어요.

dbt build --generate-info-schema

dbt.node_columns와 dbt.column_lineage에 컬럼 타입과 컬럼 레벨 계통을 채우려면 --static-analysis strict를 결합하세요. 없으면 dbt.node_columns·dbt.column_lineage에는 컬럼 타입과 계통이 없어요.

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

실패 시 건너뛰기(Skipping on failures): 업스트림 리소스의 테스트는 다운스트림 리소스가 실행되지 않도록 막으며, 테스트 실패는 그 다운스트림 리소스를 완전히 건너뛰게 해요. 예를 들어 model_b가 model_a에 의존하는데 model_a의 unique 테스트가 실패하면 model_b는 SKIP돼요. 테스트가 건너뜀을 유발하지 않게 하려면? 심각도나 임계값을 warn으로 조정하세요 (error 대신). 여러 부모가 있고 한 부모가 다른 부모에 의존하는 테스트(예: model_a + model_b 사이의 relationships 테스트)의 경우, 그 테스트는 가장 다운스트림 부모(model_b)의 자식만 막고 건너뛰게 해요. 서로 독립적인 여러 부모가 있는 테스트라면 dbt는 노드가 그 부모 모두에 의존하는 경우에만 다운스트림 노드를 건너뛰어요. (dbt v2.0 이상 적용)

Checks: dbt build는 모델을 컴파일하거나 실행하기 전에 check를 실행해요. check는 dbt Information Schema에 대해 작성하는 SQL 쿼리로 팀의 프로젝트 표준을 강제해요. 예를 들어 모든 모델에 설명이 있는지가 check일 수 있어요. 쿼리가 행을 반환하지 않으면 check는 통과해요. 실패한 check는 check의 severity가 warn으로 설정되지 않았다면 anything materialized 전에 빌드를 멈춰요. (dbt v1.12 이상 적용)

모델 오류 시 건너뛰기: 기본적으로 모델이 실패하면 모든 다운스트림 모델이 건너뛰어져요. 모델에 on_error: continue를 설정하면 그 모델이 실패해도 다운스트림 모델이 실행되도록 허용할 수 있어요. (dbt v1.12 이상 적용)

리소스 선택: build 작업은 표준 선택 문법(--select, --exclude)과, 최종 필터를 제공하는 --resource-type 플래그(list처럼)를 지원해요. 선택된 리소스가 무엇이든 그 리소스를 build가 실행/테스트/스냅샷/시드해요. 테스트는 간접 선택을 지원하므로 dbt build -s model_a는 model_a를 실행하고 테스트도 한다는 걸 기억하세요. 그게 무슨 뜻일까요? model_a에 직접 의존하는 모든 테스트는, 그 테스트가 다른 선택되지 않은 부모에도 의존하지 않는 한 포함돼요. 자세한 내용과 예시는 test selection을 참고하세요.

Flags: build 작업은 run, test, snapshot, seed와 같은 모든 플래그를 지원해요. 여러 작업 간 공유되는 플래그(예: --full-refresh)는 지원하는 모든 선택된 리소스 유형에 같은 값을 사용해요(예: 모델과 시드가 모두 full refresh됨).

스냅샷은 full refresh를 무시해요. 스냅샷은 full_refresh config와 --full-refresh 플래그를 모두 무시해요. dbt build --full-refresh나 dbt snapshot --full-refresh 같은 명령어가 스냅샷 노드를 포함하면 스냅샷은 정상적으로 실행되며, 스냅샷 테이블을 drop·재생성하지 않아 기존 스냅샷 이력이 보존돼요. (dbt v2.0 이상 적용)

`--skip-checks` 플래그

build 명령어는 check 게이트를 우회하는 --skip-checks를 지원해요.

dbt build --skip-checks

전체 게이트 대신 단일 check를 비활성화하려면 그 check의 설정에 enabled: false를 설정하세요:

checks:
  - name: all_models_have_descriptions
    config:
      enabled: false

`--empty` 플래그

build 명령어는 스키마 전용 드라이런을 위해 --empty 플래그를 지원해요. --empty 플래그는 refs와 sources를 0행으로 제한해요. dbt는 여전히 target 데이터 웨어하우스에 대해 모델 SQL을 실행하지만 입력 데이터의 값비싼 읽기는 피해요. 이는 의존성을 검증하고 모델이 제대로 빌드되도록 보장해요.

렌더 메서드

.render() 메서드는 일반적으로 런타임 중 Jinja 표현식(예: {{ source(...) }})을 해결(error)하는 데 사용돼요. --empty 플래그를 사용할 때 dbt는 최적화를 위해 ref()나 source() 처리를 건너뛸 수 있어요. 컴파일 오류를 피하고 특정 관계(ref() or source())를 처리하도록 dbt에 명시적으로 지시하려면 모델 파일에서 .render() 메서드를 사용하세요. 예를 들어:

models.sql

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

select ...

테스트

dbt build가 단위 테스트와 함께 실행될 때 모델은 계보(lineage)와 의존성에 따라 처리돼요. 테스트는 다음과 같이 실행돼요:

단위 테스트는 SQL 모델에 대해 실행돼요.
모델이 구체화돼요.
데이터 테스트는 모델에 대해 실행돼요.

이렇게 하면 단위 테스트가 성공적으로 통과할 때만 모델이 구체화되므로 웨어하우스 비용이 절약돼요. 단위 테스트와 데이터 테스트는 dbt build에 --select test_type:unit 또는 --select test_type:data로 선택할 수 있어요(--exclude 플래그도 동일).

예시

$ 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) — dbt v1.11 이상에서 사용 가능 build 명령어는 DAG 실행의 일부로 사용자 정의 함수를 빌드해요. 프로젝트에서 functions만 빌드·재빌드하려면 dbt build --select "resource_type:function"을 실행하세요. 예를 들어:

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)

dbt build 명령어