meta

meta (메타데이터)

meta 설정은 리소스에 메타데이터를 설정하며 임의의 키-값 쌍을 받아요. 이 메타데이터는 dbt가 생성하는 manifest.json 파일에 컴파일되고 자동 생성된 문서에 표시돼요. 모델, 소스, 시드, 스냅샷, 테스트, 매크로, exposure, semantic model 등 여러 리소스에 매핑됩니다.

출처: dbt 공식 문서

본문

모델

dbt_project.yml

models:
  <resource-path>:
    +meta: {<dictionary>}

models/schema.yml


models:
  - name: model_name
    config:
      meta: {<dictionary>}

    columns:
      - name: column_name
        config:
          meta: {<dictionary>} # changed to config in v1.10 and backported to 1.9

meta 설정은 다음 위치에 정의할 수 있어요.

  • 프로젝트 파일의 models 설정 아래(위의 'models/schema.yml' 예시 참고)
  • 프로젝트 파일의 models 설정 아래(dbt_project.yml)
  • 모델 SQL 파일 안의 config() Jinja 매크로

자세한 내용은 configs and properties를 참고해요.

소스

dbt_project.yml

sources:
  <resource-path>:
    +meta: {<dictionary>}

models/schema.yml


sources:
  - name: model_name
    config:
      meta: {<dictionary>}

    tables:
      - name: table_name
        config:
          meta: {<dictionary>}

        columns:
          - name: column_name
            config:
              meta: {<dictionary>} # changed to config in v1.10 and backported to 1.9

시드

dbt_project.yml

seeds:
  <resource-path>:
    +meta: {<dictionary>}

seeds/schema.yml


seeds:
  - name: seed_name
    config:
      meta: {<dictionary>}

    columns:
      - name: column_name
        config:
          meta: {<dictionary>} # changed to config in v1.10 and backported to 1.9

meta 설정은 다음 위치에 정의할 수 있어요.

  • 프로퍼티 파일의 seeds 설정 아래(위의 'seeds/schema.yml' 예시 참고)
  • 프로젝트 파일의 seeds 설정 아래(dbt_project.yml). 자세한 내용은 configs and properties를 참고해요.

스냅샷

dbt_project.yml

snapshots:
  <resource-path>:
    +meta: {<dictionary>}

snapshots/schema.yml


snapshots:
  - name: snapshot_name
    config:
      meta: {<dictionary>}

    columns:
      - name: column_name
        config:
          meta: {<dictionary>} # changed to config in v1.10 and backported to 1.9

meta 설정은 다음 위치에 정의할 수 있어요.

  • 프로퍼티 파일의 snapshots 설정 아래(위의 snapshots/schema.yml 예시 참고)
  • 프로젝트 파일의 snapshots 설정 아래(dbt_project.yml)
  • 스냅샷의 SQL 블록 안의 config() Jinja 매크로

자세한 내용은 configs and properties를 참고해요.

테스트

meta 필드를 사용해 generic 또는 singular 테스트에 메타데이터를 추가할 수 있어요. meta는 키-값 쌍을 받고, manifest.json에 컴파일되며, 자동 생성 문서에 나타나요.

Generic 데이터 테스트

properties.yml 파일의 config 블록 아래에 meta를 추가해요.

models/properties.yml

models:
  - name: my_model
    columns:
      - name: my_column
        data_tests:
          - unique:
              config:
                meta:
                  owner: "docs team"

또는 dbt_project.yml에서 기본값을 설정해요.

dbt_project.yml

data_tests:
  my_project:
    +meta:
      owner: "docs team"

Singular 데이터 테스트

SQL 테스트 파일에서 config()로 meta를 추가해요.

tests/my_singular_test.sql

{{ config(meta={'owner': 'docs team'}) }}

select * from {{ ref('my_model') }}
where my_column is null

또는 tests/properties.yml에서 문서화해요.

tests/properties.yml

data_tests:
  - name: my_singular_test
    config:
      meta:
        owner: "analytics_team"

유닛 테스트

dbt v1.8 또는 dbt "v1 Latest" 릴리스 트랙에서 사용할 수 있어요.

dbt_project.yml

