EXECUTE DBT PROJECT

지정한 dbt project 객체 또는 Snowflake 워크스페이스의 dbt project를, 지정한 dbt 명령과 명령줄 옵션으로 실행하는 명령이에요.

출처: 문서

본문

참고: 이 페이지에 설명된 일부 기능은 변경 가능한 라이브 버전(live version)을 사용하는 dbt project 객체가 필요해요. 라이브 버전 객체를 얻으려면 2026_06 행동 변경 번들이나 별도 단일 라이브 버전 기능을 활성화한 뒤, 객체를 생성/교체하거나 SYSTEM$MIGRATE_DBT_PROJECT로 기존 버전 객체를 마이그레이션해야 해요.

구문 (Syntax)

지정된 이름의 dbt project 객체를 실행해요:

EXECUTE DBT PROJECT [ IF EXISTS ] <name>
  [ ARGS = '[ <dbt_command> ] [ --<dbt_cli_option> <option_value_1> [ ... ] ] [ ... ]' ]
  [ DBT_VERSION = 'version_number' ]
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <integration_name> [ , ... ] ) ]
  [ ENVIRONMENT = '<environment_name>' ]
  [ ENV_VARS = ( '<key>' = '<value>' [ , ... ] ) ]
  [ IMPORTS = ( { '<source_location>' | <system_function> } [ AS '<alias>' ] [ , ... ] ) ]
  [ WRITEBACK = { TRUE | FALSE } ]

변형 구문 (Variant syntax)

지정된 워크스페이스 이름으로 워크스페이스에 저장된 dbt project를 실행해요. 워크스페이스를 소유한 사용자가 이 명령 변형을 실행하는 사용자와 같아야 해요.

EXECUTE DBT PROJECT [ IF EXISTS ] [ FROM WORKSPACE <workspace_name> ]
  [ ARGS = '[ <dbt_command> ] [ --<dbt_cli_option> <option_value_1> [ ... ] [ ... ] ]' ]
  [ DBT_VERSION = 'version_number' ]
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <integration_name> [ , ... ] ) ]
  [ ENVIRONMENT = '<environment_name>' ]
  [ ENV_VARS = ( '<key>' = '<value>' [ , ... ] ) ]
  [ PROJECT_ROOT = '<subdirectory_path>' ]

필수 파라미터 (Required parameters)

name — dbt project 객체를 실행할 때는 실행할 dbt project 객체의 이름을 지정해요. FROM WORKSPACE 옵션으로 dbt project를 실행할 때는 dbt Projects on Snowflake용 워크스페이스 이름을 지정해요. 워크스페이스 이름은 항상 사용자의 개인 데이터베이스의 public 스키마를 기준으로 지정되며, user$로 표시돼요. 워크스페이스 이름은 대소문자를 구분하고 특수 문자를 포함할 수 있으므로 큰따옴표로 묶는 것을 권장해요. 다음 예시는 워크스페이스 이름 참조를 보여줘요: user$.public."My dbt Project Workspace"

선택 파라미터 (Optional parameters)

