description 속성

description 속성

description 속성은 모델, 소스, 시드, 스냅샷, 분석, 매크로, 데이터 테스트, 유닛 테스트, 그룹 등을 문서화하기 위한 사용자 정의 설명이에요. dbt가 렌더링하는 문서 사이트에서 활용돼요.

출처: 문서

본문

models/schema.yml

models:
  - name: model_name
    description: markdown_string

    columns:
      - name: column_name
        description: markdown_string

models/schema.yml

sources:
  - name: source_name
    description: markdown_string

    tables:
      - name: table_name
        description: markdown_string

        columns:
          - name: column_name
            description: markdown_string

seeds/schema.yml

seeds:
  - name: seed_name
    description: markdown_string

    columns:
      - name: column_name
        description: markdown_string

snapshots/schema.yml

snapshots:
  - name: snapshot_name
    description: markdown_string

    columns:
      - name: column_name
        description: markdown_string

analysis/schema.yml

analyses:
  - name: analysis_name
    description: markdown_string

    columns:
      - name: column_name
        description: markdown_string

macros/schema.yml

macros:
  - name: macro_name
    description: markdown_string

    arguments:
      - name: argument_name
        description: markdown_string

( dbt v1.9 이상 적용) 단일 데이터 테스트나 제네릭 데이터 테스트에 설명을 추가할 수 있어요. tests/schema.yml

# Singular data test example
version: 2
data_tests:
  - name: data_test_name
    description: markdown_string

tests/schema.yml

# Generic data test example
version: 2
models:
  - name: model_name
    columns:
      - name: column_name
        data_tests:
          - unique:
              description: markdown_string

models/schema.yml

unit_tests:
  - name: unit_test_name
    description: "markdown_string"
    model: model_name 
    given: ts
      - input: ref_or_source_call
        rows:
         - {column_name: column_value}
         - {column_name: column_value}
         - {column_name: column_value}
         - {column_name: column_value}
      - input: ref_or_source_call
        format: csv
        rows: dictionary | string
    expect: 
      format: dict | csv | sql
      fixture: fixture_name

models/schema.yml

groups:
  - name: group_name
    description: markdown_string  # Supported in v1.10 and later
    owner:
      email: [email protected]

Definition

다음을 문서화하는 데 사용하는 사용자 정의 설명이에요:

  • 모델, 그리고 모델 컬럼
  • 소스, 소스 테이블, 소스 컬럼
  • 시드, 시드 컬럼
  • 스냅샷, 스냅샷 컬럼
  • 분석, 분석 컬럼
  • 매크로, 매크로 인자
  • 데이터 테스트, 데이터 테스트 컬럼
  • 모델의 유닛 테스트
  • 그룹 (dbt v1.10+) 이 설명은 dbt가 렌더링하는 문서화 웹사이트에서 사용돼요(문서화 가이드 또는 Catalog 참고). 설명에는 markdown 뿐 아니라 doc Jinja 함수도 포함할 수 있어요. 설명을 제공할 때 YAML 의미론에 주의하세요. 설명에 중괄호, 콜론, 대괄호 같은 특수 YAML 문자를 포함한다면 설명을 인용(quote)해야 할 수도 있어요. 인용된 설명의 예시는 아래에 있어요.

Examples

이 섹션은 다양한 리소스에 설명을 추가하는 방법의 예시를 보여줘요:

모델과 컬럼에 간단한 설명 추가

models/schema.yml

version: 2

models:
  - name: dim_customers
    description: One record per customer

    columns:
      - name: customer_id
        description: Primary key

모델에 여러 줄 설명 추가

YAML 블록 표기법(block notation)을 사용해 긴 설명을 여러 줄로 나눌 수 있어요: models/schema.yml

version: 2

models:
  - name: dim_customers
    description: >
      One record per customer. Note that a customer must have made a purchase to
      be included in this table — customer accounts that were created but never
      used have been filtered out.

    columns:
      - name: customer_id
        description: Primary key.

설명에서 markdown 사용

설명에 markdown을 사용할 수 있지만, 특수 문자가 있으면 YAML 파서가 혼동하지 않도록 설명을 인용해야 할 수도 있어요! models/schema.yml

version: 2

models:
  - name: dim_customers
    description: "**[Read more](https://www.google.com/)**"

    columns:
      - name: customer_id
        description: Primary key.

설명에서 docs 블록 사용

긴 설명, 특히 markdown을 포함한 설명은 docs 블록을 활용하는 게 더 적합할 수 있어요. 이 방식의 장점은 코드 편집기가 markdown을 올바르게 하이라이트해서 작성할 때 디버깅이 더 쉽다는 점이에요. models/schema.yml

version: 2

models:
  - name: fct_orders
    description: This table has basic information about orders, as well as some derived facts based on payments

    columns:
      - name: status
        description: '{{ doc("orders_status") }}'

models/docs.md

{% docs orders_status %}

Orders can be one of the following statuses:

| status         | description                                                               |
|----------------|---------------------------------------------------------------------------|
| placed         | The order has been placed but has not yet left the warehouse              |
| shipped        | The order has been shipped to the customer and is currently in transit     |
| completed      | The order has been received by the customer                               |
| returned       | The order has been returned by the customer and received at the warehouse |

