노드 셀렉터 메서드

노드 셀렉터 메서드 (Node selector methods)

셀렉터 메서드는 method:value 문법을 사용해 공통 속성을 공유하는 모든 리소스를 반환해요. 이 페이지에서는 access, config, exposure, file, fqn, group, metric, package, path, resource_type, result, saved_query, selector, semantic_model, source, source_status, state, tag, test_name, test_type, unit_test, version 메서드를 다뤄요.

출처: 문서

본문

셀렉터 메서드는 method:value 문법을 사용해 공통 속성을 공유하는 모든 리소스를 반환해요. 메서드를 명시적으로 표기하는 것이 권장되지만, 생략할 수도 있어요(기본값은 path, file, fqn 중 하나가 돼요).

tip — 한 번의 --select 명령에서 쉼표(,)로 구분해(공백 없이) 여러 셀렉터 메서드를 결합할 수 있어요(예: dbt run --select "marts.finance,tag:nightly"). 이는 모든 인자를 충족하는 리소스만 선택해요. 이 예시에서 명령은 marts/finance 하위 디렉터리에 있고 nightly 태그가 붙은 모델만 실행해요. 자세한 내용은 Set operators를 참고하세요.

아래 메서드 중 다수는 Unix 스타일 와일드카드를 지원해요:

Wildcard	Description
*	matches any number of any characters (including none)
?	matches any single character
[abc]	matches one character given in the bracket
[a-z]	matches one character from the range given in the bracket

예를 들어:

dbt list --select "*.folder_name.*"
dbt list --select "package:*_source"

access

access 메서드는 모델을 access 속성 기준으로 선택해요.

dbt list --select "access:public"      # list all public models
dbt list --select "access:private"       # list all private models
dbt list --select "access:protected"       # list all protected models

config

config 메서드는 지정된 노드 config와 일치하는 모델을 선택하는 데 사용해요.

dbt run --select "config.materialized:incremental"    # run all models that are materialized incrementally
dbt run --select "config.schema:audit"              # run all models that are created in the `audit` schema
dbt run --select "config.cluster_by:geo_country"      # run all models clustered by `geo_country`

대부분의 config 값은 문자열이지만, config 메서드를 사용해 불리언 config, 사전 키, 리스트의 값을 일치시킬 수도 있어요.

예를 들어 다음 구성을 가진 모델이 있다고 할 때:

{{ config(
  materialized = 'incremental',
  unique_key = ['column_a', 'column_b'],
  grants = {'select': ['reporter', 'analysts']},
  meta = {"contains_pii": true},
  transient = true
) }}
select ...

다음 중 아무거나 사용해 선택할 수 있어요:

dbt ls -s config.materialized:incremental
dbt ls -s config.unique_key:column_a
dbt ls -s config.grants.select:reporter
dbt ls -s config.meta.contains_pii:true
dbt ls -s config.transient:true

exposure

exposure 메서드는 특정 exposure의 부모 리소스를 선택하는 데 사용해요. + 연산자와 함께 사용해요.

dbt run --select "+exposure:weekly_kpis"                # run all models that feed into the weekly_kpis exposure
dbt test --select "+exposure:*"                         # test all resources upstream of all exposures
dbt ls --select "+exposure:*" --resource-type source    # list all source tables upstream of all exposures

file

(dbt v1.11 이상) file 메서드는 파일 확장자(.sql)를 포함해 파일명으로 모델이나 함수를 선택하는 데 사용할 수 있어요.

# These are equivalent
dbt run --select "file:some_model.sql"
dbt run --select "some_model.sql"
dbt run --select "some_model"
# These are equivalent
dbt build --select "file:my_function.sql"
dbt build --select "my_function.sql"
dbt build --select "my_function"
# To build all models that use the function
dbt build --select "my_function+"

fqn

fqn 메서드는 dbt 그래프 안에서 "완전 자격 이름"(FQN)을 기준으로 노드를 선택하는 데 사용해요. dbt list의 기본 출력은 FQN 목록이에요. 기본 FQN 형식은 프로젝트 이름, 경로 내 하위 디렉터리, 그리고 (확장자 없는) 파일 이름을 마침표로 구분해 구성돼요.

dbt run --select "fqn:some_model"
dbt run --select "fqn:your_project.some_model"
dbt run --select "fqn:some_package.some_other_model"
dbt run --select "fqn:some_path.some_model"
dbt run --select "fqn:your_project.some_path.some_model"

group

group 메서드는 그룹 안에 정의된 모델을 선택하는 데 사용해요.