ARGS = '[ dbt_command ] [ --dbt_cli_option option_value_1 [ ... ] [ ... ] ]' — dbt project 객체가 실행될 때 사용할 dbt 명령과 지원되는 명령줄 옵션을 지정해요. dbt CLI 명령의 구문과 요구사항을 따라야 하는 리터럴 문자열이에요. 값이 지정되지 않으면 dbt project 객체 정의에 지정된 dbt 명령과 명령줄 옵션으로 실행돼요. dbt 명령 없이 dbt CLI 옵션만 지정하면 dbt run 명령이 기본 실행돼요. 기본값: 없음
DBT_VERSION = 'version_number' — dbt project 객체의 버전을 지정해요. 기본값: dbt project 객체 실행 시 시스템은 객체 생성 시 지정한 기본 버전을 사용해요. 지정하지 않으면 기본적으로 1.9.4를 사용해요.
PROJECT_ROOT = 'subdirectory_path' — dbt project 객체 또는 워크스페이스 내에서 dbt_project.yml 파일까지의 하위 디렉토리 경로를 지정해요. 이 파라미터는 FROM WORKSPACE 옵션으로 dbt project를 실행할 때만 지원돼요. 값이 지정되지 않으면 dbt project 객체의 루트 디렉토리에 있는 dbt_project.yml 파일로 실행돼요. 루트 디렉토리나 PROJECT_ROOT 하위 디렉토리에 dbt_project.yml 파일이 없으면 오류가 발생해요. 기본값: 없음
EXTERNAL_ACCESS_INTEGRATIONS = ( integration_name [ , ... ] ) — dbt의 외부 엔드포인트로의 아웃바운드 네트워크 접근을 허용하는 외부 액세스 통합(external access integration)을 지정해요. 대부분 dbt가 실행 중 dbt deps 실행 시 dbt package hub나 GitHub 같은 Git 제공자에서 원격 패키지를 가져올 수 있게 해줘요. 실행 중 외부 접근이 필요한 명령(예: dbt deps)이 있으면 EXECUTE DBT PROJECT 명령에 EXTERNAL_ACCESS_INTEGRATIONS를 지정해요. 이는 프로젝트가 env.yml 파일에서 Snowflake 시크릿을 해석하여 프라이빗 Git 패키지를 인증하는 경우에도 해당돼요.
ENVIRONMENT = 'environment_name' — 이번 실행을 위해 프로젝트의 env.yml 파일에 정의된 명명된 환경을 선택해요. 이 환경은 dbt가 실행되기 전에 주입되는 환경 변수와 시크릿의 집합을 결정해요. 이 인자는 환경 선택에서 가장 높은 우선순위를 가지며, dbt project 객체에 설정된 DEFAULT_ENVIRONMENT와 env.yml의 default_environment를 재정의해요. 환경 없이 실행하려면 예약된 이름 NO_ENV를 사용해요. 기본값: dbt project 객체의 DEFAULT_ENVIRONMENT, 또는 설정되지 않았다면 env.yml의 default_environment:.
ENV_VARS = ( 'key' = 'value' [ , ... ] ) — 단일 실행을 위해 개별 환경 변수를 재정의해요. 이 재정의는 선택된 환경에 병합되며 env.yml의 값보다 최종 우선순위를 가져요. 키는 DBT_ 접두사와 대문자여야 해요. 값은 단일 VARCHAR 값으로 해석되는 SQL, 문자열 리터럴, 세션 변수($var), 바인드 플레이스홀더(?)가 될 수 있어요. ENV_VARS에서 Snowflake 시크릿을 직접 참조할 수 없어요. 시크릿은 env.yml 파일을 통해 관리해야 해요. 기본값: 없음
IMPORTS = ( { 'source_location' | system_function } [ AS 'alias' ] [ , ... ] ) — 배포된 dbt project 객체를 실행할 때 하나 이상의 소스 위치에서 파일을 프로젝트의 ./imports 디렉토리에서 사용할 수 있게 해요. 스테이지, 배포된 dbt project 객체, 워크스페이스, 또는 다음 시스템 함수 중 하나에서 가져올 수 있어요:
- SYSTEM$DBT_GET_LAST_SUCCESSFUL_RUN_TARGET
- SYSTEM$DBT_GET_LAST_FAILED_RUN_TARGET
- SYSTEM$DBT_GET_LAST_RUN_TARGET
- SYSTEM$LOCATE_DBT_ARTIFACTS
- SYSTEM$LOCATE_DBT_ARCHIVE
IMPORTS에서는 다른 시스템 함수는 지원되지 않아요. import의 하위 디렉토리 이름을 지정하려면 AS '<alias>'를 사용해요. 예를 들어 AS 'state'는 가져온 파일을 ./imports/state에 마운트해요. ARGS의 --state 옵션은 마운트된 디렉토리를 가리켜야 해요. IMPORTS만으로는 dbt가 파일을 state로 사용하도록 지시하지 않아요. 별칭이 없으면 Snowflake는 {소문자 객체 이름}_{소문자 마지막 폴더 이름} 형태의 소문자 디렉토리 이름을 유도해요. 예를 들어 @my_dbt_project/target/는 ./imports/my_dbt_project_target에, DBT_PROD라는 dbt project 객체의 target 디렉토리는 ./imports/dbt_prod_target에 마운트돼요. 더 짧고 예측 가능한 경로를 원할 때 별칭을 사용해요. IMPORTS 목록에는 최대 하나의 ZIP 파일만 포함할 수 있어요. 가져오려면 SYSTEM$LOCATE_DBT_ARCHIVE 시스템 함수를 사용하며, 이 함수는 dbt project 객체의 results stage에서 아카이브를 반환해요. 다른 소스 위치의 ZIP 파일은 지원되지 않아요. Snowflake가 아카이브를 자동으로 압축 해제해요. dbt project 객체의 가장 최근 성공적인 실행의 dbt 아티팩트에는 SYSTEM$DBT_GET_LAST_SUCCESSFUL_RUN_TARGET를 사용해요. 특정 쿼리에서 dbt 아티팩트를 가져오려면 SYSTEM$LOCATE_DBT_ARTIFACTS를 사용해요. 이 함수는 쿼리의 results 디렉토리를 마운트하므로 dbt 아티팩트는 ./imports/<alias>/target 아래에 있어요. 기본값: 없음
WRITEBACK = { TRUE | FALSE } — 배포된 dbt project 객체를 실행할 때 이번 실행을 위해 그 객체의 DEFAULT_WRITEBACK 속성을 재정의해요:
- TRUE — 생성된 target 및 log 파일을 변경 가능한 라이브 버전에 다시 써요.
- FALSE — 생성된 target 및 log 파일을 라이브 버전에 다시 쓰지 않아요. 라이브 버전을 업데이트할 필요가 없는 동시(concurrent) 실행에는 Snowflake가 WRITEBACK = FALSE를 권장해요. 쓰기백이 필요하면 각 실행에 대해 겹치지 않는 별도의 target 및 log 디렉토리를 사용해요. Snowflake는 이 설정과 관계없이 쿼리별 결과 아티팩트와 아카이브를 저장해요. 기본값: dbt project 객체의 DEFAULT_WRITEBACK 값.

