dbt 프로젝트 객체 보기 및 관리

이 항목은 기존 dbt 프로젝트 객체의 구조와 메타데이터를 탐색하는 방법을 다뤄요. 프로젝트의 DAG 보기, 모델과 소스 세부 정보 검사, dbt 프로젝트 객체 실행이 포함돼요.

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

출처: Snowflake 문서

본문

dbt 프로젝트 객체 세부 정보 페이지 탐색

Snowsight의 dbt 프로젝트 객체 세부 정보 페이지는 배포된 dbt 프로젝트 객체를 탐색하고 관리하는 주요 장소예요. 항상 현재 배포된 프로젝트 버전을 반영하므로 유지 관리할 생성된 사이트가 없어요. 이 페이지에서 다음에 접근할 수 있어요:

검색과 깊이 컨트롤이 있는 완전한 대화형 프로젝트 DAG.
컴파일된 SQL과 구성을 포함한 모델, 소스, 테스트, 스냅샷, 매크로 세부 정보.
Snowflake Horizon Catalog 기반 컬럼 수준 혈통.
overview 문서 블록을 정의한 프로젝트용 Markdown 렌더링 프로젝트 개요. 자세한 내용은 프로젝트 개요 유지 관리 문서를 참조하세요.
배포된 dbt 프로젝트 객체의 일회성 및 부분 DAG 실행.
스케줄 보기와 생성을 포함한 스케줄 관리.
각 개별 실행의 로그, 추적, 다운로드 가능한 빌드 아티팩트가 있는 실행 기록.

배포된 dbt 프로젝트 객체와 그 아티팩트 파일은 Snowflake Horizon Catalog의 일부예요. 즉, 문서 생성, 실패 디버깅, 파이프라인에 대한 질문 응답 시 CoCo에 직접 쿼리하거나 검사하도록 요청할 수 있어요.

Snowsight에서 프로젝트 세부 정보 페이지를 다음 방식으로 열 수 있어요:

dbt Projects on Snowflake 홈 페이지: 탐색 메뉴에서 Transformations » dbt Projects를 선택한 다음 목록에서 배포된 dbt 프로젝트 객체를 선택해요.
Horizon Catalog Explorer: 탐색 메뉴에서 Catalog » Explorer » 데이터베이스 » 스키마 » dbt Projects를 선택한 다음 프로젝트를 선택해요.
워크스페이스 편집기: 프로젝트를 연 상태에서 Connect » View project를 선택해요. 자세한 내용은 dbt Projects on Snowflake용 워크스페이스 문서를 참조하세요.

프로젝트 DAG를 탐색해 모델 혈통과 의존성 보기

방향성 비순환 그래프(Directed Acyclic Graph, DAG)는 dbt 모델이 서로 어떻게 의존하는지 보여주며 데이터 혈통을 시각화해 다음을 할 수 있게 해요:

모델이 어디에 빌드되는지(데이터베이스.스키마), 어떻게 구체화되는지, 어떤 업스트림·다운스트림 의존성이 있는지 확인해요.
더 나은 성능과 확장성을 위해 비효율적인 모델 설계를 발견하고 개선해요.

Snowsight에서 프로젝트 DAG를 탐색하려면 Databases » 데이터베이스 » 스키마 » dbt Projects로 이동해 프로젝트를 선택해요. 프로젝트 세부 정보 페이지는 모델과 그 관계의 Graph, 프로젝트의 Description, dbt Project 정의, Privileges를 표시해요.

Graph에서 모델 노드를 클릭하면 DAG에서 직접 모델·소스·테스트 세부 정보(컴파일된 SQL과 구성 포함)를 검사할 수 있어요.

DAG 노드 범례

다음 표는 DAG의 각 노드 유형을 설명해요:

노드 유형	설명
Model	`models/` 디렉터리의 SQL 또는 Python 파일로, 테이블이나 뷰를 정의해요. 가장 흔한 노드 유형이에요.
Source	YAML 파일의 `sources:` 블록에 선언된 외부 테이블 또는 뷰. 소스는 모델의 입력이지 dbt가 빌드하는 것이 아니에요.
Seed	`seeds/` 디렉터리의 CSV 파일로, dbt가 테이블로 로드해요.
Test	프로젝트에 정의된 데이터 품질 검사(단일 또는 제네릭). 테스트 노드는 DAG에서 검증하는 모델에 연결돼요.
Snapshot	시간 경과에 따라 천천히 변하는 차원 데이터를 캡처하는 dbt 스냅샷. `snapshots/` 디렉터리에 정의돼요.