dbt run --select "group:finance" # run all models that belong to the finance group.

metric

metric 메서드는 특정 metric의 부모 리소스를 선택하는 데 사용해요. + 연산자와 함께 사용해요.

dbt build --select "+metric:weekly_active_users"       # build all resources upstream of weekly_active_users metric
dbt ls    --select "+metric:*" --resource-type source  # list all source tables upstream of all metrics

package

package 메서드는 루트 프로젝트나 설치된 dbt 패키지 안에 정의된 모델을 선택하는 데 사용해요. package: 접두사는 명시적으로 요구되진 않지만 셀렉터를 명확하게 만드는 데 사용할 수 있어요.

# These three selectors are equivalent
dbt run --select "package:snowplow"
dbt run --select "snowplow"
dbt run --select "snowplow.*"

this 패키지를 사용해 현재 프로젝트에서 노드를 선택해요. 예를 들어 snowplow 프로젝트에서 dbt run --select "package:this"를 실행하면 다른 세 셀렉터와 정확히 같은 모델 집합을 실행해요.

this는 항상 현재 프로젝트를 가리키므로 package:this를 사용하면 작업 중인 프로젝트의 모델만 선택하고 있음을 보장해요.

path

(dbt v1.11 이상) path 메서드는 특정 경로에 있거나 그 아래에 정의된 모델, 소스, 함수를 선택하는 데 사용해요. 모델 정의는 SQL/Python 파일(구성 YAML 아님)이고, 소스 정의는 YAML 파일이에요. 함수는 SQL 파일에 정의돼요. path: 접두사는 명시적으로 요구되진 않지만 셀렉터를 명확하게 만드는 데 사용할 수 있어요.

# These two selectors are equivalent
dbt run --select "path:models/staging/github"
dbt run --select "models/staging/github"
# These two selectors are equivalent
dbt run --select "path:models/staging/github/stg_issues.sql"
dbt run --select "models/staging/github/stg_issues.sql"
# These two selectors are equivalent
dbt build --select "path:functions/my_function.sql"
dbt build --select "functions/my_function.sql"

resource_type

(dbt v1.11 이상) resource_type 메서드를 사용해 특정 유형(model, test, exposure, function 등)의 노드를 선택해요. 이는 dbt build, dbt test, dbt clone, dbt list 명령이 사용하는 --resource-type 플래그와 비슷해요.

dbt build --select "resource_type:exposure"    # build all resources upstream of exposures
dbt build --select "resource_type:function"    # build all functions in your project
dbt list --select "resource_type:test"         # list all tests in your project
dbt list --select "resource_type:source"       # list all sources in your project

result

result 메서드는 state 메서드와 관련이 있으며, 이전 실행의 결과 상태를 기준으로 리소스를 선택하는 데 사용할 수 있어요. result 셀렉터가 동작하는 결과를 만들려면 [run, test, build, seed] dbt 명령 중 하나가 수행되어야 한다는 점을 참고하세요.

result 셀렉터는 + 연산자와 함께 사용할 수 있어요.

# run all models that generated errors on the prior invocation of dbt run
dbt run --select "result:error" --state path/to/artifacts
# run all tests that failed on the prior invocation of dbt test
dbt test --select "result:fail" --state path/to/artifacts
# run all the models associated with failed tests from the prior invocation of dbt build
dbt build --select "1+result:fail" --state path/to/artifacts
# run all seeds that generated errors on the prior invocation of dbt seed
dbt seed --select "result:error" --state path/to/artifacts

result:fail은 마지막 실행에서 실패한 테스트를 다시 실행하고 싶을 때만 사용해요. 이 셀렉터는 테스트 노드에 특화돼 있어요. 테스트는 DAG에 다운스트림 노드가 없으므로 result:fail+ 셀렉터를 사용하면 실패한 테스트 자체만 반환하고 모델이나 그 위에 빌드된 것은 반환하지 않아요.

반면 result:error는 오류를 반환한 모든 리소스(모델, 테스트, 스냅샷 등)를 선택해요.

예를 들어 실패한 테스트와 연관된 상·하류 리소스를 다시 실행하려면 다음 셀렉터 중 하나를 사용할 수 있어요:

# reruns all the models associated with failed tests from the prior invocation of dbt build
dbt build --select "1+result:fail" --state path/to/artifacts
# reruns the models associated with failed tests and all downstream dependencies - especially useful in deferred state workflows
dbt build --select "1+result:fail+" --state path/to/artifacts