출력 (Output)

Column	Description
Success	dbt project 객체가 성공적으로 실행되었으면 TRUE, 그렇지 않으면 FALSE. 실행에 실패하면 예외 메시지가 반환돼요.
EXCEPTION	dbt project 실행이 반환한 예외 메시지. 성공 시 문자열 None이 반환돼요.
STDOUT	dbt project 실행이 반환한 표준 출력.
OUTPUT_ARCHIVE_URL	dbt project 실행의 출력 파일을 포함하는 출력 아카이브의 URL. dbt가 `/target` 디렉토리에 쓰는 log 파일과 아티팩트를 포함해요. 이 링크를 직접 선택하면 오류가 발생하지만, 이 URL로 dbt project 파일과 출력을 검색할 수 있어요.

접근 제어 요구사항 (Access control requirements)

이 SQL 명령을 실행하는 역할은 최소한 다음 권한 중 하나를 가져야 해요:

Privilege	Object
USAGE	dbt project

스키마에서 객체를 운영하려면 부모 데이터베이스에 대한 권한이 하나 이상, 부모 스키마에 대한 권한이 하나 이상 필요해요.

참고: EXECUTE DBT PROJECT에 지정된 dbt 명령은 프로젝트의 dbt_projects_profiles.yml 또는 profiles.yml 파일의 outputs 블록에 지정된 역할의 권한으로 실행돼요. 작업은 EXECUTE DBT PROJECT를 호출하는 Snowflake 사용자에게 부여된 권한으로만 더 제한돼요. 사용자와 지정된 역할 모두 웨어하우스 사용, 프로필 파일에 지정된 데이터베이스와 스키마에 대한 작업, dbt 모델이 지정하는 다른 Snowflake 객체에 대한 작업에 필요한 권한을 가져야 해요. 두 파일이 모두 있으면 Snowflake는 dbt_projects_profiles.yml을 사용해요.

예시 (Examples)

기본 run 명령 (target과 models 지정)

dbt project 객체의 루트 디렉토리 dbt_project.yml 파일에서 dev 프로필을 대상으로 dbt run을 실행하고 프로젝트 DAG에서 3개의 모델을 선택해요. run 명령이 명시되지 않아 기본 실행돼요.

EXECUTE DBT PROJECT my_database.my_schema.my_dbt_project
  ARGS = '--select simple_customers combined_bookings prepped_data --target dev';

명시적 test 명령 (target과 models 지정)

dbt project 객체의 루트 디렉토리 dbt_project.yml 파일에서 prod 프로필을 대상으로 dbt test 명령을 실행하고 프로젝트 DAG에서 3개의 모델을 선택해요.

EXECUTE DBT PROJECT my_database.my_schema.my_dbt_project
  ARGS = '--select simple_customers combined_bookings prepped_data --target prod';

명시적 run 명령 (하위 모델 지정)

dbt_project.yml 파일에서 dev 프로필을 대상으로 dbt run 명령을 실행하고, dbt + 표기법을 사용하여 simple_customers 모델의 모든 하위 모델을 선택해요.

EXECUTE DBT PROJECT my_database.my_schema.my_dbt_project
  ARGS = 'run --select simple_customers+ --target dev';

프로덕션 프로젝트에서 state를 가져와 변경된 모델 실행

프로덕션 dbt project 객체의 가장 최근 성공적인 실행의 dbt 아티팩트를 가져와요. state 별칭은 반환된 아티팩트를 ./imports/state에 마운트해요. dbt 인자는 현재 프로젝트를 그 아티팩트와 비교하고, 변경된 노드와 그 하위 의존성을 선택하며, 빌드되지 않은 노드의 참조를 지연(defer)시켜요:

EXECUTE DBT PROJECT ci_database.dbt_projects.pr_test_project
  ARGS = 'run --state ./imports/state --defer --select state:modified+'
  IMPORTS = (
    SYSTEM$DBT_GET_LAST_SUCCESSFUL_RUN_TARGET(
      'prod_database.dbt_projects.production_project'
    ) AS 'state'
  );

