config 정의하기

dbt 프로젝트에서 리소스에 대한 구성을(configuration) 어떻게 정의하는지 배워요.

리소스 유형에 따라, dbt 프로젝트와 설치된 패키지에서 다음 방법으로 구성을 정의할 수 있어요:

출처: 문서

본문

(앱: dbt v1.9 이상)

.yml 파일에서 config 속성을 사용해 models/, snapshots/, seeds/, analyses, tests/ 등 지원되는 리소스 디렉터리에 대해 정의
dbt_project.yml 파일에서 해당 리소스 키(models:, snapshots:, data_tests: 등) 아래 정의

Config 상속

가장 구체적인 config가 항상 우선해요. 일반적으로 위 순서를 따르며, 파일 안의 config() 블록 --> .yml 파일에 정의된 속성 --> 프로젝트 파일에 정의된 config 순이에요.

참고 - 제네릭 데이터 테스트는 구체성(specificity)에서 조금 다르게 동작해요. test configs를 참고해요.

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

루트 dbt 프로젝트의 구성은 설치된 패키지의 구성보다 높은 우선순위를 가져요. 이 덕분에 설치된 패키지의 구성을 오버라이드할 수 있어 dbt 실행을 더 잘 제어할 수 있어요.

Config 결합하기

대부분의 구성은 계층적으로 적용될 때 "덮어써져(clobber)"요. 더 구체적인 값을 쓸 수 있으면 덜 구체적인 값을 완전히 대체해요. 단, 일부 config는 다른 병합 동작을 가져요:

tags는 addtive(덧셈적)이에요. 모델이 dbt_project.yml에 일부 태그를 구성하고 .sql 파일에 더 많은 태그를 적용하면, 최종 태그 집합에는 모두 포함돼요.
freshness config를 쓸 때, 더 구체적인 키-값 쌍이 같은 키의 덜 구체적인 값을 대체해요.
pre-hook과 post-hook도 additive예요.
meta 사전은 shallow-merged(얕은 병합)돼요. dbt는 최상위 키만 병합하고 중첩 사전 안은 들여다보지 않아요. 같은 최상위 키가 둘 이상의 레벨에 나타나면, 더 구체적인 값이 덜 구체적인 값을 완전히 대체해요 — 그 값 자체가 사전이어도 마찬가지예요. 한 레벨에만 나타나는 최상위 키는 유지돼요. 예를 들어 dbt_project.yml이 다음과 같이 설정하면:
```
+meta: {owner: "alice", dagster: {automation_condition: "eager"}}
```
그리고 모델이 다음과 같이 설정하면:
```
meta: {dagster: {asset_key: "my_key"}}
```
결과는 다음과 같아요:
```
{owner: "alice", dagster: {asset_key: "my_key"}}
```
owner는 한 레벨에만 나타나므로 유지돼요. dagster는 양쪽 레벨에 나타나므로 더 구체적인 값이 그대로 대체해요. 그리고 병합은 dagster 안을 절대 들여다보지 않기 때문에 중첩된 automation_condition은 사라져요. 깊은(재귀적) 병합이라면 중첩 키를 결합해 dagster: {automation_condition: "eager", asset_key: "my_key"}를 만들었을 거예요. meta는 이렇게 하지 않아요 — 중첩 사전은 병합이 아니라 대체돼요.

레벨 간 어떤 config가 이기나

여러 레벨에서 상속된 config를 clobber·병합할 때 일반 규칙은 다음과 같아요:

노드 레벨 config(더 구체적)는 프로젝트 레벨 config(덜 구체적)를 clobber해요.
소스의 경우 테이블 레벨 config(더 구체적)는 소스 레벨 config(덜 구체적)를 clobber해요.
dbt_project.yml의 루트 프로젝트 구성은 패키지 파일 안의 구성을 clobber해요. 이는 사용자가 dbt deps로 설치하는 패키지의 코드를 직접 편집하지 않고 그 패키지의 동작을 제어할 수 있게 하기 위함이에요.

`+` 접두사

dbt는 폴더 이름과 구성을 + 접두사로 구분해요. + 접두사는 config에 만 사용하며 dbt_project.yml에서 해당 리소스 키 아래 적용돼요. 다음에는 적용되지 않아요:

리소스 파일 안의 config() Jinja 매크로
.yml 파일의 config 속성

자세한 내용은 Using the + prefix를 참고해요.

예시

프로젝트에 sources와 models를 모두 정의하는 예시예요:

models/jaffle_shop.yml

version: 2

sources:
  - name: raw_jaffle_shop
    description: A replica of the postgres database used to power the jaffle_shop app.
    tables:
      - name: customers
        columns:
          - name: id
            description: Primary key of the table
            data_tests:
              - unique
              - not_null

      - name: orders
        columns:
          - name: id
            description: Primary key of the table
            data_tests:
              - unique
              - not_null

          - name: user_id
            description: Foreign key to customers

          - name: status
            data_tests:
              - accepted_values:
                  arguments: # available in v1.10.5 and higher. Older versions can set the <argument_name> as the top-level property.
                    values: ['placed', 'shipped', 'completed', 'return_pending', 'returned']


models:
  - name: stg_jaffle_shop__customers #  Must match the filename of a model -- including case sensitivity.
    config:
      tags: ['pii']
    columns:
      - name: customer_id
        data_tests:
          - unique
          - not_null

  - name: stg_jaffle_shop__orders
    config:
      materialized: view
    columns:
      - name: order_id
        data_tests:
          - unique
          - not_null
      - name: status
        data_tests:
          - accepted_values:
              arguments: # available in v1.10.5 and higher. Older versions can set the <argument_name> as the top-level property.
                values: ['placed', 'shipped', 'completed', 'return_pending', 'returned']
              config:
                severity: warn

