persist_docs

persist_docs (문서 지속)

persist_docs 설정은 리소스에 대한 설명(description)을 데이터베이스의 컬럼·관계 주석(comment)으로 선택적으로 유지하는 기능이에요. 기본적으로 문서 지속은 비활성화돼 있고, 필요에 따라 특정 리소스나 리소스 그룹에 대해 활성화할 수 있어요.

출처: dbt 공식 문서

본문

모델

dbt_project.yml

models:
  <resource-path>:
    +persist_docs:
      relation: true
      columns: true

models/.sql


{{ config(
  persist_docs={"relation": true, "columns": true}
) }}

select ...

소스

이 설정은 소스에는 구현되지 않아요.

시드

dbt_project.yml

seeds:
  <resource-path>:
    +persist_docs:
      relation: true
      columns: true

스냅샷

dbt_project.yml

snapshots:
  <resource-path>:
    +persist_docs:
      relation: true
      columns: true

(dbt v1.9 이상에 적용돼요.)

snapshots/snapshot_name.yml


snapshots:
  - name: snapshot_name
    config:
      persist_docs:
        relation: true
        columns: true

snapshots/.sql

{% snapshot snapshot_name %}

{{ config(
  persist_docs={"relation": true, "columns": true}
) }}

select ...

{% endsnapshot %}

정의

리소스 설명을 데이터베이스의 컬럼 및 관계 주석으로 선택적으로 유지하는 설정이에요. 기본적으로 문서 지속은 비활성화돼 있지만, 특정 리소스나 리소스 그룹에 대해 필요에 따라 활성화할 수 있어요.

지원

persist_docs 설정은 가장 널리 쓰이는 dbt 어댑터에서 지원돼요.

  • Postgres
  • Redshift
  • Snowflake
  • BigQuery
  • Databricks
  • Apache Spark
  • Starburst Galaxy (dbt-trino)

다만 일부 데이터베이스는 설명을 데이터베이스 객체에 어디에, 어떻게 추가할 수 있는지 제한해요. 그런 데이터베이스 어댑터는 persist_docs를 지원하지 않거나 부분적으로만 지원할 수 있어요.

몇 가지 알려진 이슈와 제한 사항:

Databricks

  • 컬럼 레벨 주석에는 file_format: delta(또는 다른 "v2 파일 포맷")가 필요해요.

Snowflake

  • SQL 모델의 컬럼 이름이 혼합 대소문자 형식(예: ca_net_ht_N)이면 해당 컬럼의 문서가 유지되지 않아요. 문서를 유지하려면 두 가지 옵션이 있어요.

    • 해당 YML 파일에서 컬럼 이름을 소문자 또는 대문자로만 정의해요.
    • 해당 YML 파일에서 quote 설정을 사용해요.

    혼합 대소문자 형식 컬럼에 quote 필드를 사용하는 방법은 다음 예시를 참고해요.

    1. 다음 SQL과 YML 파일을 만들어요.

      .sql

      {{ config(materialized='table') }}

select 1 as "ca_net_ht_N" # note the use of double quotes for the column name

      .yml

      models:
  - name: <modelname>
    description: This is the table description

columns:
  - name: "ca_net_ht_N"
    description: This should be the description of the column
    quote: true

    2. dbt build -s models/<modelname>.sql --full-refresh를 실행해요.

    3. logs/dbt.log에서 로그를 열고 컬럼 설명을 확인해요.

      alter table analytics.<schema>.<modelname> alter
    "ca_net_ht_N" COMMENT $$This should be the description of the column$$;

Starburst Galaxy (dbt-trino)

사용법

컬럼과 관계 문서화하기

모델에 설명을 제공해요.

models/schema.yml


models:
  - name: dim_customers
    description: One record per customer
    columns:
      - name: customer_id
        description: Primary key

프로젝트에서 컬럼과 관계에 persist_docs를 활성화해요.

dbt_project.yml

models:
  +persist_docs:
    relation: true
    columns: true

dbt를 실행하면 생성된 관계와 컬럼에 여러분의 설명이 주석으로 달리는 것을 볼 수 있어요.

더 알아보기 (Learn more)