dbt State 설정

dbt State 설정 (dbt State configurations)

dbt State를 활성화한 상태로 dbt 명령을 실행하면, dbt는 이전 빌드와 노드의 로직·데이터를 비교해 가장 효율적인 경로를 선택해요. 재사용(reuse), 복제(clone), 일반 빌드(normal build) 세 가지 중 상황에 맞는 길을 고르죠. 이 문서는 dbt State가 그 결정을 내릴 때 사용하는 설정들을 정리해요.

출처: 문서

본문

dbt State를 활성화하고 dbt 명령을 실행하면, dbt는 노드의 로직과 데이터를 이전 빌드와 비교해 가장 효율적인 경로를 선택해요:

  • 재사용(Reuse): 객체가 타깃 스키마에 존재하고, 로직이 바뀌지 않았으며, 부모가 lag_tolerance를 넘는 신선한 데이터를 받지 않았다면 노드를 재사용해요.
  • 복제(Clone): 재사용이 불가능하지만 지연 환경(deferred environment)에 같은 로직과 충분히 신선한 데이터가 있는 객체가 존재한다면 dbt State가 그것을 복제해요.
  • 일반 빌드(Normal build): 재사용도 복제도 불가능하다면 노드를 평소처럼 빌드해요. 선택되지 않은 업스트림 노드는 deferral을 사용해요.

dbt State가 이런 결정을 내릴 때는 다음 설정을 사용해요.

models:
  +state:
    lag_tolerance: <duration>
    compare_unrendered_code: true | false
    require_fresh_data_from: any | all
    evaluate_volatile_sql: true | false
    pre_clone: never | if_missing | always
    execute_hooks_on_any_reuse: true | false

models:
  - name: <model_name>
    config:
      state:
        lag_tolerance: <duration>
        compare_unrendered_code: true | false
        require_fresh_data_from: any | all
        evaluate_volatile_sql: true | false
        pre_clone: never | if_missing | always
        execute_hooks_on_any_reuse: true | false

{{ config(
    state={
        "lag_tolerance": "<duration>",
        "compare_unrendered_code": true | false,
        "require_fresh_data_from": "any" | "all",
        "evaluate_volatile_sql": true | false,
        "pre_clone": "never" | "if_missing" | "always",
        "execute_hooks_on_any_reuse": true | false
    }
) }}

프로필 레벨 설정은 profiles.yml에 구성되며 특정 타깃 환경에 적용돼요:

my_project:
  outputs:
    dev:
      type: snowflake
      # ... dev connection settings
      defer_to_target: prod  # self-managed only
    prod:
      type: snowflake
      # ... prod connection settings
      allow_clones: true | false
      metadata_warehouse: <warehouse_name>  # Snowflake only
  target: dev
설정 기본값 범위 설명
lag_tolerance 45m 노드·폴더·프로젝트 레벨 (model config) 마지막 업스트림 데이터 변경 이후 노드가 재빌드 대상이 되기까지 지나야 하는 시간. 빌드를 freshness SLA에 맞추는 컴퓨팅 절약 버퍼 역할을 해요. 데이터 신선도에만 적용되며, SQL 변경은 이 설정과 무관하게 항상 재빌드를 일으켜요.
compare_unrendered_code false 노드·폴더·프로젝트 레벨 코드 변경 감지 시 dbt State가 Jinja 템플릿(렌더링 전 코드)과 렌더링된 SQL을 모두 확인할지를 제어해요. 매 실행 다른 렌더링된 SQL을 만들어내는 비결정적 매크로나 환경 변수가 있는 모델에 유용해요.
require_fresh_data_from any 노드·폴더·프로젝트 레벨 노드가 재빌드 대상이 되려면 직접 부모 중 일부(any) 또는 전부(all)에 신선한 데이터가 필요한지 여부.
pre_clone if_missing 노드·폴더·프로젝트 레벨 dbt State가 실행 전에 프로덕션을 복제해 incremental 모델과 스냅샷을 미리 채울지 여부.
execute_hooks_on_any_reuse false 노드·폴더·프로젝트 레벨 노드가 재빌드 없이 재사용될 때 pre-/post-hook이 실행될지 여부.
evaluate_volatile_sql false 노드·폴더·프로젝트 레벨 재빌드 여부 결정 시 dbt State가 volatile SQL 함수의 런타임 출력을 저장·비교할지 여부.
defer_to_target prod 프로필 (셀프 매니지드 전용) dbt State가 deferral할 프로필 타깃.
allow_clones true 프로필 dbt State가 타깃에 테이블을 복제할 수 있는지 여부. 예를 들어 프로덕션에서 false로 설정하면 dev 테이블을 프로덕션으로 복제하는 것을 막아요.
metadata_warehouse 프로필 웨어하우스 프로필 (Snowflake 전용) dbt State 메타데이터 조회용 별도 웨어하우스. 설정하면 하나의 통합 쿼리 대신 여러 개의 개별 쿼리(스키마당 하나)를 발행해요.

더 알아보기 (Learn more)