saved_query

saved_query 메서드는 저장된 쿼리를 선택해요.

dbt list --select "saved_query:*"                    # list all saved queries
dbt list --select "+saved_query:orders_saved_query"  # list your saved query named "orders_saved_query" and all upstream resources

(dbt v1.12 이상) selector

selector 메서드는 selectors.yml의 명명된 YAML 셀렉터가 정의하는 노드를 선택해요. --select나 --exclude 문자열에서 사용해 명명된 셀렉터를 다른 메서드, 그래프 연산자, 집합 연산자와 조합할 수 있어요.

dbt run --select "selector:my_selector"          # same node set as `dbt run --selector my_selector`
dbt build --select "selector:staging selector:nightly"   # union (space-separated)
dbt build --select "selector:staging,selector:nightly"   # intersection (comma-separated)
dbt build --select "1+selector:staging"                  # graph operators
dbt build --select "selector:staging tag:nightly"        # combine with other methods
dbt run --select "selector:staging" --exclude "selector:exclude_tests"

레거시 --selector 플래그를 --select나 --exclude와 함께 사용하면 dbt는 노드 선택에 --selector만 사용하고 --select와 --exclude는 무시해요. dbt v1.12부터 dbt는 --selector가 --select나 --exclude와 결합될 때 SelectExcludeIgnoredWithSelectorWarning을 발생시켜요. 셀렉터를 이 플래그들과 결합하려면 selector: 메서드를 대신 사용하세요.

--select나 --exclude 없이 "비정규화" 명령을 실행하면, selectors.yml에 기본 셀렉터를 정의했다면 dbt가 그것을 적용해요. --select나 --exclude를 사용하면 dbt는 기본 셀렉터를 무시해요. --select나 --exclude 문자열에 셀렉터를 포함하려면 selector: 메서드를 사용해 명시적으로 참조해야 해요.

셀렉터 정의가 서로를 순환 참조하면 dbt는 런타임에 DbtRecursionError를 발생시켜요. 자세한 내용은 Selector inheritance를 참고하세요.

semantic_model

semantic_model 메서드는 시맨틱 모델을 선택해요.

dbt list --select "semantic_model:*"        # list all semantic models
dbt list --select "+semantic_model:orders"  # list your semantic model named "orders" and all upstream resources

source

source 메서드는 특정 소스에서 선택하는 모델을 선택하는 데 사용해요. + 연산자와 함께 사용해요.

dbt run --select "source:snowplow+"    # run all models that select from Snowplow sources
dbt run --select "source:snowplow.events+"    # run all models downstream of the events table in the Snowplow source

자세한 내용은 source FAQ를 참고하세요.

source_status

작업 상태의 또 다른 요소는 이전 dbt 실행의 source_status예요. 예를 들어 dbt source freshness를 실행한 후 dbt는 dbt 소스의 실행 시간과 max_loaded_at 날짜를 담은 sources.json 아티팩트를 생성해요. sources.json에 대한 자세한 내용은 'sources' 페이지를 참고하세요.

다음 dbt 명령어는 결과를 이후 dbt 실행에서 참조할 수 있는 sources.json 아티팩트를 생성해요:

• dbt source freshness

위 명령 중 하나를 실행한 후, 이후 명령에 셀렉터를 추가해 소스 freshness 결과를 참조할 수 있어요:

(dbt v1.11 이상)

# You can also set the DBT_ENGINE_STATE environment variable instead of the --state flag.
dbt source freshness # must be run again to compare current to previous state
dbt build --select "source_status:fresher+" --state path/to/prod/artifacts

state

N.B. 상태 기반 선택은 강력하고 복잡한 기능이에요. 상태 비교의 알려진 주의사항과 제한사항을 읽어 보세요.

state 메서드는 노드를 프로젝트의 이전 버전(매니페스트로 표현됨)과 비교해 선택하는 데 사용해요. 비교 매니페스트의 파일 경로는 --state 플래그 또는 (dbt v1.11 이상) DBT_ENGINE_STATE 환경 변수로 지정해야 해요.

• state:new: 비교 매니페스트에 같은 unique_id의 노드가 없음
• state:modified: 모든 새 노드 + 기존 노드에 대한 모든 변경

dbt test --select "state:new" --state path/to/artifacts      # run all tests on new models + and new tests on old models
dbt run --select "state:modified" --state path/to/artifacts  # run all models that have been modified
dbt ls --select "state:modified" --state path/to/artifacts   # list all modified nodes (not just models)

