dbt 프로젝트 객체 이해하기

dbt 프로젝트 객체 이해하기

DBT PROJECT는 Snowflake에 배포된 dbt 프로젝트의 소스 파일과 아티팩트를 담는 스키마 수준(schema-level) 객체예요. 그 프로젝트 디렉터리에는 루트에 dbt_project.yml 파일과 데이터 파이프라인을 정의하는 모델 파일이 포함돼 있어요.

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

출처: Snowflake 문서

본문

dbt 프로젝트 객체는 live라는 가변 버전 하나를 가져요. 파일은 다음 형태의 경로에서 사용할 수 있어요:

snow://dbt/<database>.<schema>.<project>/versions/live

dbt 프로젝트를 배포하면 Snowflake가 워크스페이스, Git 저장소 스테이지, 내부 스테이지, 또는 로컬 디렉터리에서 파일을 이 live 버전으로 복사해요. 워크스페이스는 Snowsight나 CI/CD 파이프라인을 통해 dbt 프로젝트 객체에 배포하기 전에 dbt 코드를 편집하고 디버깅할 수 있는 개발 환경이에요.

dbt 프로젝트 객체는 역할 기반 접근 제어(RBAC)를 지원해요. Snowflake의 다른 스키마 수준 객체처럼 생성·변경·삭제할 수 있어요. Snowflake 웨어하우스에서 EXECUTE DBT PROJECT 명령을 사용해 test, run 같은 dbt 명령을 실행할 수 있어요. 태스크를 사용해 이 명령들의 실행을 스케줄할 수도 있어요.

dbt 프로젝트 객체를 만드는 이점

  • 모든 오케스트레이터에서 실행: SQL 클라이언트, Snowflake 태스크, 또는 Apache Airflow 같은 외부 오케스트레이터에서 EXECUTE DBT PROJECT를 사용할 수 있어요.
  • 모니터링과 관측성: 각 dbt 프로젝트 객체 실행은 OpenTelemetry 호환 로그와 추적을 Snowflake Event Table로 보내요. 사용자는 DBT_PROJECT_EXECUTION_HISTORY와 SYSTEM$GET_DBT_LOG를 사용해 쿼리 기록 세부 정보에 프로그래밍 방식으로 접근해요. 자세한 내용은 dbt Projects on Snowflake 모니터링 문서를 참조하세요.
  • CI/CD 통합: Snowflake CLI(snow dbt deploy)를 사용해 매 머지마다 live 프로젝트를 자동으로 업데이트해요. 전체 워크스루는 dbt Projects on Snowflake에서 CI/CD 통합 설정 튜토리얼을 참조하세요.
  • 재사용 가능한 실행 아티팩트: 이전 실행의 dbt 아티팩트를 Slim CI, defer to production, 부분 파싱(partial parsing), 실패한 실행 복구에 재사용해요. 실행 결과 시스템 함수(예: SYSTEM$DBT_GET_LAST_SUCCESSFUL_RUN_TARGET)로 검색해요.
  • Cortex를 통한 AI 지원 디버깅: Cortex AI는 배포된 프로젝트 파일과 혈통(lineage)을 검사할 수 있어요. 실행이 실패하면 Cortex에 자연어 질문을 해서 배포된 객체 파일로 직접 문제를 진단할 수 있어요.
  • 실시간 프로젝트 문서: 프로젝트 세부 정보 페이지는 대화형 DAG, 컬럼 수준 혈통, 컴파일된 SQL, 전체 실행 기록을 갖춘 인제품(in-product) dbt docs 대체품이에요. 자세한 내용은 dbt 프로젝트 객체 보기 및 관리 문서를 참조하세요.

dbt 프로젝트 객체가 업데이트되는 방식

dbt 프로젝트 객체는 소스 워크스페이스나 저장소를 편집해도 자동으로 업데이트되지 않아요. 객체 파일을 재배포하고 업데이트하려면 ALTER DBT PROJECT ... DEPLOY 또는 snow dbt deploy를 사용하세요.

프로덕션 파이프라인을 만들려면 dbt 프로젝트 객체를 배포하고 태스크로 실행을 스케줄하는 것을 권장해요. 다음 예시는 SQL을 사용해요:

