CREATE DBT PROJECT

CREATE DBT PROJECT

새 dbt 프로젝트 객체를 만들거나 기존 dbt 프로젝트 객체를 교체하는 명령이에요. 이 명령은 프로젝트 파일을 versions/live에 배포해요.

출처: 문서

본문

새 dbt 프로젝트 객체를 만들거나 기존 dbt 프로젝트 객체를 교체해요. 이 명령은 프로젝트 파일을 versions/live에 배포해요.

참고: 이 페이지에 설명된 일부 기능은 변경 가능한 live 버전을 사용하는 dbt 프로젝트 객체가 필요해요. live 버전 객체를 얻으려면 2026_06 동작 변경 번들에 옵트인하거나 Snowflake 계정 담당자에게 별도의 단일 live 버전 기능을 활성화해 달라고 요청해요. 그런 다음 객체를 만들거나 교체하거나, 기존 버전 객체를 SYSTEM$MIGRATE_DBT_PROJECT으로 마이그레이션해요. 자세한 내용은 Snowflake의 dbt 프로젝트: dbt 프로젝트 객체가 단일 변경 가능한 live 버전으로 마이그레이션을 참고해요.

⚠️ 경고: CREATE OR REPLACE DBT PROJECT는 객체를 다시 만들며 실행 이력을 제거할 수 있어요. 기존 dbt 프로젝트 객체의 파일을 업데이트하려면 ALTER DBT PROJECT ... DEPLOY를 사용해요.

함께 보기: ALTER DBT PROJECT, DESCRIBE DBT PROJECT, EXECUTE DBT PROJECT, SHOW DBT PROJECTS, DROP DBT PROJECT

구문 (Syntax)

CREATE [ OR REPLACE ] DBT PROJECT [ IF NOT EXISTS ] <name>
  FROM '<source_location>'
  [ DBT_VERSION = <version_number> ]
  [ DEFAULT_TARGET = <default_target> ]
  [ DEFAULT_ENVIRONMENT = '<environment_name>' ]
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <integration_name> [ , ... ] ) ]
  [ AUTO_COMPILE = { TRUE | FALSE } ]
  [ DEFAULT_WRITEBACK = { TRUE | FALSE } ]
  [ COMMENT = '<string_literal>' ]

매개변수 (Parameters)

name dbt 프로젝트 객체의 이름을 지정하는 문자열로, dbt 프로젝트 객체가 만들어지는 스키마 안에서 고유해야 해요.

또한 식별자는 반드시 알파벳 문자로 시작해야 하며, 전체 식별자 문자열이 큰따옴표로 묶이지 않는 한 공백이나 특수 문자를 포함할 수 없어요 (예: "My object"). 큰따옴표로 묶인 식별자는 대소문자를 구분해요.

자세한 내용은 식별자 요구 사항(Identifier requirements)을 참고해요.

FROM 'source_location' 필수예요. dbt 프로젝트 소스 파일의 위치를 지정하는 문자열이에요.

소스 위치는 루트에 단일 dbt_project.yml 파일이 있는 디렉터리를 가리켜야 해요. 워크스페이스는 여러 dbt 프로젝트가 있는 저장소 작업을 지원하지만, dbt 프로젝트 객체를 배포할 때는 특정 프로젝트 디렉터리를 선택해야 해요.

dbt 프로젝트 객체 소스 파일은 다음 위치 중 하나에 있을 수 있어요.

• 내부 이름 지정 스테이지, 예:
  • '@my_db.my_schema.my_internal_named_stage/path/to/dbt_projects_or_projects_parent'
  • 내부 사용자 스테이지와 테이블 스테이지는 지원되지 않아요.
• dbt 워크스페이스, 예:
  • 'snow://workspace/user$.public."my_workspace_name"/versions/live'
  • 워크스페이스 URI는 versions/live를 사용하며, 이는 워크스페이스의 활성 작업 상태를 가리켜요. 워크스페이스 이름은 대소문자를 구분하고 특수 문자를 포함할 수 있으므로 큰따옴표로 감싸는 것을 권장해요.
• 기존 dbt 프로젝트 스테이지, 예:
  • 'snow://dbt/my_db.my_schema.my_existing_dbt_project_object/versions/live'
  • 버전 지정자는 필수이며 live예요.
• Git 저장소 스테이지, 예:
  • '@my_db.my_schema.my_git_repository_stage/branches/my_branch/path/to/dbt_project_or_projects_parent'
  • Git 저장소 객체와 스테이지 만들기·관리에 대한 자세한 내용은 Snowflake에서 Git 저장소 사용하기(Using a Git repository in Snowflake)와 CREATE GIT REPOSITORY를 참고해요.

COMMENT = 'string_literal' dbt 프로젝트 객체에 대한 설명(comment)을 지정해요.

• 기본값: 값 없음

DBT_VERSION = version_number dbt 프로젝트 객체에 대한 버전을 지정해요. 값을 지정하지 않으면 DEFAULT_DBT_VERSION 계정 매개변수로 설정된 버전이 기본값이 돼요. 자세한 내용은 계정 수준 기본 버전 설정(Set the account-level default version)을 참고해요.

