YAML 선택자

YAML 선택자 (YAML Selectors)

리소스 선택자를 YAML로 작성하고 사람이 읽기 좋은 이름으로 저장한 뒤 --select와 함께 selector: 메서드로 참조하는 기능이에요. 복잡한 선택 조건을 읽기 쉽고 버전 관리 가능하며 재사용 가능하게 만들어요.

출처: 문서

본문

(dbt v1.12 이상에 적용) 리소스 선택자를 YAML로 작성하고, 사람이 읽기 좋은 이름으로 저장한 뒤 --select와 함께 selector: 메서드로 참조하세요.

선택자를 최상위 selectors.yml 파일에 기록하면:

• 가독성 (Legibility) — 복잡한 선택 기준이 딕셔너리와 배열로 구성돼요.
• 버전 관리 (Version control) — 선택자 정의가 dbt 프로젝트와 같은 git 저장소에 저장돼요.
• 재사용성 (Reusability) — 선택자를 여러 작업 정의에서 참조할 수 있고, 정의가(YAML 앵커를 통해) 확장 가능해요.

선택자는 최상위 selectors.yml 파일에 있어요. 각각 name과 definition이 있어야 하고, 선택적으로 description과 default 플래그를 정의할 수 있어요.

selectors.yml:

selectors:
  - name: nodes_to_joy
    definition: ...
  - name: nodes_to_a_grecian_urn
    description: Attic shape with a fair attitude
    default: true
    definition: ...

(dbt v1.12 이상에 적용) dbt v1.12부터 --select 또는 --exclude에서 selector 메서드(예: selector:my_selector)로 명명된 선택자를 참조할 수 있어요.

정의 (Definitions)

각 정의는 하나 이상의 인자로 구성되며, 다음 중 하나일 수 있어요:

• CLI 스타일 — 문자열로, CLI 스타일 인자를 나타내요.
• 키-값 (Key-value) — method: value 형태의 쌍이에요.
• 전체 YAML (Full YAML) — method, value, operator-등가 키워드, exclude 지원 항목을 갖춘 완전히 지정된 딕셔너리예요.

여러 인자를 정리하려면 union과 intersection operator-등가 키워드를 사용하세요.

CLI 스타일 (CLI-style)

definition: 'tag:nightly'

이 단순한 문법은 +, @, * 그래프 연산자, 집합 연산자, exclude를 지원해요.

키-값 (Key-value)

definition:
  tag: nightly

이 단순한 문법은 그래프·집합 연산자나 exclude를 지원하지 않아요.

전체 YAML (Full YAML)

가장 철저한 문법으로, 그래프·집합 연산자의 operator-등가 키워드를 포함할 수 있어요.

사용 가능한 목록은 methods 문서를 확인하세요.

definition:
  method: tag
  value: nightly
  # Optional keywords map to the `+` and `@` graph operators:
  children: true | false
  parents: true | false
  children_depth: 1
  # if children: true, degrees to include
  parents_depth: 1
  # if parents: true, degrees to include
  childrens_parents: true | false
  # @ operator
  indirect_selection: eager | cautious | buildable | empty
  # include all tests selected indirectly? eager by default

모든 노드를 선택하는 * 연산자는 다음과 같이 작성할 수 있어요:

definition:
  method: fqn
  value: "*"

Exclude

exclude 키워드는 완전히 지정된(fully-qualified) 딕셔너리에서만 지원돼요. 각 딕셔너리의 인자로 전달하거나, union의 항목으로 전달할 수 있어요. 다음은 동등해요:

- method: tag
  value: nightly
  exclude:
    - "@tag:daily"

- union:
    - method: tag
      value: nightly
    - exclude:
        - method: tag
          value: daily

참고: YAML 선택자의 exclude 인자는 CLI의 --exclude 인자와 미묘하게 달라요. 여기서 exclude는 항상 집합 차집합(set difference)을 반환하고, 자신의 범위 안에서 항상 마지막에 적용돼요.

--select(yeslist)가 둘 이상 전달되면 교집합이 아니라 합집합으로 처리돼요. --exclude(nolist)도 둘 이상일 때 마찬가지예요.

간접 선택 (Indirect selection)

일반적으로 dbt는 직접 선택하는 리소스에 닿는 모든 테스트를 간접적으로 선택해요. 이를 "eager" 간접 선택이라고 불러요. 특정 기준에 대해 indirect_selection을 설정해 "cautious", "buildable", "empty" 모드로 전환할 수 있어요:

- union:
    - method: fqn
      value: model_a
      indirect_selection: eager
      # default: will include all tests that touch model_a
    - method: fqn
      value: model_b
      indirect_selection: cautious
      # will not include tests touching model_b
      # if they have other unselected parents
    - method: fqn
      value: model_c
      indirect_selection: buildable
      # will not include tests touching model_c
      # if they have other unselected parents (unless they have an ancestor that is selected)
    - method: fqn
      value: model_d
      indirect_selection: empty
      # will include tests for only the selected node and ignore all tests attached to model_d

제공된다면 YAML 선택자의 indirect_selection 값이 CLI 플래그 --indirect-selection보다 우선해요. indirect_selection은 각 선택 기준마다 별도로 정의되므로, 같은 정의 안에서 eager/cautious/buildable/empty 모드를 섞어 정확히 원하는 동작을 얻을 수 있어요. (dbt v1.12 이상) dbt ls --select selector:SELECTOR_NAME으로 언제든 기준을 테스트해볼 수 있어요.