DAG 검색

DAG의 검색 바를 사용해 이름으로 모델을 찾아요. 모델을 선택하면 그 모델이 그래프의 초점(focal point)으로 고정돼요. 앵커 노드를 바꾸려면 검색 바를 사용해 다른 모델을 검색해요.

DAG 깊이 제어

업스트림·다운스트림 깊이 컨트롤을 사용해 앵커 노드 기준으로 그래프의 몇 레벨이 보일지 변경해요. 모델을 처음 앵커하면 DAG는 기본적으로 업스트림 2레벨, 다운스트림 2레벨을 보여줘요. 다른 모델을 앵커해도 깊이 설정은 유지돼요.

DAG는 한 번에 최대 300개의 모델을 표시해요. 프로젝트에 모델이 더 많다면 검색과 깊이 컨트롤을 사용해 필요한 그래프 부분으로 이동해요.

DAG에서 모델 세부 정보 검사

DAG에서 모델 노드를 선택하면 사이드 패널이 열리며 다음을 보여줘요:

모델의 유형, 파일 경로, 데이터베이스의 target 객체 링크.
행 수와 컬럼 수, 그리고 컬럼 이름 목록.
모델 설명(프로젝트에 정의된 경우).
업스트림·다운스트림 의존성을 나열하고 그 사이를 탐색할 수 있는 링크가 있는 모델 혈통.
모델의 소스 및 컴파일된 SQL.

프로젝트 세부 정보 페이지의 Graph 탭에서 사이드 패널의 View in Details를 선택해 객체 세부 정보 페이지에서 완전한 모델 세부 정보를 열어요. 모델 세부 정보 보기에서 Show in Graph를 선택하면 그 모델을 초점으로 앵커한 상태로 Graph 탭으로 돌아와요.

💡 쿼리 기록(query history) DAG와 워크스페이스 DAG는 이 페이지에서 설명하는 것과 같은 검색, 깊이 컨트롤, 컬럼 수준 혈통을 공유하며, 추가로 manifest.json과 run_results.json의 런타임 데이터(시작 시간, 종료 시간, 지속 시간)를 각 모델의 사이드 패널에 주입해요. 자세한 내용은 dbt Projects on Snowflake 모니터링 및 dbt Projects on Snowflake용 워크스페이스 문서를 참조하세요.

컬럼 수준 혈통 보기

DAG의 각 모델 노드는 Snowflake Horizon Catalog 기반 컬럼 수준 혈통을 지원해요. 아무 모델 노드에서 Show columns를 선택해 컬럼 목록을 펼쳐요. 컬럼을 선택하면 DAG에서 그 컬럼을 사용하는 모든 업스트림·다운스트림 모델이 강조 표시되어 데이터가 파이프라인을 통해 흐르는 방식을 추적할 수 있어요.

📌 컬럼 수준 혈통은 프로젝트가 최소 한 번 실행된 후에만 사용할 수 있어요. 자세한 내용은 컬럼 수준 혈통 제한 사항 문서를 참조하세요.

DAG에서 모델 실행

모델 노드의 … 메뉴를 선택해 DAG에서 직접 dbt 프로젝트 객체의 하위 집합을 실행할 수 있어요. 다음 실행 옵션을 사용할 수 있어요:

메뉴 옵션	실행 대상	해당 `--select` 플래그
Execute model	선택한 모델만	`--select model_name`
Execute model+	모델과 모든 다운스트림 종속 항목	`--select model_name+`
Execute +model	모델과 모든 업스트림 상위 항목	`--select +model_name`
Execute +model+	모델, 상위 항목, 하위 항목	`--select +model_name+`

옵션을 선택하면 Additional flags 필드에 해당 --select 값이 미리 채워진 Execute dbt project 대화 상자가 열려요. 대화 상자에서 다음을 할 수 있어요:

Run, Test, Build 같은 작업을 선택해요.
프로필 target(예: dev 또는 prod)을 선택해요.
선택 항목을 다듬고 싶다면 실행 전에 플래그를 편집해요.

SQL과 Snowflake CLI에서도 + 그래프 연산자와 함께 같은 --select 구문을 사용할 수 있어요:

EXECUTE DBT PROJECT my_dbt_project ARGS = 'build --select +stg_customers+ --target dev';

지원되는 dbt 명령과 플래그에 대한 자세한 내용은 지원되는 dbt 명령과 플래그 문서를 참조하세요.

dbt 프로젝트 객체 속성 보기

