dbt 아티팩트(Artifacts)

dbt 아티팩트(Artifacts)

dbt는 실행(invocation)할 때마다 하나 이상의 아티팩트를 생성하고 저장해요. 이 중 JSON 파일들은 문서화·상태(state)·소스 신선도 시각화에 쓰이고, Semantic Layer 분석이나 테스트 커버리지 계산, 실행 시간 분석 등에도 활용할 수 있어요.

출처: 문서

본문

(dbt v1.12 이상 적용)

dbt는 매 실행마다 하나 이상의 아티팩트를 생성하고 저장해요. 그중 몇 가지는 JSON 파일(semantic_manifest.json, osi_document.json, manifest.json, catalog.json, run_results.json, sources.json)로, 다음과 같은 용도로 사용돼요:

  • 문서화(documentation)
  • 상태(state)
  • 소스 신선도 시각화

이 파일들은 다음과 같은 목적으로도 사용할 수 있어요:

  • Semantic Layer에 대한 인사이트 얻기
  • 프로젝트 레벨 테스트 커버리지 계산
  • 실행 타이밍의 세로(longitudinal) 분석
  • 테이블 구조의 과거 변경 이력 파악
  • 그 외에도 훨씬 더 많은 용도로 활용 가능

아티팩트는 언제 생성되나?

대부분의 dbt 명령어(및 해당 RPC 메서드)는 아티팩트를 생성해요:

  • semantic manifest: dbt 프로젝트가 파싱될 때마다 생성돼요

(dbt v1.12 이상 적용)

  • Apache Ossie 문서: dbt 프로젝트가 파싱될 때마다 생성돼요

  • manifest: 프로젝트를 읽고 이해하는 명령어가 생성해요

  • run results: DAG의 노드를 실행·컴파일·카탈로그화하는 명령어가 생성해요

  • catalog: docs generate가 생성해요

(dbt v2.0 이상 적용)

  • sources: 소스가 포함될 때 dbt freshness가 생성하며, 하위 호환성을 위해 유지돼요
  • freshness: dbt freshness가 생성하며, freshness가 설정된 소스와 모델을 모두 다루고 각 항목에 resource_type 필드로 구분돼요

dbt CLI에서 명령어를 실행할 때는 모든 아티팩트가 기본적으로 다운로드돼요. 이 동작을 바꾸려면 How to skip artifacts from being downloaded 문서를 참고하세요.

아티팩트는 어디에서 생성되나?

기본적으로 아티팩트는 dbt 프로젝트의 /target 디렉터리에 기록돼요. 위치는 target-path 플래그로 설정할 수 있어요.

공통 메타데이터

dbt가 생성하는 모든 아티팩트에는 다음 속성이 있는 metadata 사전(dictionary)이 포함돼요:

  • dbt_version: 이 아티팩트를 생성한 dbt의 버전. 릴리스 버전 관리에 대한 자세한 내용은 Versioning을 참고하세요.
  • dbt_schema_version: 이 아티팩트 스키마의 URL. 아래 참고 사항을 확인하세요.
  • generated_at: 이 아티팩트가 생성된 UTC 타임스탬프.
  • adapter_type: 어댑터(데이터베이스), 예: postgres, spark 등.
  • env: DBT_ENV_CUSTOM_ENV_ 접두사가 붙은 환경 변수가 사전에 포함되며, 키는 접두사를 뺀 변수명이에요.
  • invocation_id: 이 dbt 실행(invocation)의 고유 식별자

manifest에서는 metadata에 다음도 포함될 수 있어요:

  • send_anonymous_usage_stats: 이 실행이 실행 중에 익명 사용 통계를 보냈는지 여부.
  • project_name: 루트 프로젝트의 dbt_project.yml에 정의된 name. (manifest v10 / dbt v1.6에서 추가)
  • project_id: project_name에서 해시된 프로젝트 식별자. 익명 사용 통계가 활성화된 경우 함께 전송돼요.
  • user_id: 기본적으로 ~/dbt/.user.yml에 저장되는 사용자 식별자. 익명 사용 통계가 활성화된 경우 함께 전송돼요.

참고 사항:

  • dbt 아티팩트의 구조는 schemas.getdbt.com에 호스팅된 JSON 스키마로 정형화돼요.
  • 아티팩트 버전은 dbt의 어떤 마이너 버전(v1.x.0)에서도 바뀔 수 있어요. 각 아티팩트는 독립적으로 버전이 매겨져요.

더 알아보기 (Learn more)