상태 비교는 복잡하고 프로젝트마다 다르기 때문에 dbt는 전체 수정 기준의 하위 집합을 포함하는 하위 셀렉터를 지원해요:

• state:modified.body: 노드 본문의 변경 (예: 모델 SQL, 시드 값)
• state:modified.configs: database/schema/alias/tags/meta를 제외한 노드 configs의 변경
• state:modified.relation: target 값이나 generate_x_name 매크로와 무관하게 database/schema/alias(이 노드의 데이터베이스 표현)의 변경
• state:modified.persisted_descriptions: 각 레벨에서 persist_docs가 활성화된 경우에만 relation 또는 column 레벨 description의 변경
• state:modified.macros: 업스트림 매크로의 변경 (다른 매크로에 의해 직접 또는 간접적으로 호출된 것)
• state:modified.contract: 모델 계약의 변경. 현재로써는 컬럼의 name과 data_type을 포함해요. 기존 컬럼을 제거하거나 유형을 바꾸는 것은 breaking change로 간주되며 오류를 발생시켜요.

state:modified에는 위의 모든 기준에 더해 소스의 freshness 또는 quoting 규칙을 수정하거나 exposure의 maturity 속성을 수정하는 것 같은 리소스별 기준도 포함된다는 점을 기억하세요. (소스, exposure, 실행 가능한 노드를 비교할 때 사용되는 전체 검사 집합은 소스 코드를 참고하세요.)

dbt는 tags와 meta를 리소스 레벨과 컬럼 레벨 모두에서 metadata 전용 필드로 취급하며, 수정으로 간주하지 않아요. tags나 meta 값을 변경하는 것(YAML 파일의 개별 컬럼 포함)은 state:modified를 트리거하지 않아요. 이 필드들은 dbt가 리소스를 materialize하는 방식에 영향을 주지 않기 때문이에요.

이는 (예를 들어) persist_docs가 활성화되었을 때 수정으로 간주되는 description과는 달라요. dbt는 그 config가 materialization에 영향을 줄 수 있으므로 다른 모든 config 변경을 수정으로 취급해요.

state:new와 state:modified를 보완하는 추가 state 셀렉터가 두 개 있으며, 이 함수들의 역을 나타내요:

• state:old — 비교 매니페스트에 같은 unique_id의 노드가 존재함
• state:unmodified — 변경이 없는 모든 기존 노드

이 셀렉터들은 변경되지 않은 노드를 제외해 실행 시간을 단축하는 데 도움이 될 수 있어요. 현재로써는 하위 셀렉터가 없지만, 사용 사례가 발전함에 따라 바뀔 수 있어요.

state:modified 노드와 참조 영향 (state:modified node and reference impacts)

state:modified는 추가된 모든 새 노드, 기존 노드의 변경, 그리고 다음에 대한 변경을 식별해요:

• access 권한
• deprecation_date
• latest_version

노드의 group이 변경되면 다운스트림 참조가 깨져 빌드 실패가 발생할 수 있어요.

group은 config이고 config는 일반적으로 state:modified 감지에 포함되므로, 참조된 모든 곳에서 group 이름을 수정하면 해당 노드들이 "modified"로 표시돼요.

부분 파싱이 활성화되어 있는지에 따라 CI 워크플로에서 이 깨짐을 잡을 수 있어요.

• 참조된 모든 곳에서 group 이름을 변경하고 부분 파싱이 활성화되어 있으면, dbt는 변경된 모델만 다시 파싱할 수 있어요.
• 부분 파싱 없이 모든 참조에서 group 이름을 업데이트하면 dbt는 모든 모델을 다시 파싱하고 잘못된 다운스트림 참조를 식별해요.

group 이름을 변경하고 dbt build --select state:modified로 실행하도록 잡힌 것이 있을 때 "there's nothing to do" 같은 오류가 발생할 수 있어요. CI 작업이 state:modified+(다운스트림 포함)를 선택하고 있다면 이 오류는 런타임에 잡혀요.

참조가 나중에 사용되거나 해석되는 방식에 영향을 줄 수 있는 특정 요소:

• access 수정: 권한이나 access 규칙이 변경되면 일부 참조가 동작을 멈출 수 있어요.
• deprecation_date 수정: 참조나 모델 버전이 deprecated로 표시되면 참조가 처리되는 방식에 영향을 줄 수 있는 새 경고가 나타날 수 있어요.
• latest_version 수정: 특정 버전에 고정되지 않으면 참조나 모델은 최신 버전을 가리켜요.
• 더 새로운 버전이 릴리스되면 참조는 자동으로 새 버전으로 해석되어, 그에 의존하는 시스템의 동작이나 출력이 바뀔 수 있어요.