이 문장을 실행하는 역할은 prod_database.dbt_projects.production_project에 대한 MONITOR 권한이 있어야 해요. 해당 객체는 지난 7일 이내에 성공적인 실행이 있어야 해요.

특정 쿼리에서 state를 가져와 변경된 모델 실행

SYSTEM$LOCATE_DBT_ARTIFACTS로 특정 dbt project 실행의 results 디렉토리를 가져와요. state 별칭은 디렉토리를 ./imports/state에 마운트하고, dbt 아티팩트는 그 target 하위 디렉토리에 있어요:

EXECUTE DBT PROJECT ci_database.dbt_projects.pr_test_project
  ARGS = 'run --state ./imports/state/target --defer --select state:modified+'
  IMPORTS = (
    SYSTEM$LOCATE_DBT_ARTIFACTS(
      '01c6a772-001e-db19-0000-5349650b6cfe'
    ) AS 'state'
  );

results stage에서 ZIP 아카이브 가져오기

SYSTEM$LOCATE_DBT_ARCHIVE는 ZIP 파일을 가져오는 지원되는 방법이에요. 이 함수는 dbt project 객체의 results stage에서 아카이브를 반환해요. IMPORTS 목록에는 최대 하나의 ZIP 파일만 포함할 수 있어요. 다른 소스 위치의 ZIP 파일은 지원되지 않아요. Snowflake가 아카이브를 자동으로 압축 해제해요:

EXECUTE DBT PROJECT ci_database.dbt_projects.pr_test_project
  ARGS = 'run --state ./imports/archive --defer --select state:modified+'
  IMPORTS = (
    SYSTEM$LOCATE_DBT_ARCHIVE(
      '01c6a772-001e-db19-0000-5349650b6cfe'
    ) AS 'archive'
  );

Snowflake가 마운트 디렉토리 이름을 생성하게 하려면 AS '<alias>'를 생략해요. 예를 들어 쿼리 ID가 PROD_PROJECT라는 dbt project 객체의 실행을 식별하면, Snowflake는 아카이브를 ./imports/prod_project_dbt_artifacts/ 아래에 압축 해제해요:

EXECUTE DBT PROJECT ci_database.dbt_projects.pr_test_project
  ARGS = 'run --state ./imports/prod_project_dbt_artifacts/target --defer --select state:modified+'
  IMPORTS = (
    SYSTEM$LOCATE_DBT_ARCHIVE('')
  );

dbt project 객체를 동시에 실행

같은 dbt project 객체의 동시 실행에서 실행들이 target과 log 아티팩트를 라이브 버전에 유지할 필요가 없을 때 Snowflake는 WRITEBACK = FALSE를 권장해요. 이는 실행들이 겹치는 target과 log 디렉토리에 아티팩트를 쓰는 것을 방지해요. Snowflake는 쿼리별 결과 아티팩트를 계속 저장해요.

각 동시 실행에 WRITEBACK = FALSE를 사용해요:

EXECUTE DBT PROJECT my_database.my_schema.my_dbt_project
  ARGS = 'run --target prod'
  WRITEBACK = FALSE;

프로덕션 태스크로 dbt project 객체 실행 및 테스트

6시간 간격으로 dbt run 명령을 실행하는 프로덕션 dbt target용 태스크를 만들고, 각 dbt run 태스크가 완료된 후 dbt test 명령을 실행하는 태스크를 만들어요. 각 태스크의 EXECUTE DBT PROJECT 명령은 dbt project 객체의 루트 디렉토리 dbt_project.yml 파일의 prod 프로필을 대상으로 해요.

CREATE OR ALTER TASK my_database.my_schema.run_dbt_project
  WAREHOUSE = my_warehouse
  SCHEDULE = '6 hours'
AS
  EXECUTE DBT PROJECT my_database.my_schema.my_dbt_project args='run --target prod';

CREATE OR ALTER TASK change_this.public.test_dbt_project
        WAREHOUSE = my_warehouse
        AFTER run_dbt_project
AS
  EXECUTE DBT PROJECT my_database.my_schema.my_dbt_project args='test --target prod';

테스트 또는 임시 목적으로 실행 시 프로젝트의 고정 버전 재정의

my_dbt_project는 1.9.4에 고정되어 있어요. 이 실행은 dbt project 객체의 기본 1.9.4 버전을 재정의해요:

EXECUTE DBT PROJECT finance_analytics
  DBT_VERSION = '1.11.11'

실행 시 환경 선택 및 변수 재정의

env.yml에 정의된 prod 환경으로 실행하되, 이번 실행에서 단일 변수를 재정의해요:

EXECUTE DBT PROJECT my_database.my_schema.my_dbt_project
  ARGS = 'run --target prod'
  ENVIRONMENT = 'prod'
  ENV_VARS = ( 'DBT_DATABASE' = 'tasty_bytes_staging_db' );

더 알아보기 (Learn more)

본문