tags

tags

tags는 리소스에 태그(또는 태그 목록)를 적용하는 config예요. 이 태그들은 리소스 선택 문법의 일부로 사용돼서, dbt run --select tag:my_tag 처럼 특정 태그가 붙은 리소스만 골라 실행할 수 있게 해줘요.

출처: 문서

본문

(dbt v1.9 이상 적용) dbt_project.yml

models:
  <resource-path>:
    +tags: <string> | [<string>]

models/properties.yml

models:
  - name: model_name
    config:
      tags: <string> | [<string>]
    columns:
      - name: column_name
        config:
          tags: <string> | [<string>] # changed to config in v1.10 and backported to 1.9
        data_tests:
          - test_name:
              config:
                tags: <string> | [<string>]

models/.sql

{{ config(
    tags="<string>" | ["<string>"]
) }}

select ...

(dbt v1.9 이상 적용) dbt_project.yml

seeds:
  <resource-path>:
    +tags: <string> | [<string>]

seeds/properties.yml

seeds:
  - name: seed_name
    config:
      tags: <string> | [<string>]
    columns:
      - name: column_name
        config:
          tags: <string> | [<string>] # changed to config in v1.10 and backported to 1.9
        data_tests:
          - test_name:
              config:
                tags: <string> | [<string>]

(dbt v1.9 이상 적용) dbt_project.yml

snapshots:
  <resource-path>:
    +tags: <string> | [<string>]

(dbt v1.9 이상 적용) snapshots/properties.yml

snapshots:
  - name: snapshot_name
    config:
      tags: <string> | [<string>]

snapshots/.sql

{% snapshot snapshot_name %}

{{ config(
    tags="<string>" | ["<string>"]
) }}

select ...

{% endsnapshot %}

(dbt v1.9 이상 적용) dbt_project.yml

saved-queries:
  <resource-path>:
    +tags: <string> | [<string>]

models/semantic_models.yml

saved_queries:
  - name: saved_query_name
    config:
      tags: <string> | [<string>]

(dbt v1.9 이상 적용) dbt_project.yml

sources:
  <resource-path>:
    +tags: <string> | [<string>]

models/properties.yml

sources:
  - name: source_name
    config:
      tags: <string> | [<string>] # changed to config in v1.10
    tables:
      - name: table_name
        config:
          tags: <string> | [<string>] # changed to config in v1.10
        columns:
          - name: column_name
            config:
              tags: <string> | [<string>] # changed to config in v1.10 and backported to 1.9
            data_tests:
              - test_name:
                  config:
                    tags: <string> | [<string>]

하위 호환성을 위해 tags는 sources의 최상위 키로 지원되지만, config 상속 기능은 없어요.

(dbt v1.9 이상 적용) dbt_project.yml

exposures:
  <resource-path>:
    +tags: <string> | [<string>]

models/exposures.yml

exposures:
  - name: exposure_name
    config:
      tags: <string> | [<string>] # changed to config in v1.10

하위 호환성을 위해 tags는 exposures의 최상위 키로 지원되지만, config 상속 기능은 없어요.

(dbt v1.9 이상 적용) dbt_project.yml

data_tests:
  <resource-path>:
    +tags: <string> | [<string>]

models/properties.yml

models:
  - name: model_name
    columns:
      - name: column_name
        data_tests:
          - test_name:
              config:
                tags: <string> | [<string>]

tests/.sql

{% test test_name() %}

{{ config(
    tags="<string>" | ["<string>"]
) }}

select ...

{% endtest %}

Definition

리소스에 태그(또는 태그 목록)를 적용해요.

이 태그들은 다음 명령을 실행할 때 리소스 선택 문법의 일부로 사용할 수 있어요.

• dbt run --select tag:my_tag — 특정 태그가 붙은 모든 모델 실행.
• dbt build --select tag:my_tag — 특정 태그가 붙은 모든 리소스 빌드.
• dbt seed --select tag:my_tag — 특정 태그가 붙은 모든 리소스 시드.
• dbt snapshot --select tag:my_tag — 특정 태그가 붙은 모든 리소스 스냅샷.
• dbt test --select tag:my_tag — 태그가 붙은 모델과 연결된 모든 테스트를 간접적으로 실행.

상태 비교에 미치는 영향: 컬럼 레벨을 포함해 tags가 바뀌어도 state:modified가 트리거되지 않아요. dbt는 tags(와 meta)를 리소스를 materialize하는 방식에 영향을 주지 않으므로 메타데이터로만 취급해요. state 비교의 제약 사항은 caveats를 참고하세요.

+ 연산자와 함께 태그 쓰기

tag 선택에 업스트림/다운스트림 의존성을 포함하려면 + 연산자를 쓸 수 있어요.

• dbt run --select tag:my_tag+ — my_tag가 붙은 모델과 그 모든 다운스트림 의존성 실행.
• dbt run --select +tag:my_tag — my_tag가 붙은 모델과 그 모든 업스트림 의존성 실행.
• dbt run --select +tag:my_tag+ — my_tag가 붙은 모델, 업스트림 의존성, 다운스트림 의존성 실행.
• dbt run --select tag:my_tag+ --exclude tag:exclude_tag — my_tag가 붙은 모델과 그 다운스트림 의존성을 실행하고, 의존성과 무관하게 exclude_tag가 붙은 모델은 제외.

태그 사용 참고 사항 — 태그를 쓸 때 다음을 고려하세요.

• 각 개별 태그는 문자열이어야 해요.
• 태그는 프로젝트 계층에 걸쳐 가산적(additive)이에요.
• 일부 리소스 타입(예: sources, exposures)은 태그를 최상위에 요구해요.

자세한 내용은 usage notes를 참고하세요.