Snowflake가 dbt 프로젝트 객체에 대해 저장하는 메타데이터를 보면 객체의 이름, 소유자, 가변 live 버전의 파일이 Snowflake 내부 snow://dbt/... 스테이지 어디에 저장되는지 알 수 있어요.

특정 dbt 프로젝트 객체의 속성(이름, 소유자, comment 등)을 보려면 다음 예시처럼 DESCRIBE DBT PROJECT 명령을 사용하세요:

DESCRIBE DBT PROJECT my_dbt_project;

출력은 객체의 이름, 소유자, comment, live 버전 메타데이터, 외부 접근 통합을 보여줘요. 자세한 내용은 DESCRIBE DBT PROJECT 문서를 참조하세요.

모든 dbt 프로젝트 보기

접근할 수 있는 모든 dbt 프로젝트 객체와 주요 메타데이터를 보려면 SHOW DBT PROJECTS를 사용하세요.

SHOW DBT PROJECTS IN DATABASE mydb;

출력은 각 객체의 데이터베이스, 스키마, 소유자, comment, 생성·마지막 업데이트 시각, live 버전 메타데이터, 기본 환경, 외부 접근 통합을 보여줘요. 자세한 내용은 SHOW DBT PROJECTS 문서를 참조하세요.

또는 snow dbt list 명령을 사용하세요. 자세한 내용은 모든 사용 가능한 dbt 프로젝트 객체 나열 문서를 참조하세요.

dbt 프로젝트 문서와 아티팩트 접근

클래식한 dbt docs를 생성·호스팅하는 대신, Snowsight의 dbt 프로젝트 객체 세부 정보 페이지를 기본 문서 경험으로 사용할 것을 권장해요. dbt docs가 제공하는 모든 것과 그 이상을 제공해요. 이 페이지에서 할 수 있는 모든 것에 대해서는 dbt 프로젝트 객체 세부 정보 페이지 탐색 문서를 참조하세요.

여전히 정적 문서 사이트가 필요하다면 다음 옵션 중 하나를 사용하세요.

옵션 1: 배포된 dbt 프로젝트 객체에서 아티팩트 다운로드

EXECUTE DBT PROJECT 또는 Snowsight에서 docs generate 작업을 선택해 배포된 dbt 프로젝트 객체에서 dbt docs generate --static을 실행해요. WRITEBACK 설정은 실행이 생성한 target 및 log 아티팩트를 live 버전에 기록할지 제어해요. 다음 예시는 정적 사이트를 생성하고 live 버전에 기록해요:

EXECUTE DBT PROJECT my_db.my_schema.my_dbt_project
  ARGS = 'docs generate --static'
  WRITEBACK = TRUE;

실행이 완료된 후 생성된 아티팩트를 다음 방식으로 다운로드할 수 있어요:

live 버전에 기록된 아티팩트를 다운로드하려면 Databases » 데이터베이스 » 스키마 » dbt Projects » 프로젝트에서 dbt 프로젝트 객체 세부 정보 페이지를 열고 프로젝트 페이지를 사용해 live 버전에서 아티팩트를 다운로드해요.
해당 개별 실행의 아티팩트를 다운로드하려면 Run History 또는 Query History » Query Details에서 실행을 연 다음 dbt Output 아래의 Download Build Artifacts를 선택해요. Snowflake는 WRITEBACK 설정과 관계없이 이 쿼리별 결과 아티팩트와 그 아카이브를 저장해요.
프로그래밍 방식으로 쿼리별 아티팩트를 다운로드하려면 SYSTEM$LOCATE_DBT_ARTIFACTS 함수로 파일을 찾은 다음 GET 또는 COPY FILES로 가져와요.

전체 단계와 예시는 프로그래밍 방식으로 dbt 아티팩트와 로그 접근 문서를 참조하세요.

옵션 2: 워크스페이스에서 정적 문서 사이트 생성

클래식한 단일 파일 dbt docs 사이트를 원한다면 워크스페이스에서 dbt docs generate --static을 실행해요. 이는 문서 사이트를 번들한 독립형 target/static_index.html 파일을 생성하므로, 어떤 것도 호스팅하지 않고 볼 수 있어요. 워크스페이스에서 target/static_index.html을 로컬 머신으로 다운로드한 다음 브라우저에서 열어요.

📌 dbt Projects on Snowflake는 dbt docs serve를 지원하지 않아요. 대화형 경험에는 Snowsight의 프로젝트 세부 정보 페이지를 사용하거나, dbt docs generate --static으로 target/static_index.html을 생성하세요.

dbt 프로젝트 객체 보기 및 관리