AUTO_COMPILE = { TRUE | FALSE } Snowflake가 소스 파일 배포 후 dbt 프로젝트를 컴파일할지 지정해요.

• TRUE: 배포 중 dbt compile을 실행해요. 외부 접근 인티그레이션이 구성되어 있으면 Snowflake가 먼저 dbt deps를 실행한 뒤 dbt compile을 실행해요. 컴파일 아티팩트를 live 버전에 저장해요.
• FALSE: 두 명령을 모두 건너뛰어요. 나중에 EXECUTE DBT PROJECT로 둘 중 하나를 실행할 수 있어요.
• 기본값: TRUE

DEFAULT_WRITEBACK = { TRUE | FALSE } 후속 실행이 기본적으로 생성된 target과 log 파일을 live 버전에 다시 기록할지 지정해요. 개별 실행에 대해 EXECUTE DBT PROJECT의 WRITEBACK 매개변수로 이 값을 재정의할 수 있어요.

이 설정과 관계없이 Snowflake는 각 실행에 대해 쿼리별 결과 아티팩트와 아카이브를 별도로 저장해요.

• 기본값: TRUE

DEFAULT_TARGET = default_target dbt 프로젝트 객체의 컴파일과 후속 실행에 사용되는 프로파일(예: prod)을 지정해요. EXECUTE DBT PROJECT 명령을 ARGS = '--target <other_target>'로 사용해 이 매개변수를 재정의할 수 있어요.

• 기본값: 값 없음

DEFAULT_ENVIRONMENT = 'environment_name' dbt 프로젝트 객체의 컴파일과 후속 실행에 사용되는 기본 환경을 지정해요. 값은 프로젝트의 env.yml 파일에 정의된 환경을 식별해요. 이 속성을 설정하지 않으면 Snowflake가 env.yml의 default_environment:를 사용해요. EXECUTE DBT PROJECT 명령의 ENVIRONMENT 인자로 실행별로 재정의할 수 있어요. 예약된 이름 NO_ENV를 사용해 기본값으로 아무 환경 없이 실행해요.

• 기본값: 값 없음

자세한 내용은 Snowflake의 dbt 프로젝트용 SQL 환경 변수와 프라이빗 Git 패키지 사용(Using SQL environment variables and private Git packages for dbt Projects on Snowflake)을 참고해요.

EXTERNAL_ACCESS_INTEGRATIONS = ( integration_name [ , ... ] ) dbt 패키지 허브나 GitHub에서 원격 종속성을 가져오는 권한을 부여하는 데 사용되는 외부 접근 인티그레이션을 지정해요. 객체에 선언되면 dbt deps가 배포 중 자동으로 실행돼요.

이 설정은 dbt 프로젝트 객체를 배포(생성)할 때 사용돼요. 실행 중 명령이 외부 접근이 필요하면 EXECUTE DBT PROJECT 명령에서도 EXTERNAL_ACCESS_INTEGRATIONS를 지정할 수 있어요.

자세한 내용은 Snowflake의 dbt 프로젝트 종속성 이해(Understand dependencies for dbt Projects on Snowflake)를 참고해요.

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

이 작업을 실행하는 데 사용하는 역할(role)은 최소한 다음 권한을 가져야 해요.

권한 (Privilege)	객체 (Object)
CREATE DBT PROJECT	Schema

스키마 안의 객체를 작업하려면 상위 데이터베이스에 대한 권한이 최소 하나, 상위 스키마에 대한 권한이 최소 하나 필요해요.

지정된 권한 집합으로 사용자 지정 역할을 만드는 방법은 사용자 지정 역할 만들기(Creating custom roles)를 참고해요. 보호 가능한 객체에 대해 SQL 작업을 수행하기 위한 역할과 권한 부여의 일반적인 내용은 접근 제어 개요(Overview of Access Control)를 참고해요.

사용 메모 (Usage notes)

참고: CREATE DBT PROJECT는 이름이 지정된 데이터베이스와 스키마에 dbt 프로젝트 객체를 만들어요 (예: mydb.my_schema.my_project). FROM 절에서 워크스페이스를 소스로 사용할 수 있지만, 객체 이름은 항상 일반 이름 지정 데이터베이스와 스키마의 정규화된 경로여야 해요. 객체 이름에 워크스페이스 경로(예: USER$.PUBLIC.my_workspace)를 사용하려고 하면 명령이 실패해요.

OR REPLACE와 IF NOT EXISTS 절은 서로 배타적이에요. 같은 문에서 둘 다 사용할 수 없어요.

CREATE OR REPLACE <object> 문은 원자적(atomic)으로 동작해요. 즉, 객체를 교체할 때 기존 객체는 삭제되고 새 객체는 단일 트랜잭션 안에서 생성돼요.

메타데이터에 관해서는 다음 사항에 주의해요.