dbt는 시드 파일의 상태 비교를 크기에 따라 다르게 처리해요:

• 1 MiB보다 작은 시드 파일: 내용이 변경된 경우에만 state:modified 셀렉터에 포함돼요.
• 1 MiB 이상인 시드 파일: 시드 파일 경로가 변경된 경우에만 state:modified 셀렉터에 포함돼요.

manifest.json 덮어쓰기 (Overwrites the manifest.json)

dbt는 파싱 중 manifest.json 파일을 덮어써요. 즉 target/ 디렉터리에서 --state를 참조하면 저장된 매니페스트를 찾을 수 없다는 경고가 발생할 수 있어요.

Saved manifest not found error — 다음 작업 실행 중 dbt는 이 문제로 이어지는 일련의 단계를 따릅니다. 먼저 변경 감지에 사용되기 전에 target/manifest.json을 덮어씁니다. 그런 다음 dbt가 변경을 감지하기 위해 target/manifest.json을 다시 읽으려고 하면, 이전 상태가 이미 덮어써졌기 때문에 찾지 못합니다.

--defer와 state:modified 같은 상태 의존 기능과 함께 --state와 --target-path를 같은 경로로 설정하지 마세요. 비멱등적(non-idempotent) 동작으로 이어져 예상대로 작동하지 않을 수 있어요.

권장사항 (Recommendation) — dbt가 변경 감지 전에 manifest.json을 덮어쓰는 것을 막으려면 다음 방법 중 하나로 워크플로를 업데이트하세요:

• dbt가 target/ 폴더에 manifest.json을 생성한 후 전용 폴더(예: state/)로 옮기기. 이렇게 하면 방금 덮어쓴 버전과 현재 상태를 비교하는 대신 dbt가 올바른 저장 상태를 참조하게 돼요. 또한 --state와 --target-path를 같은 위치로 설정해 비멱등적 동작을 일으키는 문제도 피할 수 있어요.
• 빌드 단계(dbt가 target/manifest.json을 생성할 곳)에서 또는 작업 실행 중 덮어쓰기 전에 매니페스트를 다른 --target-path에 쓰기. 이렇게 하면 방금 덮어쓴 버전과 현재 상태를 비교하는 대신 dbt가 변경을 감지할 수 있어요.
• 재현 단계에서 --no-write-json 플래그 전달하기: dbt ls --no-write-json --select state:modified --state target:.

tag

tag: 메서드는 지정된 태그와 일치하는 모델을 선택하는 데 사용해요.

dbt run --select "tag:nightly"    # run all models with the `nightly` tag

test_name

test_name 메서드는 그 테스트를 정의하는 generic 테스트의 이름을 기준으로 테스트를 선택하는 데 사용해요. generic 테스트가 정의되는 방식에 대한 자세한 내용은 data tests 문서를 읽어 보세요.

dbt test --select "test_name:unique"            # run all instances of the `unique` test
dbt test --select "test_name:equality"          # run all instances of the `dbt_utils.equality` test
dbt test --select "test_name:range_min_max"     # run all instances of a custom schema test defined in the local project, `range_min_max`

test_type

test_type 메서드는 테스트를 유형 기준으로 선택하는 데 사용해요:

• Unit tests
• Data tests:
  • Singular
  • Generic

dbt test --select "test_type:unit"           # run all unit tests
dbt test --select "test_type:data"           # run all data tests
dbt test --select "test_type:generic"        # run all generic data tests
dbt test --select "test_type:singular"       # run all singular data tests

unit_test

unit_test 메서드는 단위 테스트를 선택해요.

dbt list --select "unit_test:*"                        # list all unit tests
dbt list --select "+unit_test:orders_with_zero_items"  # list your unit test named "orders_with_zero_items" and all upstream resources

version

version 메서드는 버전 식별자와 최신 버전을 기준으로 버전이 있는 모델을 선택해요.

dbt list --select "version:latest"      # only 'latest' versions
dbt list --select "version:prerelease"  # versions newer than the 'latest' version
dbt list --select "version:old"         # versions older than the 'latest' version
dbt list --select "version:none"        # models that are *not* versioned

더 알아보기 (Learn more)

• Node selection syntax — 선택 문법 개요
• Set operators — 합집합·교집합
• State comparison caveats — 상태 비교 주의사항