FAQ

테스트와 설명이 들어 있는 .yml 파일 이름을 schema.yml로 지어야 하나요?

아니요! 다음 조건만 만족하면 어떤 이름이든 쓸 수 있어요(whatever_you_want.yml 포함):

파일이 models/ 디렉터리에 있고¹
파일 확장자가 .yml이면 돼요

자세한 내용은 docs를 참고해요.

¹seed, snapshot, macro의 속성을 선언한다면 그 관련 디렉터리(seeds/, snapshots/, macros/ 각각)에도 이 파일을 둘 수 있어요.

이 파일들 이름을 마음대로 지을 수 있다면 뭐라고 지어야 하나요?

그건 여러분 마음이에요! 몇 가지 옵션이 있어요:

기존 용어를 기본으로: schema.yml(다만 시간이 지나면 올바른 파일을 찾기 어려워질 수 있어요)
디렉터리와 같은 이름 사용(디렉터리 이름을 분별 있게 지었다면)
파일당 모델(또는 seed, snapshot, macro 등) 하나를 테스트·문서화한다면 모델과 같은 이름을 줄 수 있어요

팀에 맞는 걸 선택하세요. dbt 프로젝트 구조화 가이드에 더 많은 권장 사항이 있어요.

리소스 속성을 선언할 때 별도 파일을 써야 하나요, 아니면 하나의 큰 파일을 써야 하나요?

그건 여러분 마음이에요:

어떤 사람들은 모델(또는 source / snapshot / seed 등) 하나당 파일 하나가 유용하다고 해요
어떤 사람들은 디렉터리 하나당 파일 하나가 유용하고, 한 파일에서 여러 모델을 문서화·테스트한다고 해요

팀에 맞는 걸 선택하세요. dbt 프로젝트 구조화 가이드에 더 많은 권장 사항이 있어요.

SQL config 블록에 테스트와 설명을 추가할 수 있나요?

dbt는 config() 블록과 dbt_project.yml 외에도 YAML 파일에서 노드 config를 정의할 수 있어요. 하지만 그 반대는 항상 그렇진 않아요. .yml 파일에는 그곳에서만 정의할 수 있는 것들이 있거든요.

특정 속성은 다음 이유로 특별해요:

고유한 Jinja 렌더링 컨텍스트가 있어요
새 프로젝트 리소스를 만들어요
계층적 구성으로 말이 안 돼요
아직 config로 재정의되지 않은 오래된 속성이에요

이 속성들은 다음과 같아요:

description
tests
docs
columns
quote
source properties (예: loaded_at_field, freshness)
exposure properties (예: type, maturity)
macro properties (예: arguments)

모델·소스 YAML 파일이 왜 항상 version: 2로 시작하나요?

옛날엔 이 .yml 파일들의 구조가 아주 달랐어요(그때 dbt를 쓰던 분들 화이팅!). version: 2를 추가하면서 이 구조를 더 확장 가능하게 만들 수 있었어요.

dbt v1.5부터 모든 리소스 YAML 파일에서 최상위 version: 키는 선택 사항이에요. 있으면 version: 2만 지원돼요.

또한 v1.5부터는 dbt_project.yml의 config-version: 2와 최상위 version: 키도 선택 사항이에요.

리소스 YAML 파일은 현재 이 config를 요구하지 않아요. 지정하면 version: 2만 지원해요. 곧 YAML 파일을 version: 3으로 업데이트할 계획은 없지만, 이 config가 있으면 미래에 새 구조를 도입하기 쉬워져요.

YAML 파일 확장자를 쓸 수 있나요?

아니요. 현재 dbt는 .yml 확장자 파일만 검색해요. 향후 dbt 릴리스에서는 .yaml 확장자 파일도 검색할 거예요.

일반적인 에러 해결

[모델 이름]에 주어진 잘못된 테스트 config

이 에러는 .yml 파일이 dbt가 기대하는 구조와 일치하지 않을 때 발생해요. 전체 에러 메시지는 대략 이렇게 보일 수 있어요:

* Invalid test config given in models/schema.yml near {'namee': 'event', ...}
  Invalid arguments passed to "UnparsedNodeUpdate" instance: 'name' is a required property, Additional properties are not allowed ('namee' was unexpected)

장황하지만, 이런 에러는 문제를 찾는 데 도움이 돼요. 여기서 name 필드가 실수로 namee로 제공됐어요. 이 에러를 고치려면 .yml이 이 가이드에 설명된 기대 구조와 일치하는지 확인해요.

schema.yml 파일의 잘못된 구문

.yml 파일이 유효한 YAML이 아니면 dbt는 이런 에러를 보여줘요:

Runtime Error
  Syntax error near line 6
  ------------------------------
  5  |   - name: events
  6  |     description; "A table containing clickstream events from the marketing website"
  7  |

  Raw Error:
  ------------------------------
  while scanning a simple key
    in "<unicode string>", line 6, column 5:
          description; "A table containing clickstream events from the marketing website"
          ^

이 에러는 description 필드 뒤에 콜론(:) 대신 실수로 세미콜론(;)이 쓰였기 때문에 발생했어요. 이런 문제를 해결하려면 에러 메시지에 언급된 .yml 파일을 찾아 그 안의 구문 에러를 고치세요. 온라인 YAML 검증기가 도움이 될 수 있지만, 민감한 정보를 서드파티 앱에 제출하는 것은 주의하세요!

더 알아보기 (Learn more)

config는 계층적으로 상속되고 가장 구체적인 값이 우선해요. 루트 프로젝트가 패키지보다 우선이에요.
관련 개념: define-properties, dbt_project.yml.

config 정의하기