docs

docs

docs 설정은 리소스가 자동 생성된 **문서 사이트에 나타날지(show), DAG에서 어떤 색으로 표시될지(node_color)**를 다루는 문서 관련 설정이에요. 모델·시드·스냅샷·분석·매크로에 적용할 수 있어요.

출처: 문서

본문

모델의 예시:

models:
  <resource-path>:
    +docs:
      show: true | false
      node_color: color_id # Use name (such as node_color: purple) or hex code with quotes (such as node_color: "#cd7f32")

models:
- name: model_name
  config:
    docs: # changed to config in v1.10
      show: true | false
      node_color: color_id # Use name (such as node_color: purple) or hex code with quotes (such as node_color: "#cd7f32")

시드의 예시:

seeds:
  <resource-path>:
    +docs:
      show: true | false
      node_color: color_id # Use name (such as node_color: purple) or hex code with quotes (such as node_color: "#cd7f32")

seeds:
  - name: seed_name
    config:
      docs: # changed to config in v1.10
        show: true | false
        node_color: color_id # Use name (such as node_color: purple) or hex code with quotes (such as node_color: "#cd7f32")

스냅샷의 예시:

snapshots:
  <resource-path>:
    +docs:
      show: true | false
      node_color: color_id # Use name (such as node_color: purple) or hex code with quotes (such as node_color: "#cd7f32")

snapshots:
  - name: snapshot_name
    config:
      docs: # changed to config in v1.10
        show: true | false
        node_color: color_id # Use name (such as node_color: purple) or hex code with quotes (such as node_color: "#cd7f32")

분석(analysis)의 예시:

analyses:
  - name: analysis_name
    config:
      docs: # changed to config in v1.10
        show: true | false
        node_color: color_id # Use name (such as node_color: purple) or hex code with quotes (such as node_color: "#cd7f32")

매크로의 예시:

macros:
  - name: macro_name
    config: 
      docs: # changed to config in v1.11
        show: true | false

dbt_project.yml에서 설정하면 많은 리소스의 docs 동작을 한 번에 구성할 수 있어요. properties.yaml 파일의 docs 설정으로 특정 리소스의 문서 동작을 설정하거나 덮어쓸 수도 있어요. docs 설정은 sources에는 지원되지 않아요.

역방향 호환성을 위해 docs는 최상위 키로도 지원되지만, 설정 상속(config inheritance)의 기능은 없어요.

정의 (Definition)

docs 설정으로 리소스에 대한 문서 관련 구성을 제공할 수 있어요. 지원하는 속성은 다음과 같아요:

  • show: 노드가 자동 생성된 문서 웹사이트에 나타날지 제어해요.
  • node_color: DAG에 표시되는 노드의 색상을 제어해요. 모델·시드·스냅샷·분석에서 지원되며, 다른 노드 유형은 지원되지 않아요.

참고: 숨겨진 모델은 여전히 dbt DAG 시각화에 나타나지만 "hidden"으로 구분돼요.

기본값 (Default)

show의 기본값은 true예요.

예시 (Examples)

모델을 숨김으로 표시하기

models:
  - name: sessions__tmp
    docs:
      show: false

모델 하위 폴더를 숨김으로 표시하기

참고: 이는 dbt 패키지도 숨길 수 있어요.

models:
  # hiding models within the staging subfolder
  tpch:
    staging:
      +materialized: view
      +docs:
        show: false
  
  # hiding a dbt package
  dbt_artifacts:
    +docs:
      show: false

커스텀 노드 색상 (Custom node colors)

docs 속성은 dbt Docs의 DAG 안에서 일부 노드 유형의 표시 색상을 커스터마이즈하는 node_color를 지원해요. 노드 색상은 다음 파일들에서 정의하고 필요한 곳에서 오버라이드할 수 있어요.

  • <example-sql-file.sql> 오버라이드 schema.yml 오버라이드 dbt_project.yml

참고, 커스터마이즈된 색상을 적용·확인하려면 dbt docs generate 명령을 실행하거나 다시 실행해야 해요.

예시

커스텀 노드 색상은 Catalog에 적용되지 않아요. node_color 속성은 Catalog에서 적용되지 않아요. 대신 Explorer는 DAG의 맵 레이어인 렌즈(lenses)를 제공해요. 렌즈는 프로젝트의 컨텍스트 메타데이터를 규모에 맞게 이해하고 특정 모델이나 모델 하위 집합을 구분하는 데 도움을 줍니다.

지원하는 모델에 hex 코드나 평범한 색상 이름으로 하위 디렉터리 내 커스텀 node_color를 추가해요. marts/core/fct_orders.sql의 node_color: red는 dbt_project.yml의 node_color: gold를 오버라이드해요. marts/core/schema.yml의 node_color: #000000은 dbt_project.yml의 node_color: gold를 오버라이드해요.

models:
  tpch:
    staging:
      +materialized: view
      +docs:
        node_color: "#cd7f32"

    marts:
      core:
        materialized: table
        +docs:
          node_color: "gold"

models:
  - name: dim_customers
    description: Customer dimensions table
    docs:
      node_color: '#000000'

{{
    config(
        materialized = 'view',
        tags=['finance'],
        docs={'node_color': 'red'}
    )
}}

with orders as (
    
    select * from {{ ref('stg_tpch_orders') }} 

),
order_item as (
    
    select * from {{ ref('order_items') }}
),
order_item_summary as (

    select 
        order_key,
        sum(gross_item_sales_amount) as gross_item_sales_amount,
        sum(item_discount_amount) as item_discount_amount,
        sum(item_tax_amount) as item_tax_amount,
        sum(net_item_sales_amount) as net_item_sales_amount
    from order_item
    group by
        1
),
final as (

    select 

        orders.order_key, 
        orders.order_date,
        orders.customer_key,
        orders.status_code,
        orders.priority_code,
        orders.clerk_name,
        orders.ship_priority,
                
        1 as order_count,                
        order_item_summary.gross_item_sales_amount,
        order_item_summary.item_discount_amount,
        order_item_summary.item_tax_amount,
        order_item_summary.net_item_sales_amount
    from
        orders
        inner join order_item_summary
            on orders.order_key = order_item_summary.order_key
)
select 
    *
from
    final

order by
    order_date

node_color가 dbt docs와 호환되지 않으면 다음과 같은 컴파일 오류가 표시돼요.

Invalid color name for docs.node_color: aweioohafio23f. It is neither a valid HTML color name nor a valid HEX code.

models:
  tpch:
    marts:
      core:
        materialized: table
        +docs:
          node_color: "aweioohafio23f"

더 알아보기 (Learn more)