문법 개요

문법 개요 (Syntax overview)

dbt의 노드 선택 문법은 특정 dbt 실행에서 특정 리소스만 실행할 수 있게 해줘요. --select, --exclude, 그 외 플래그로 노드를 지정하고, 셀렉션 메서드·그래프 연산자·집합 연산자 순서로 해석하는 방법을 다뤄요.

출처: 문서

본문

dbt의 노드 선택 문법은 특정 dbt 실행에서 특정 리소스만 실행할 수 있게 해줘요. 이 선택 문법은 다음 하위 명령에 사용돼요:

(dbt v1.12 이상)

command argument(s)
run --select, --exclude, --defer
test --select, --exclude, --defer
seed --select, --exclude
snapshot --select, --exclude
ls (list) --select, --exclude, --resource-type
compile --select, --exclude, --inline
freshness --select, --exclude
build --select, --exclude, --resource-type, --defer
docs generate --select, --exclude

노드와 리소스 (Nodes and resources)

"노드"와 "리소스"라는 용어를 같은 의미로 사용해요. 이들은 프로젝트의 모든 모델, 테스트, 소스, 시드, 스냅샷, exposure, 분석을 포함해요. 이들은 dbt의 DAG(directed acyclic graph)를 구성하는 객체들이에요.

(dbt v1.12 이상) --select 또는 --exclude와 함께 selector: 메서드를 사용해 명명된 셀렉터를 참조할 수 있어요. 자세한 내용은 selector: method를 참고하세요.

리소스 지정 (Specifying resources)

기본적으로 dbt run은 의존성 그래프의 모든 모델을 실행하고, dbt seed는 모든 시드를, dbt snapshot은 모든 스냅샷을 수행해요. --select 플래그는 실행할 노드 하위 집합을 지정하는 데 사용해요.

POSIX 표준을 따르고 더 이해하기 쉽게 만들기 위해, CLI 사용자가 --select나 --exclude 옵션에 인자를 전달할 때(단일 또는 다중 공백 구분, 또는 쉼표 구분 인자 포함) 따옴표를 사용하기를 권장해요. 따옴표를 쓰지 않으면 모든 운영 체제, 터미널, 사용자 인터페이스에서 안정적으로 동작하지 않을 수 있어요. 예를 들어 dbt run --select "my_dbt_project_name"은 프로젝트의 모든 모델을 실행해요.

선택은 어떻게 동작하나? (How does selection work?)

dbt는 하나 이상의 --select 기준에 일치하는 모든 리소스를 선택 메서드(예: tag:) 순서, 그다음 그래프 연산자(예: +), 마지막으로 집합 연산자(합집합, 교집합, 제외) 순서로 모아요.

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

선택된 리소스는 모델, 소스, 시드, 스냅샷, 테스트일 수 있어요. (테스트는 부모를 통해 "간접적으로"도 선택될 수 있어요. 자세한 내용은 test selection examples를 참고하세요.)

dbt에는 이제 다양한 유형의 여전히 선택된 리소스 목록이 있어요. 마지막 단계로, 현재 작업의 리소스 유형과 일치하지 않는 리소스는 버려요. (dbt seed는 시드만, dbt run은 모델만, dbt test는 테스트만 유지하는 식이에요.)

줄임말 (Shorthand)

리소스를 빌드(run, test, seed, snapshot)하거나 freshness를 확인하려면 --select, -s를 사용해요.

예시 (Examples)

기본적으로 dbt run은 의존성 그래프의 모든 모델을 실행해요. 개발(및 배포) 중에는 실행할 모델 하위 집합만 지정하는 것이 유용해요. dbt run과 함께 --select 플래그를 사용해 실행할 모델 하위 집합을 선택하세요. (dbt v1.12 이상) 다음 인자들(--select와 --exclude)은 test와 build 같은 다른 dbt 작업에도 적용된다는 점을 참고하세요.

Examples of select flag · Examples of subsets of nodes

--select 플래그는 하나 이상의 인자를 받아요. 각 인자는 다음 중 하나일 수 있어요:

  • 패키지 이름
  • 모델 이름
  • 모델 디렉터리의 완전 자격 경로
  • 선택 메서드 (path:, tag:, config:, test_type:, test_name:, selector:)

예시:

dbt run --select "my_dbt_project_name"   # runs all models in your project
dbt run --select "my_dbt_model"          # runs a specific model
dbt run --select "path/to/my/models"     # runs all models in a specific directory
dbt run --select "my_package.some_model" # run a specific model in a specific package
dbt run --select "tag:nightly"           # run models with the "nightly" tag
dbt run --select "path/to/models"        # run models contained in path/to/models
dbt run --select "path/to/my_model.sql"  # run a specific model by its path
dbt run --select "selector:my_selector"  # run the node set defined by the named selector in selectors.yml; available starting v1.12

dbt는 노드 하위 집합을 정의하기 위한 줄임말 언어를 지원해요. 이 언어는 다음 문자를 사용해요:

  • plus operator (+)
  • at operator (@)
  • asterisk operator (*)
  • comma operator (,)

예시:

# multiple arguments can be provided to --select
dbt run --select "my_first_model my_second_model"
# select my_model and all of its children
dbt run --select "my_model+"
     # select my_model, its children, and the parents of its children
dbt run --select @my_model
          # these arguments can be projects, models, directory paths, tags, or sources
dbt run --select "tag:nightly my_model finance.base.*"
# use methods and intersections for more complex selectors
dbt run --select "path:marts/finance,tag:nightly,config.materialized:table"
# combine a named selector with another method
dbt run --select "selector:staging,tag:nightly"

선택 로직이 더 복잡해져서 명령줄 인자로 입력하기 어려워지면 yaml 셀렉터를 사용하는 것을 고려해 보세요.

(dbt v1.12 이상) --select나 --exclude 사용 시 selector: 메서드로 미리 정의된 셀렉터를 참조할 수 있어요. 자세한 내용은 selector: method를 참고하세요.

ls 명령으로 문제 해결 (Troubleshoot with the ls command)

선택 문법을 구성하고 디버깅하는 것은 어려울 수 있어요. 무엇이 선택될지 "미리 보기"하려면 list 명령을 사용하기를 권장해요. 이 명령은 선택 문법과 결합하면 그 선택 기준을 충족하는 노드 목록을 출력해요. dbt ls 명령은 모든 유형의 선택 문법 인자를 지원해요. 예를 들어:

dbt ls --select "path/to/my/models" # Lists all models in a specific directory.
dbt ls --select "source_status:fresher+" # Shows sources updated since the last dbt source freshness run.
dbt ls --select state:modified+ # Displays nodes modified in comparison to a previous state.
dbt ls --select "result:<status>+" state:modified+ --state ./<dbt-artifact-path> # Lists nodes that match certain result statuses and are modified.

더 알아보기 (Learn more)