[dbt 101] Day 5: 문서화의 자동화, dbt Docs & Governance

“이 테이블의 amount 컬럼은 부가세 포함인가요, 별도인가요?” “이 user_id는 탈퇴한 회원도 포함하나요?”

데이터 팀이 가장 많이 듣는 질문이자, 가장 답변하기 귀찮아하는 질문들이다. 보통 위키(Wiki)나 엑셀에 데이터 사전을 정리하지만, 코드가 바뀌는 속도를 문서가 따라가지 못해 결국 ‘거짓말하는 문서’가 되고 만다.

dbt 시리즈의 마지막인 오늘은, “코드가 곧 문서”가 되는 dbt의 문서화(Documentation) 기능과 이를 통한 데이터 거버넌스(Governance) 구축에 대해 다룬다.

1. Descriptions as Code

dbt에서 문서는 별도의 워드 파일이 아니다. 우리는 모델을 정의했던 schema.yml 파일에 설명(Description)을 달아두기만 하면 된다.

version: 2

models:
  - name: stg_orders
    description: "쇼핑몰의 주문 내역을 담고 있는 Staging 테이블"
    columns:
      - name: status
        description: "주문 상태. (placed, shipped, completed, return_pending)"
      - name: amount
        description: "주문 총액. " # 긴 설명은 참조 가능

이렇게 코드 바로 옆에 설명을 적어두면, 개발할 때 자연스럽게 문서를 업데이트하게 된다. 주석(Comment)과 달리 이 설명들은 구조화된 메타데이터로 관리된다.

2. 아름다운 웹 문서 자동 생성

이제 마법을 부릴 차례다. 터미널에 단 두 줄의 명령어를 입력해보자.

dbt docs generate
dbt docs serve

dbt는 프로젝트의 모든 정보를 읽어 정적 웹사이트(Static Website)를 생성하고, 로컬 서버를 띄운다. 브라우저에서 열린 문서는 놀라울 정도로 강력하다.

dbt Docs가 제공하는 핵심 정보

• 테이블 스키마: 컬럼명, 데이터 타입, 우리가 적은 설명(Description).
• 소스 코드: 해당 테이블을 만드는 SQL 원본.
• 의존성: 이 테이블이 참조하는 상위 모델과, 이 테이블을 참조하는 하위 모델.

3. 살아있는 Lineage Graph

dbt Docs의 백미는 우측 하단에 있는 Lineage Graph 버튼이다.

Day 2에서 다뤘던 ref() 함수들이 시각화되어, 데이터가 소스(Source)에서부터 최종 마트(Mart)까지 어떻게 흘러가는지 한눈에 보여준다.

• Impact Analysis (영향도 분석): “Source 테이블의 컬럼을 수정하면 누가 영향을 받지?”를 알기 위해 그래프를 따라가기만 하면 된다.
• Onboarding: 신규 입사자에게 복잡한 아키텍처를 설명할 때 이 그래프 하나면 충분하다.

4. 배포 및 공유 (Governance)

로컬에서만 문서를 보면 의미가 없다. dbt docs generate 명령을 실행하면 target/ 폴더에 index.html, catalog.json, manifest.json 파일이 생성된다.

이 파일들을 AWS S3나 Google Cloud Storage의 정적 웹 호스팅 기능을 이용해 업로드하면, 전사 구성원이 볼 수 있는 “사내 공식 데이터 딕셔너리”가 완성된다. Airflow 파이프라인의 마지막 단계에 dbt docs generate && aws s3 cp ... 명령을 추가하면, 문서는 매일 자동으로 최신화된다.