모델 구성

모델 구성 (Model configurations)

모델에 적용할 수 있는 config들을 다뤄요. 모델별 구성, 일반 구성, 웨어하우스별 구성이 있으며, dbt_project.yml·속성 파일·SQL 파일에서 계층적으로 적용돼요.

출처: 문서

본문

관련 문서 — Models, run command

사용 가능한 구성 (Available configurations)

모델별 구성 (Model-specific configurations)

리소스별 구성은 여러 리소스 유형이 아닌 dbt 리소스 유형 하나에만 적용돼요. 이 설정을 프로젝트 파일(dbt_project.yml), 속성 파일(모델이면 models/properties.yml, 다른 리소스도 마찬가지), 또는 리소스의 파일 안에서 {{ config() }} 매크로로 정의할 수 있어요.

다음 리소스별 구성은 모델에만 사용할 수 있어요:

Project file · Property file · SQL file config

dbt_project.yml (dbt v1.12 이상)

models:
  <resource-path>:
    +materialized: <materialization_name>
    +sql_header: <string>
    +on_configuration_change: apply | continue | fail # only for materialized views on supported adapters
    +unique_key: <column_name_or_expression>
    +freshness: <dict>
    +on_error: skip_children | continue
    +latest_version_pointer: <dict>

models/properties.yml (dbt v2.0 이상)

models:
  - name: [<model-name>]
    config:
      materialized: <materialization_name>
      sql_header: <string>
      on_configuration_change: apply | continue | fail # only for materialized views on supported adapters
      unique_key: <column_name_or_expression>
      freshness:
        warn_after: {count: 24, period: hour}
        error_after: {count: 48, period: hour}
        build_after: <dict>
        # build scheduling — Enterprise only
      loaded_at_field: updated_at  # or loaded_at_query
      on_error: skip_children | continue
      latest_version_pointer: <dict>

models/<model_name>.sql (dbt v1.12 이상)

{{ config(
    materialized="<materialization_name>",
    sql_header="<string>"
    on_configuration_change: apply | continue | fail # only for materialized views for supported adapters
    unique_key='column_name_or_expression'
    freshness=<dict>
    on_error="skip_children" | "continue"
    latest_version_pointer=<dict>) }}

일반 구성 (General configurations)

일반 구성은 여러 리소스 유형에 걸쳐 적용되는 더 넓은 운영 설정을 제공해요. 리소스별 구성과 마찬가지로 프로젝트 파일, 속성 파일, 또는 리소스별 파일에서 설정할 수 있어요.

Project file · Property file · SQL file config

dbt_project.yml (dbt v1.9 이상)

models:
  <resource-path>:
    +enabled: true | false
    +tags: <string> | [<string>]
    +pre-hook: <sql-statement> | [<sql-statement>]
    +post-hook: <sql-statement> | [<sql-statement>]
    +database: <string>
    +schema: <string>
    +alias: <string>
    +persist_docs: <dict>
    +full_refresh: <boolean>
    +meta: {<dictionary>}
    +grants: {<dictionary>}
    +contract: {<dictionary>}
    +event_time: my_time_field

models/properties.yml (dbt v1.9 이상)

models:
  - name: [<model-name>]
    config:
      enabled: true | false
      tags: <string> | [<string>]
      pre_hook: <sql-statement> | [<sql-statement>]
      post_hook: <sql-statement> | [<sql-statement>]
      database: <string>
      schema: <string>
      alias: <string>
      persist_docs: <dict>
      full_refresh: <boolean>
      meta: {<dictionary>}
      grants: {<dictionary>}
      contract: {<dictionary>}
      event_time: my_time_field

models/<model_name>.sql (dbt v1.9 이상)

{{ config(
    enabled=true | false,
    tags="<string>" | ["<string>"],
    pre_hook="<sql-statement>" | ["<sql-statement>"],
    post_hook="<sql-statement>" | ["<sql-statement>"],
    database="<string>",
    schema="<string>",
    alias="<string>",
    persist_docs={<dict>},
    meta={<dict>},
    grants={<dict>},
    contract={<dictionary>},
    event_time='my_time_field',
) }}