간접 선택에 대한 자세한 내용은 test selection 예시를 참고하세요.

예시 (Example)

다음을 나타내는 두 가지 방법이 있어요:

$ dbt run --select @source:snowplow,tag:nightly models/export --exclude package:snowplow,config.materialized:incremental export_performance_timing

CLI 스타일 / Full YML:

selectors.yml:

selectors:
  - name: nightly_diet_snowplow
    description: "Non-incremental Snowplow models that power nightly exports"
    definition:
      # Optional `union` and `intersection` keywords map to the ` ` and `,` set operators:
      union:
        - intersection:
            - '@source:snowplow'
            - 'tag:nightly'
            - 'models/export'
        - exclude:
            - intersection:
                - 'package:snowplow'
                - 'config.materialized:incremental'
                - export_performance_timing

selectors.yml:

selectors:
  - name: nightly_diet_snowplow
    description: "Non-incremental Snowplow models that power nightly exports"
    definition:
      # Optional `union` and `intersection` keywords map to the ` ` and `,` set operators:
      union:
        - intersection:
            - method: source
              value: snowplow
              childrens_parents: true
            - method: tag
              value: nightly
            - method: path
              value: models/export
        - exclude:
            - intersection:
                - method: package
                  value: snowplow
                - method: config.materialized
                  value: incremental
                - method: fqn
                  value: export_performance_timing

그런 다음 작업 정의에서:

(dbt v1.12 이상에 적용)

dbt run --select selector:nightly_diet_snowplow

기본값 (Default)

선택자는 boolean default 속성을 정의할 수 있어요. 선택자가 default: true면 dbt는 작업이 자체 선택 기준을 정의하지 않을 때 이 선택자의 기준을 사용해요.

루트 프로젝트에 정의된 리소스만 선택하는 기본 선택자를 정의한다고 해볼게요:

selectors:
  - name: root_project_only
    description: >
        Only resources from the root project.
        Excludes resources defined in installed packages.
    default: true
    definition:
      method: package
      value: <my_root_project_name>

"unqualified" 명령을 실행하면 dbt는 root_project_only에 정의된 선택 기준을 사용해요 — 즉 dbt는 루트 프로젝트에 정의된 리소스만 빌드/freshness 검사/컴파일된 SQL 생성을 해요.

dbt build
dbt source freshness
dbt docs generate

(dbt v1.12 이상) 자체 선택 기준(--select나 --exclude를 통한)을 정의하는 명령을 실행하면 dbt는 기본 선택자를 무시하고 플래그 기준을 사용해요. 둘을 결합하려고 하지 않아요. 둘 다 적용하려면 --select와 함께 selector: 메서드를 사용해 기본 선택자를 다른 기준과 함께 참조하세요. 예: dbt build --select selector:root_project_only tag:nightly

주어진 호출에서 default: true는 하나의 선택자만 설정할 수 있어요. 그렇지 않으면 dbt는 에러를 반환해요. 환경에 따라 default 값을 조정하려면 Jinja 표현식을 사용할 수 있어요:

selectors:
  - name: default_for_dev
    default: "{{ target.name == 'dev' | as_bool }}"
    definition: ...
  - name: default_for_prod
    default: "{{ target.name == 'prod' | as_bool }}"
    definition: ...

선택자 상속 (Selector inheritance)

선택자는 selector 메서드를 통해 다른 선택자의 정의를 재사용하고 확장할 수 있어요.

selectors:
  - name: foo_and_bar
    definition:
      intersection:
        - tag: foo
        - tag: bar
  - name: foo_bar_less_buzz
    definition:
      intersection:
        # reuse the definition from above
        - method: selector
          value: foo_and_bar
        # with a modification!
        - exclude:
            - method: tag
              value: buzz

참고: 선택자 상속은 다른 선택자의 로직을 재사용할 수 있게 하지만, parents, children, indirect_selection 등을 통해 그 선택자의 로직을 수정하는 것은 허용하지 않아요. selector 메서드는 명명된 선택자가 반환하는 노드의 완전한 집합을 반환해요.

(dbt v1.12 이상) 선택자 정의가 서로 순환 참조하면 dbt는 런타임에 DbtRecursionError를 발생시켜요. 예를 들어 다음 선택자 상속은 유효하지 않아요:

selectors:
  - name: selector_a
    definition:
      method: selector
      value: selector_b
  - name: selector_b
    definition:
      method: selector
      value: selector_a

--select와 함께 selector: 사용 (Using selector: with --select)

(dbt v1.12 이상) dbt v1.12부터 레거시 --selector 플래그를 --select나 --exclude와 함께 사용하면 dbt는 SelectExcludeIgnoredWithSelectorWarning을 발생시켜요. 미리 정의된 선택자를 다른 선택 기준과 함께 참조하려면 --select와 함께 selector: 메서드를 직접 사용하세요. 예:

dbt run --select selector:nightly_diet_snowplow tag:nightly

더 알아보기 (Learn more)

• 노드 선택 메서드 전체 목록은 Node selection methods 문서를 참고하세요.
• CLI에서의 선택 구문은 Node selection syntax 문서를 참고하세요.