Examples

다음 예시들은 프로젝트의 리소스에 태그를 적용하는 방법을 보여줘요. 태그는 dbt_project.yml, property 파일, SQL 파일에서 설정할 수 있어요.

태그로 프로젝트 일부만 실행하기

dbt_project.yml에서 단일 값 또는 문자열로 태그를 적용해요. 다음 예시에서 모델 중 하나인 jaffle_shop 모델은 contains_pii로 태그가 붙어요.

dbt_project.yml

models:
  jaffle_shop:
    +tags: "contains_pii"

    staging:
      +tags:
        - "hourly"

    marts:
      +tags:
        - "hourly"
        - "published"

    metrics:
      +tags:
        - "daily"
        - "published"

모델에 태그 적용하기

이 섹션은 dbt_project.yml, schema.yml, SQL 파일에서 모델에 태그를 적용하는 방법을 보여줘요.

dbt_project.yml 파일에서 모델에 태그를 적용하려면:

dbt_project.yml

models:
  jaffle_shop:
    +tags: finance # jaffle_shop model is tagged with 'finance'.

models/ 디렉터리 YAML property 파일에서 config 속성으로 모델에 태그를 적용하려면:

models/stg_customers.yml

models:
  - name: stg_customers
    description: Customer data with basic cleaning and transformation applied, one row per customer.
    config:
      tags: ['santi'] # stg_customers.yml model is tagged with 'santi'.
    columns:
      - name: customer_id
        description: The unique key for each customer.
        data_tests:
          - not_null
          - unique

SQL 파일에서 모델에 태그를 적용하려면:

models/staging/stg_payments.sql

{{ config(
    tags=["finance"] # stg_payments.sql model is tagged with 'finance'.
) }}

select ...

특정 태그가 붙은 리소스 실행(또는 제외)은 다음 명령으로 해요.

# Run all models tagged "daily"
  dbt run --select tag:daily

# Run all models tagged "daily", except those that are tagged hourly
  dbt run --select tag:daily --exclude tag:hourly

시드에 태그 적용하기

dbt_project.yml

seeds:
  jaffle_shop:
    utm_mappings:
      +tags: marketing

dbt_project.yml

seeds:
  jaffle_shop:
    utm_mappings:
      +tags:
        - marketing
        - hourly

저장된 쿼리에 태그 적용하기

dbt_project.yml 파일에서 저장된 쿼리에 태그를 적용하는 예시예요. 이 저장된 쿼리는 order_metrics로 태그가 붙어요.

dbt_project.yml

saved-queries:
  jaffle_shop:
    customer_order_metrics:
      +tags: order_metrics

그다음 특정 태그가 붙은 리소스를 다음 명령으로 실행해요.

# Run all resources tagged "order_metrics"
  dbt run --select tag:order_metrics

두 번째 예시는 semantic_model.yml 파일에서 저장된 쿼리에 여러 태그를 적용하는 방법을 보여줘요. 이 저장된 쿼리는 order_metrics와 hourly로 태그가 붙어요.

semantic_model.yml

saved_queries:
  - name: test_saved_query
    description: "{{ doc('saved_query_description') }}"
    label: Test saved query
    config:
      tags:
        - order_metrics
        - hourly

여러 태그가 붙은 리소스를 다음 명령으로 실행해요.

# Run all resources tagged "order_metrics" and "hourly"
  dbt build --select tag:order_metrics tag:hourly

Usage notes

태그는 문자열이어야 함

각 개별 태그는 문자열 값이어야 해요(예: marketing 또는 daily).

다음 예시에서 my_tag: "my_value"는 키-값 쌍이라 유효하지 않아요.

sources:
  - name: ecom
    schema: raw
    description: E-commerce data for the Jaffle Shop
    config:
      tags:
        my_tag: "my_value". # invalid
    tables:
      - name: raw_customers
        config:
          tags:
            my_tag: "my_value". # invalid

tags 값이 문자열이 아니면 경고가 나와요. 예:

Field config.tags: {'my_tag': 'my_value'} is not valid for source (ecom)

태그는 가산적(additive)임

태그는 계층적으로 축적돼요. 앞의 예시는 다음처럼 이어져요.

특정 컬럼과 테스트에 태그 적용하기

리소스의 특정 컬럼과 테스트에도 태그를 적용할 수 있어요.

models/properties.yml

models:
  - name: my_model
    columns:
      - name: column_name
        config:
          tags: ['column_level'] # changed to config in v1.10 and backported to 1.9
        data_tests:
          - unique:
              config:
                tags: ['test_level'] # changed to config in v1.10

위 예시에서 unique 테스트는 다음 두 태그 중 어느 것으로도 선택할 수 있어요.

dbt test --select tag:column_level
dbt test --select tag:test_level

sources와 exposures의 하위 호환성

하위 호환성을 위해 tags는 sources와 exposures의 최상위 키로 지원돼요 (dbt v1.10 이전), config 상속 기능은 없어요.

models/properties.yml

exposures:
  - name: my_exposure
    tags: ['exposure_tag'] # top-level key (legacy)
    # OR use config (v1.10+)
    config:
      tags: ['exposure_tag']

sources:
  - name: source_name
    tags: ['top_level'] # top-level key (legacy)
    # OR use config (v1.10+)
    config:
      tags: ['top_level']
    tables:
      - name: table_name
        tags: ['table_level'] # top-level key (legacy)
        # OR use config (v1.10+)
        config:
          tags: ['table_level']
        columns:
          - name: column_name
            config:
              tags: ['column_level'] # changed to config in v1.10 and backported to 1.9

더 알아보기 (Learn more)

• Resource selection syntax — 태그 기반 선택 문법.
• state 비교 — 태그와 state 비교.