properties 정의하기

properties.yml 파일에서 리소스에 대한 속성(properties)을 어떻게 정의하는지 배워요.

dbt에서는 properties.yml 파일을 사용해 리소스의 속성을 정의할 수 있어요. 리소스와 같은 디렉터리의 .yml 파일에서 속성을 선언할 수 있어요. 이 파일 이름을 whatever_you_want.yml로 지을 수 있고, 각 디렉터리 안의 하위 폴더에 자유롭게 중첩할 수 있어요.

속성은 설명하는 리소스 옆의 전용 경로에 정의하는 걸 강력히 권장해요.

출처: 문서

본문

참고 — schema.yml 파일 — 이전 버전의 문서에서는 이 파일들을 schema.yml이라고 불렀어요. 데이터베이스 이야기를 할 때 schema라는 단어가 다른 의미로 쓰이기도 하고, 사람들이 꼭 schema.yml로 이름을 지어야 한다고 생각하는 경우가 많아서 이 용어에서 벗어났어요. 대신 지금은 이 파일들을 properties.yml 파일이라고 불러요. (물론 여전히 자유롭게 schema.yml로 이름 지을 수 있어요)

config가 아닌 속성은?

dbt에서는 config() 블록과 dbt_project.yml 외에도 properties.yml 파일에서 노드 config를 정의할 수 있어요. 하지만 일부 특별한 속성은 .yml 파일에서만 정의할 수 있고 config() 블록이나 dbt_project.yml 파일로는 구성할 수 없어요:

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

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

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

columns
deprecation_date
description
quote
source properties (예: loaded_at_field)
exposure properties (예: type, maturity)
- 대부분의 exposure 속성은 properties.yml 파일에서 직접 구성해야 하지만, enabled config는 dbt_project.yml의 프로젝트 레벨에서 설정할 수 있어요.
macro properties (예: arguments)
tests
versions

예시

프로젝트에 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)

properties.yml 파일로 설명·테스트·컬럼 등 속성을 정의하고, config는 별도로 설정해요.
관련 개념: define-configs, configs and properties.

properties 정의하기