⚠️ 주의: 고객은 Snowflake 서비스를 사용할 때 (User 객체를 제외하고) 개인 데이터·민감 데이터·수출 통제 데이터·기타 규제 데이터를 메타데이터로 입력하지 않도록 해야 해요. 자세한 내용은 Snowflake의 메타데이터 필드를 참고해요.

예시 (Examples)

Snowflake의 Git 저장소 스테이지에서 dbt 프로젝트 객체 생성

Git 저장소 스테이지의 dbt 프로젝트 파일에서 sales_dbt_model이라는 dbt 프로젝트 객체를 만들어요. 이 예시는 Snowflake의 sales_dbt_git_stage라는 Git 저장소 스테이지의 main 브랜치를 참조하며, 프로젝트의 dbt_project.yml 파일이 저장소 루트에 저장되어 있어요. 또한 dbt 명령 실행 시 사용되는 기본 대상(target)과 프로젝트에 필요한 외부 접근 인티그레이션도 설정해요.

CREATE DBT PROJECT sales_db.dbt_projects_schema.sales_model
  FROM '@sales_db.integrations_schema.sales_dbt_git_stage/branches/main'
  DEFAULT_TARGET = 'prod'
  EXTERNAL_ACCESS_INTEGRATIONS = 'my_external_access_integration'
  COMMENT = 'Generates sales data models.';

Snowflake의 Git 저장소 스테이지 내 하위 디렉터리에서 dbt 프로젝트 객체 생성

여러 dbt 프로젝트가 포함된 Git 저장소 스테이지의 하위 디렉터리에서 sw_region_sales_model이라는 dbt 프로젝트 객체를 만들어요. 이 예시는 Snowflake의 sales_dbt_git_stage라는 Git 저장소 스테이지의 main 브랜치를 참조하며, 프로젝트의 dbt_project.yml 파일이 sales_dbt_projects_parent 디렉터리의 sw_region_dbt_project 하위 디렉터리에 저장되어 있어요.

이 예시는 다음 속성도 설정해요.

• dbt 버전
• Snowflake를 통해 실행되는 dbt 명령이 사용하는 기본 실행 대상 (예: prod 또는 dev)
• dbt 프로젝트 객체가 dbt 패키지 허브나 GitHub에서 원격 종속성을 가져오는 데 사용하도록 허용된 외부 접근 인티그레이션

CREATE DBT PROJECT sales_db.dbt_projects_schema.sw_region_sales_model
  FROM '@sales_db.integrations_schema.sales_dbt_git_stage/branches/main/sales_dbt_projects_parent/sw_region_dbt_project'
  DBT_VERSION = '1.11.11'
  DEFAULT_TARGET = 'prod'
  EXTERNAL_ACCESS_INTEGRATIONS = 'my_external_access_integration'
  COMMENT = 'Generates data models for SW sales region.';

기존 dbt 프로젝트 객체의 live 버전에서 dbt 프로젝트 객체 생성

기존 sales_model dbt 프로젝트 객체의 live 버전에서 sales_model_nw_region이라는 새 dbt 프로젝트 객체를 만들어요.

이 예시는 DEFAULT_TARGET으로 기본 실행 대상을 설정하고, EXTERNAL_ACCESS_INTEGRATIONS로 허용된 외부 접근 인티그레이션을 지정해요.

CREATE DBT PROJECT sales_db.dbt_projects_schema.sales_model_nw_region
  FROM 'snow://dbt/sales_db.dbt_projects_schema.sales_model/versions/live'
  DEFAULT_TARGET = 'prod'
  EXTERNAL_ACCESS_INTEGRATIONS = (my_ext_integration_1, my_ext_integration_2)
  COMMENT = 'Generates data models for the NW sales region.';

여러 dbt 프로젝트가 포함된 워크스페이스에서 dbt 프로젝트 객체 생성

여러 dbt 프로젝트 디렉터리가 포함된 워크스페이스의 live 버전에서 sales_model_from_workspace라는 새 dbt 프로젝트 객체를 만들어요. 사용자의 개인 데이터베이스 안에 있는 "My dbt Project Workspace"예요. 워크스페이스에 여러 하위 프로젝트가 있고 특정 하위 디렉터리에서 dbt 프로젝트 객체를 만들고 싶을 때 유용해요. 워크스페이스는 대소문자를 구분하고 특수 문자를 포함할 수 있으므로 워크스페이스 이름을 큰따옴표로 감싸는 것을 권장해요.

CREATE DBT PROJECT sales_db.dbt_projects_schema.sales_model_from_workspace
  FROM 'snow://workspace/user$.public."My dbt Project Workspace"/versions/live/project2'

EXECUTE DBT PROJECT sales_db.dbt_projects_schema.sales_model_from_workspace
  ARGS = 'run --target prod';

더 알아보기 (Learn more)

• ALTER DBT PROJECT — dbt 프로젝트 객체 수정
• EXECUTE DBT PROJECT — dbt 프로젝트 객체 실행
• SHOW DBT PROJECTS — dbt 프로젝트 객체 조회