ALTER DBT PROJECT testdbt.public.my_dbt_project_object
  DEPLOY FROM 'snow://workspace/user$.public."all_my_dbt_projects"/versions/live';

Git 기반 워크플로를 쓰는 팀은 GitHub Actions 같은 CI/CD 파이프라인에서 Snowflake CLI를 사용해 직접 배포하는 것을 권장해요. 예를 들어:

⚠️ 의도적으로 dbt 프로젝트 객체를 다시 만들려는 게 아니라면 --force를 사용하지 마세요. snow dbt deploy의 --force는 CREATE OR REPLACE DBT PROJECT를 실행하며, 이는 실행 기록을 제거할 수 있어요.

snow dbt deploy my_dbt_project_object --source ./path/to/dbt/project

--source는 Snowflake CLI가 dbt 프로젝트 파일을 읽는 디렉터리를 지정해요. 로컬 경로(예: ./path/to/dbt/project)를 가리키면 Snowflake CLI는 디스크의 그 디렉터리에서 파일을 읽어요. GitHub Actions에서 이 디렉터리는 체크아웃된 코드 저장소이며 커밋된 프로젝트 파일을 포함해요.

dbt 프로젝트 객체가 이미 존재하면 ALTER DBT PROJECT ... DEPLOY와 snow dbt deploy 모두 그 live 버전을 단일 작업으로 교체해요. 전체 CI/CD 워크스루는 dbt Projects on Snowflake에서 CI/CD 통합 설정 튜토리얼을 참조하세요.

dbt 프로젝트 객체의 파일과 아티팩트

dbt 프로젝트 객체는 여러 레이어의 파일을 저장해요:

  • 프로젝트 소스 파일: live 버전에는 배포 중 복사된 dbt_project.yml, 모델 파일, 프로필 구성, 기타 파일이 들어 있어요.
  • 배포 시점 컴파일 아티팩트: AUTO_COMPILE 속성이 생성·배포 중 자동 의존성 설치와 컴파일을 제어해요. AUTO_COMPILE = TRUE면 Snowflake가 배포 중 dbt compile을 실행해요. 외부 접근 통합이 구성되면 Snowflake가 먼저 dbt deps를 실행한 다음 dbt compile을 실행해요. AUTO_COMPILE = FALSE로 설정하면 두 명령을 모두 건너뛰어요. target/manifest.json 같은 컴파일된 아티팩트는 Snowflake가 프로젝트 세부 정보를 표시할 수 있도록 live 버전에 기록돼요.
  • 실행 시점 target 및 log 아티팩트: dbt 명령이 live 버전의 target 및 log 경로를 업데이트할 수 있어요. 객체의 DEFAULT_WRITEBACK 설정이 기본적으로 이 동작을 제어하고, 개별 실행이 WRITEBACK으로 이를 재정의할 수 있어요.
  • 쿼리별 결과: Snowflake는 WRITEBACK 설정과 관계없이 각 실행에 대한 쿼리별 결과 아티팩트와 아카이브를 객체의 results 디렉터리에 저장해요.

자동 컴파일과 writeback은 다른 수명 주기 시점에 적용돼요. 자동 컴파일은 배포 중 실행돼요. 이 자동 컴파일은 쿼리별 결과 아티팩트를 객체의 results 디렉터리에 저장하지 않아요. 결과적으로 자동 컴파일은 시스템 함수가 최근 실행에서 dbt 아티팩트를 검색하는 데 사용할 실행을 만들지 않아요. Writeback은 배포된 프로젝트를 실행할 때 적용되며, 그 실행의 target 및 log 아티팩트가 live 버전을 업데이트할지 제어해요.

실행은 Slim CI with defer to production, 부분 파싱, 소스 신선도(source freshness), 실패한 실행 복구에 재사용 가능한 아티팩트를 생성해요. 워크플로에 따라 아티팩트는 쿼리별 결과에서 사용 가능하거나, writeback이 활성화되면 live 버전에 유지돼요. 동시 실행의 경우 겹치지 않는 별도의 target 및 log 디렉터리를 사용하거나 live writeback을 비활성화하세요. 자세한 내용은 Slim CI와 프로덕션 defer에 dbt 아티팩트 사용 문서를 참조하세요.

더 알아보기 (Learn more)