unit_tests:
  <resource-path>:
    +meta: {<dictionary>}

models/.yml

unit_tests:
  - name: <test-name>
    config:
      meta: {<dictionary>}

Analyses

meta 설정은 현재 analyses에서 지원되지 않아요.

매크로

dbt_project.yml

macros:
  <resource-path>:
    +meta: {<dictionary>}

macros/schema.yml

macros:
  - name: macro_name
    config: 
      meta: {<dictionary>} # changed to config in v1.11
    arguments:
      - name: argument_name

Exposures

dbt_project.yml

exposures:
  <resource-path>:
    +meta: {<dictionary>}

models/exposures.yml


exposures:
  - name: exposure_name
    config:
      meta: {<dictionary>} # changed to config in v1.10

Semantic models

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

meta를 모델 YAML 파일에 내장된 semantic models 또는 dbt_project.yml 파일의 semantic-models 설정 블록 아래에서 구성해요.

dbt_project.yml

semantic-models:
  <resource-path>:
    +meta: {<dictionary>}

models/file_name.yml

models:
  - name: model_name
    semantic_model:
      enabled: true
      config:
        meta: {<dictionary>}

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

Dimensions, entities, metrics도 각자의 meta 설정을 가질 수 있어요.

models/file_name.yml

models:
  - name: model_name
    semantic_model:
      enabled: true
      config:
        meta: {<dictionary>}

    agg_time_dimension: your_time_dimension_name

    columns:
      - name: entity_column_name
        entity:
          type: primary
          name: entity_name
          config:
            meta: {<dictionary>}

      - name: dimension_column_name
        dimension:
          type: categorical
          name: dimension_name
          config:
            meta: {<dictionary>}

    metrics:
      - name: simple_metric_name
        description: "Description of the metric"
        type: simple
        agg: sum  
        expr: column_name 
        config:
          meta: {<dictionary>}

meta 설정은 다음 위치에 정의할 수 있어요.

  • 프로퍼티 파일의 semantic-models 설정 아래(위의 models/semantic_models.yml 예시 참고)
  • 프로젝트 파일의 semantic-models 설정 아래(dbt_project.yml). 자세한 내용은 configs and properties를 참고해요.

Metrics

dbt_project.yml

metrics:
  <resource-path>:
    +meta: {<dictionary>}

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

models/file_name.yml

models:
  - name: model_name 
    semantic_model:
      enabled: true
    agg_time_dimension: your_time_dimension
    columns:
      - name: column_name
        dimension:
          type: time
        granularity: day
    metrics:
      - name: number_of_people
        type: simple
        description: Total count of people
        agg: count
        expr: people
        config:
          meta:
            my_meta_config: 'config_value'

Saved queries

dbt_project.yml

saved-queries:
  <resource-path>:
    +meta: {<dictionary>}

models/semantic_models.yml

saved_queries:
  - name: saved_query_name
    config:
      meta: {<dictionary>}

정의

meta 설정은 리소스에 메타데이터를 설정하며 임의의 키-값 쌍을 받아요. 이 메타데이터는 dbt가 생성하는 manifest.json 파일에 컴파일되고, 자동 생성된 문서에 표시돼요.

구성하는 리소스에 따라 meta는 config 프로퍼티 안에서 그리고/또는 최상위 키로 사용할 수 있어요. (하위 호환성을 위해 meta는 종종(항상은 아니지만) 최상위 키로 지원되지만, config 상속 기능은 없어요.)

상태 비교에 미치는 영향

컬럼 레벨을 포함한 meta의 변경은 state:modified를 트리거하지 않아요. dbt는 meta(와 tags)를 리소스가 어떻게 materialize되는지에 영향을 주지 않으므로 메타데이터로만 취급해요. 자세한 내용은 상태 비교의 주의 사항을 참고해요.

예시

meta 설정 사용법을 보여주는 예시들이에요.

모델 소유자 지정

추가로 model_maturity: 키를 사용해 모델의 성숙도(maturity)를 나타낼 수도 있어요.

models/schema.yml


models:
  - name: users
    config:
      meta:
        owner: "@alice"
        model_maturity: in dev

PII를 포함하는 소스 컬럼 지정

