dbt docs 명령어

dbt docs 명령어

dbt v2부터는 dbt Docs v2가 프로젝트 문서를 생성·조회하는 권장 방식이에요. dbt docs generate로 문서 사이트를 만들고 dbt docs serve로 로컬에서 미리 볼 수 있어요. v2는 Parquet 아티팩트를 만들어 정적 파일 호스트에 간단히 배포할 수 있어요.

출처: 문서

본문

(dbt v2.0 이상 적용) dbt v2에서는 dbt Docs v2가 프로젝트 문서를 생성·조회하는 권장 방식이에요. dbt docs generate로 문서 사이트를 만들고 dbt docs serve로 로컬에서 미리 볼 수 있어요. 문서 사이트를 만들지 않고 dbt platform의 Catalog용 카탈로그 메타데이터(catalog.json)만 채우려면 --write-catalog 플래그를 사용하세요.

dbt Docs v2

브라우저에 정적 manifest.json을 로드하는 대신, v2는 프로젝트를 컴파일·빌드할 때 Parquet 아티팩트를 생성해요. dbt docs generate는 순수 정적 파일(단일 페이지 앱 + 그 아티팩트들)로 이루어진 문서 사이트를 내보내며, 어떤 파일 호스트든 서빙할 수 있어요. 브라우저는 DuckDB-WASM(WebAssembly)을 사용해 Parquet을 직접 읽으므로, 문서를 보기 위해 상태를 유지하는 서버를 실행할 필요가 없어요. 이 덕분에 대형 프로젝트에서도 빠른 경험을 유지할 수 있어요.

사이트 생성

dbt docs generate는 프로젝트를 컴파일하고, 인덱스를 작성하며, 문서 사이트를 단일 명령어로 내보내요:

dbt docs generate

기본적으로 dbt는 사이트를 target/ 디렉터리(target/index.html, target/assets/, 그리고 target/index/ 아래의 인덱스)에 작성하며, dbt v1의 레이아웃과 일치해요. v1에서 했던 것처럼 target/의 index.html을 서빙할 수 있어서, dbt docs generate && mv target public 같은 기존 파이프라인도 그대로 동작해요.

--output-dir을 사용해 사이트의 자체 포함(self-contained) 복사본을 다른 디렉터리에 작성할 수 있어요:

dbt docs generate --output-dir site

이렇게 하면 S3, GitHub Pages, Netlify, GitLab Pages 또는 유사한 정적 파일 호스트에 호스팅할 수 있는 site/ 디렉터리(앱, 해시된 자산, 인덱스 복사본)가 생성돼요.

컴파일을 건너뛰고 디스크에 이미 있는 인덱스를 내보내려면 --no-compile을 사용하세요. 인덱스가 없으면 오류로 실패해요:

dbt docs generate --no-compile

컬럼 계통(lineage)과 풍부한 메타데이터

컬럼 레벨 계통과 풍부한 컬럼 메타데이터는 --static-analysis strict로 만든 인덱스가 필요해요. dbt docs generate는 기본적으로 표준 컴파일을 수행하므로, 컬럼 계통이 필요할 때는 먼저 strict 정적 분석으로 인덱스를 만든 다음 내보내세요:

dbt build --write-index --static-analysis strict
dbt docs generate --no-compile

컬럼 계통 없이 사이트를 생성하면 dbt Docs v2는 빈 데이터를 보여주는 대신 해당 기능을 숨겨요.

dbt Docs v2 서빙

로컬에서 사이트를 미리 보려면 다음을 실행하세요:

dbt docs serve

dbt docs serve는 사이트가 없거나 인덱스보다 오래됐으면 생성한 다음 정적 파일을 서빙해요. 서버는 기본적으로 포트 8580에서 시작하고 브라우저에서 열려요. --port로 포트를 바꿀 수 있어요:

dbt docs serve --port 8081

--target-path 플래그로 dbt가 아티팩트를 읽는 경로를 바꿀 수 있어요:

dbt docs serve --target-path ~/Developer/internal-analytics/target

생성된 사이트는 정적 파일 묶음이므로, 로컬 서빙 대신 클라우드 객체 스토리지나 정적 사이트 호스트 같은 어떤 정적 파일 호스트에도 호스팅할 수 있어요.

프로젝트 개요 페이지

dbt Docs v2는 dbt Docs v1과 마찬가지로 프로젝트의 __overview__ doc 블록을 랜딩 페이지로 렌더링해요. dbt는 docs-paths를 스캔해 {% docs %} 블록을 찾아 개요 콘텐츠를 발견하므로, models/overview.md의 블록은 기본적으로 발견돼요. docs/overview.md 파일은 프로젝트가 docs-paths: ["docs"]를 설정한 경우에만 발견돼요. 개요가 정의되어 있지 않으면 dbt는 기본 개요 콘텐츠를 렌더링해요.

--write-catalog 플래그

--write-catalog 플래그는 프로젝트의 모델이 생성한 테이블·뷰에 대한 메타데이터를 담은 catalog.json 아티팩트를 생성해요. 메타데이터 채우기에만 집중하며 문서 사이트는 만들지 않아요 — 문서 사이트는 dbt Docs v2를 사용하세요.

dbt platform에서 실행되는 dbt v2 작업의 경우 dbt가 build·run과 함께 write-catalog를 자동으로 실행하고 Catalog를 채우므로 수동으로 포함할 필요가 없어요. 다음 명령어에서 이 플래그를 사용할 수 있어요: dbt build dbt run dbt parse dbt compile

예시:

dbt build --write-catalog

플랫폼 동작

dbt v2에서 실행되는 dbt platform 작업에서는 카탈로그 메타데이터를 채우기 위해 바꿀 것이 없어요. dbt가 build·run과 함께 write-catalog를 자동 실행하므로 별도 명령어를 돌릴 필요가 없어요. dbt parse나 dbt compile을 실행할 때는 선택적으로 포함할 수 있어요.

작업에서 dbt Docs v2 정적 사이트를 만들려면 작업 단계로 dbt docs generate를 실행하거나 작업 설정에서 문서 생성을 활성화하세요. 그렇지 않으면 작업은 카탈로그 메타데이터만 채우고 정적 사이트는 생성하지 않아요.

로컬 사용

dbt v2를 로컬에서 실행할 때는 카탈로그를 생성하기 위해 명령어에 --write-catalog 플래그를 추가하세요:

dbt build --write-catalog

docs generate와의 차이점

--write-catalog 플래그는 메타데이터 채우기에만 집중하며, Catalog와 메타데이터 API를 구동하는 catalog.json 파일을 생성해요. 정적 문서 웹사이트 파일(index.html)은 생성하지 않아요.