{% enddocs %}

설명에서 다른 모델로 링크

상대 링크를 사용해 다른 모델로 연결할 수 있어요. 약간 hacky하지만, 이렇게 하면 됩니다:

  1. docs 사이트를 서빙해요.
  2. 연결하려는 모델로 이동해요, 예: http://127.0.0.1:8080/#!/model/model.jaffle_shop.stg_stripe__payments
  3. url_path를 복사해요, 즉 http://127.0.0.1:8080/ 뒤의 모든 것 — 이 경우 #!/model/model.jaffle_shop.stg_stripe__payments
  4. 링크로 붙여넣어요. models/schema.yml
version: 2

models:
  - name: customers
    description: "Filtering done based on [stg_stripe__payments](#!/model/model.jaffle_shop.stg_stripe__payments)"

    columns:
      - name: customer_id
        description: Primary key

설명에 저장소의 이미지 포함

이 섹션은 dbt v1 사용자에게만 적용돼요. 저장소에서 이미지를 포함하면 이미지가 버전 관리되도록 보장돼요. dbt와 dbt v1 사용자 모두 웹에서 이미지를 포함할 수 있는데, 이는 동적 콘텐츠, 저장소 크기 축소, 접근성, 협업 용이성을 제공해요. 모델의 description 필드에 이미지를 포함하려면:

  1. 하위 디렉터리에 파일을 추가해요, 예: assets/dbt-logo.svg
  2. dbt_project.yml 파일에 asset-paths 구성을 설정해서 dbt docs generate의 일부로 이 디렉터리가 target/ 디렉터리로 복사되도록 해요. dbt_project.yml
asset-paths: ["assets"]
  1. description:에 이미지에 대한 Markdown 링크를 사용해요: models/schema.yml
version: 2

models:
  - name: customers
    description: "![dbt Logo](assets/dbt-logo.svg)"

    columns:
      - name: customer_id
        description: Primary key
  1. dbt docs generate를 실행하면 assets 디렉터리가 target 디렉터리로 복사돼요.
  2. dbt docs serve를 실행하면 이미지가 프로젝트 문서의 일부로 렌더링돼요. 이미지와 텍스트를 섞을 때는 docs 블록 사용도 고려해 보세요.

설명에 웹의 이미지 포함

이 섹션은 dbt와 dbt v1 사용자 모두에게 적용돼요. 웹에서 이미지를 포함하면 동적 콘텐츠, 저장소 크기 축소, 접근성, 협업 용이성을 제공해요. 웹에서 이미지를 포함하려면 모델의 description 필드에 이미지 URL을 지정해요: models/schema.yml

version: 2

models:
  - name: customers
    description: "![dbt Logo](https://raw.githubusercontent.com/dbt-labs/dbt/refs/heads/1.latest/docs/images/dbt-core.svg)"

    columns:
      - name: customer_id
        description: Primary key

이미지와 텍스트를 섞을 때는 docs 블록 사용도 고려해 보세요.

데이터 테스트에 설명 추가

제네릭 또는 단일 데이터 테스트에 description 속성을 추가할 수 있어요.

제네릭 데이터 테스트

이 예시는 orders 모델의 컬럼에 고유 값이 있는지 확인하는 제네릭 데이터 테스트를 보여줘요. models/<filename>.yml

version: 2

models:
  - name: orders
    columns:
      - name: order_id
        data_tests:
          - unique:
              description: "The order_id is unique for every row in the orders model"

제네릭 데이터 테스트의 핵심 로직을 제공하는 Jinja 매크로에도 설명을 추가할 수 있어요. 자세한 내용은 Add description to generic data test logic를 참고해 주세요.

단일 데이터 테스트

이 예시는 payments 모델의 모든 값이 음수가 아닌지(≥ 0) 확인하는 단일 데이터 테스트를 보여줘요. tests/<filename>.yml

data_tests:
  - name: assert_total_payment_amount_is_positive
    description: >
      Refunds have a negative amount, so the total amount should always be >= 0.
      Therefore return records where total amount < 0 to make the test fail.

테스트가 실행되려면 tests/assert_total_payment_amount_is_positive.sql SQL 파일이 tests 디렉터리에 존재해야 한다는 점을 기억하세요.

유닛 테스트에 설명 추가

이 예시는 stg_locations 모델의 opened_at 타임스탬프가 날짜로 올바르게 잘리는지 확인하는 유닛 테스트를 보여줘요. models/<filename>.yml

unit_tests:
  - name: test_does_location_opened_at_trunc_to_date
    description: "Check that opened_at timestamp is properly truncated to a date."
    model: stg_locations
    given:
      - input: source('ecom', 'raw_stores')
        rows:
          - {id: 1, name: "Rego Park", tax_rate: 0.2, opened_at: "2016-09-01T00:00:00"}
          - {id: 2, name: "Jamaica", tax_rate: 0.1, opened_at: "2079-10-27T23:59:59.9999"}
    expect:
      rows:
        - {location_id: 1, location_name: "Rego Park", tax_rate: 0.2, opened_date: "2016-09-01"}
        - {location_id: 2, location_name: "Jamaica", tax_rate: 0.1, opened_date: "2079-10-27"}

더 알아보기 (Learn more)