models/schema.yml


sources:
  - name: salesforce
    tables:
      - name: account
        config:
          meta:
            contains_pii: true
        columns:
          - name: email
            config:
              meta: # changed to config in v1.10 and backported to 1.9
                contains_pii: true

모든 시드에 하나의 meta 속성 설정

dbt_project.yml

seeds:
  +meta:
    favorite_color: red

단일 모델에 하나의 meta 속성 덮어쓰기

models/my_model.sql

{{ config(meta = {
    'single_key': 'override'
}) }}

select 1 as id

dbt_project.yml에서 config 프로퍼티로 owner와 favorite_color 지정

dbt_project.yml

models:
  jaffle_shop:
    +meta:
      owner: "@alice"
      favorite_color: red

semantic model에 meta 할당

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

다음 예시는 모델 YAML 파일과 dbt_project.yml 파일에서 semantic model에 meta 값을 할당하는 방법을 보여줘요.

Semantic model
models:
  - name: fact_transactions
    description: "Transaction fact table at the transaction level. This table contains one row per transaction and includes the transaction timestamp."
    semantic_model:
      enabled: true
      name: transaction
      config:
        meta:
          data_owner: "Finance team"
          used_in_reporting: true

    agg_time_dimension: transaction_date
dbt_project.yml
semantic-models:
  jaffle_shop:
    +meta:
      used_in_reporting: true

dimensions, measures, entities에 meta 할당

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

Semantic model

다음 예시는 semantic model에서 dimension, entity, simple metrics에 meta 값을 할당하는 방법을 보여줘요.

model_name.yml

models:
  - name: model_name
    semantic_model:
      enabled: true
      name: semantic_model

    agg_time_dimension: order_date

    columns:
      - name: order_date
        dimension:
          type: time
          config:
            meta:
              data_owner: "Finance team"
              used_in_reporting: true

      - name: customer_id
        entity:
          type: primary
          config:
            meta:
              description: "Unique identifier for customers"
              data_owner: "Sales team"
              used_in_reporting: false

    metrics:
      - name: count_of_users
        type: simple
        agg: count_distinct
        expr: user_id
        config:
          meta:
            used_in_reporting: true
dbt_project.yml

이 두 번째 예시는 +meta 구문으로 dbt_project.yml 파일에서 dimension에 data_owner와 추가 메타데이터 값을 할당하는 방법을 보여줘요. 비슷한 구문이 entities와 simple metrics에도 쓰일 수 있어요.

dbt_project.yml

semantic-models:
  jaffle_shop:
    ...
    dimensions:
      - name: order_date
        config:
          meta:
            data_owner: "Finance team"
            used_in_reporting: true

generic과 singular 데이터 테스트에 meta 추가

다음 예시들은 properties.yml 파일에서 generic 데이터 테스트에, config()로 singular 데이터 테스트에 meta를 추가하는 방법을 보여줘요. dbt_project.yml이나 tests/properties.yml에서도 기본값을 설정할 수 있어요.

Generic 데이터 테스트

models/properties.yml

models:
  - name: orders
    columns:
      - name: order_id
        data_tests:
          - not_null:
              config:
                meta:
                  owner: "@data_team"
Singular 데이터 테스트

tests/assert_order_ids.sql

{{ config(meta={'owner': '@data_team'}) }}

select *
from {{ ref('orders') }}
where order_id is null

Python 모델에서 meta 값 접근

Python 모델에서 커스텀 meta 값에 접근하려면 dbt.config.meta_get() 메서드를 사용해요.

예를 들어 my_python_model이라는 모델이 있고 커스텀 값을 저장하고 싶다면:

models/schema.yml

models:
  - name: my_python_model
    config:
      meta:
        batch_size: 1000
        processing_mode: "incremental"

models/my_python_model.py

def model(dbt, session):
    # Access custom values stored in meta directly
    batch_size = dbt.config.meta_get("batch_size")
    processing_mode = dbt.config.meta_get("processing_mode")
    
    # Use the meta values in your model logic
    df = dbt.ref("upstream_model")
    
    if processing_mode == "incremental":
        df = df.limit(batch_size)
    
    return df

더 알아보기 (Learn more)