웨어하우스별 구성 (Warehouse-specific configurations)

• BigQuery configurations
• Redshift configurations
• Snowflake configurations
• Databricks configurations
• Spark configurations

모델 구성하기 (Configuring models)

모델 구성은 계층적으로 적용돼요. 설치된 패키지 안에서와 dbt 프로젝트 안에서 다음과 같은 방법으로(우선순위 순서) 모델을 구성할 수 있어요:

1. 모델 안에서 config() Jinja 매크로 사용.
2. .yml 파일에서 config 리소스 속성 사용.
3. 프로젝트 YAML 파일(dbt_project.yml)의 models: 키 아래. 이 경우 가장 깊게 중첩된 모델이 가장 높은 우선순위를 가져요.

가장 구체적인 구성이 항상 우선해요. 프로젝트 YAML 파일에서 예를 들어 marketing 하위 디렉터리에 적용된 구성이 전체 jaffle_shop 프로젝트에 적용된 구성보다 우선해요. 모델이나 모델 디렉터리에 구성을 적용하려면 리소스 경로를 중첩된 사전 키로 정의해요.

루트 dbt 프로젝트의 모델 구성은 설치된 패키지의 구성보다 우선순위가 높아요. 이를 통해 설치된 패키지의 구성을 덮어써 dbt 실행을 더 잘 제어할 수 있어요.

예시 (Example)

dbt_project.yml에서 모델 디렉터리 구성하기

dbt_project.yml 파일에서 모델을 구성하려면 models: 구성 옵션을 사용해요. 구성을 프로젝트 이름으로 네임스페이스하세요 (아래 참조):

dbt_project.yml

name: dbt_labs
models:
  # Be sure to namespace your model configs to your project name
  dbt_labs:
    # This configures models found in models/events/
    events:
      +enabled: true
      +materialized: view
      # This configures models found in models/events/base
      # These models will be ephemeral, as the config above is overridden
      base:
        +materialized: ephemeral
      ...

한 모델에만 구성 적용하기

일부 유형의 구성은 특정 모델에만 해당돼요. 이 경우 dbt_project.yml에 구성을 두는 것은 부적절할 수 있어요. 대신 모델 .sql 파일 맨 위나 개별 YAML 속성에 이 구성을 지정할 수 있어요.

models/events/base/base_events.sql

{{
  config(
    materialized = "table",
    tags = ["core", "events"]
  )
}}
select * from {{ ref('raw_events') }}

models/events/base/properties.yml

models:
  - name: base_events
    description: "Standardized event data from raw sources"
    columns:
      - name: user_id
        description: "Unique identifier for a user"
        data_tests:
          - not_null
          - unique
      - name: event_type
        description: "Type of event recorded (click, purchase, etc.)"

(dbt v2.0 이상) 모델 freshness 구성

freshness config를 다음 방법으로 사용할 수 있어요:

• Freshness SLA (warn_after, error_after): 이 모델의 데이터가 얼마나 오래돼도 되는지 선언해요. dbt freshness를 실행하면 dbt가 이 임계값을 평가하고 Pass, Warn, Error를 보고해요. 지원 범위는 materialization과 측정 방법에 따라 달라져요. 측정 방법 표를 참고하세요.
• 빌드 스케줄링 (build_after): 마지막 빌드 이후 업스트림 데이터가 변경되지 않으면 모델 재빌드를 건너뛰어요. dbt 플랫폼 Enterprise 등급에서만 사용할 수 있어요.

models/my_model.yml

models:
  - name: stg_orders
    config:
      freshness:
        # Freshness SLA — report warn/error when data is stale
        warn_after: {count: 24, period: hour}
        error_after: {count: 48, period: hour}
        # Build scheduling — Enterprise only
        build_after:
          count: 6
          period: hour
          updates_on: any  # optional
      loaded_at_field: updated_at  # or loaded_at_query

더 알아보기 (Learn more)

• Models — 모델 빌드
• run command — dbt run 명령