2026년 4월 10일부터 Dataplex Universal Catalog가 Knowledge Catalog로 변경되었습니다. API, 클라이언트 라이브러리, CLI, IAM 이름은 변경되지 않습니다. 자세한 내용은 Google Cloud Knowledge Catalog 소개를 참조하세요.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

dbt Core에서 메타데이터 가져오기

데이터 엔지니어, 분석 엔지니어, 데이터 관리자에게 메타데이터를 중앙 집중화하는 것은 엔터프라이즈 데이터 탐색 및 거버넌스에 매우 중요합니다. 팀에서 데이터 변환에 dbt를 사용하면 유용한 운영, 시맨틱, 계보 메타데이터가 생성되지만 dbt 생태계 내에 사일로화된 상태로 유지되는 경우가 많습니다.

이 정보를 중앙 집중식 카탈로그에 통합하려면 dbt Core, dbt Cloud, MetricFlow의 메타데이터를 Knowledge Catalog (이전 명칭: Dataplex Universal Catalog)로 가져오면 됩니다.

dbt Core는 Oracle이나 PostgreSQL과 같은 스토리지 시스템이 아닌 변환 엔진으로 작동하므로 메타데이터를 가져오면 다양한 사용 사례가 가능합니다. Oracle 또는 PostgreSQL 메타데이터를 가져와 '어떤 원시 데이터가 있나요?'라는 질문에 답하고, dbt Core 메타데이터를 가져와 '데이터가 어떻게 변환되고, 안정적인지, 비즈니스에 어떤 의미가 있는지'라는 질문에 답합니다.

이 문서에서는 Google Cloud CLI 명령어와 dbt 아티팩트 파일을 사용하여 메타데이터를 가져오는 방법을 설명합니다.

dbt 통합을 실행하면 다음 메타데이터가 캡처됩니다.

기술 메타데이터: 주요 리소스(소스, 시드, 모델)와 기술 속성 (열 이름, 데이터 유형, 행 수)을 탐색하여 엔터프라이즈 데이터를 검색합니다.
비즈니스 및 시맨틱 메타데이터: dbt MetricFlow로 구동되는 비즈니스 정의 및 로직(예: 시맨틱 모델, 측정항목, 저장된 쿼리)을 탐색하여 BI 도구 및 AI 에이전트에 컨텍스트를 제공합니다.
운영 및 데이터 품질 메타데이터: 타이밍, 성공 또는 실패 상태, 데이터 업데이트 빈도, 테스트 결과와 같은 실행 메타데이터를 탐색하여 파이프라인 상태를 모니터링하고 데이터 문제를 해결합니다.
계보 및 관계 메타데이터: 변환 그래프 (DAG)와 dbt 리소스 간 종속 항목, 물리적 변환 블록을 추적하고 연결하는 물리적 계보, 조인 키 및 동적 조인, 상위-하위 관계를 탐색하여 다운스트림 영향 분석 및 근본 원인 추적을 지원합니다.
사용 메타데이터: dbt 외부에서 데이터가 사용되는 방식을 매핑하는 노출에 캡처된 메타데이터를 탐색하여 다운스트림 애플리케이션이 변환된 데이터를 사용하는 방식과 관련된 문제를 해결합니다.

제한사항

dbt Core v1 (버전 1.11 및 1.12에 대해 검증됨), dbt Core v2, dbt Fusion을 지원합니다.
gcloud CLI 버전 586.0.0 이상에서는 dbt 및 BigQuery 통합을 지원합니다. CLI를 설치하거나 업데이트하려면 Google Cloud CLI 설치를 참고하세요.
dbt Cloud에 직접 연결되지 않습니다. dbt Cloud 작업에서 메타데이터를 가져오려면 먼저 작업의 아티팩트를 가져옵니다. dbt Cloud 실행에서 메타데이터 가져오기를 참고하세요.
매우 크거나 깊이 중첩된 스키마는 잘립니다. 단일 측면이 측면별 크기 한도를 초과할 수 없으므로 깊이 중첩된 스키마는 후행 필드가 손실될 수 있습니다.
--aspects-only는 메타데이터를 추가하고 새로고침할 수 있지만 삭제할 수는 없습니다. dbt 리소스를 삭제하려면 전체 실행이 필요합니다.
이 통합은 Data Lineage API 및 그래프의 BigQuery 리소스에 대한 dbt 계보 이벤트만 지원합니다. 외부 서드 파티 소스의 dbt 항목 (소스, 시드, 모델)은 데이터 계보에 포착되지 않습니다.
- Data Lineage API에서 모든 dbt 계보 이벤트를 수집하려면 OpenLineage dbt 통합을 사용하세요. 그런 다음 OpenLineage를 Knowledge Catalog와 통합하여 dbt에서 데이터 계보를 가져오고 시각화합니다.

시작하기 전에

dbt Core 및 MetricFlow에서 메타데이터를 가져오려면 다음 작업을 완료하세요.

필요한 역할 및 권한을 부여합니다.
Knowledge Catalog API를 사용 설정합니다.
dbt 기본 요건을 충족합니다.
대상 항목 그룹이 아직 없으면 만듭니다.
Cloud Storage 역할 이해

IAM 역할 및 권한

Knowledge Catalog 커넥터 작업을 만들고 관리하려면 Knowledge Catalog 및 Cloud Storage에 대한 권한을 부여하는 Identity and Access Management (IAM) 역할이 필요합니다.

dbt 커넥터를 구성하는 데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.

항목 그룹 및 항목 링크를 만들고 관리하려면 프로젝트에 대한 Dataplex 카탈로그 관리자(roles/dataplex.catalogAdmin), Dataplex 카탈로그 편집자(roles/dataplex.catalogEditor) 또는 Dataplex 항목 그룹 소유자(roles/dataplex.entryGroupOwner)가 필요합니다.
dbt gcloud 명령어를 실행하고 메타데이터 가져오기 작업을 만들려면 다음 역할을 부여하여 최소 권한 원칙을 따르세요.
- 프로젝트에 대한 Dataplex 메타데이터 작업 소유자(roles/dataplex.metadataJobOwner)
- 타겟 항목 그룹 또는 프로젝트에 대한 Dataplex 항목 그룹 가져오기 작업자(roles/dataplex.entryGroupImporter) 항목 링크도 가져오는 경우 프로젝트에 Dataplex 항목 그룹 소유자(roles/dataplex.entryGroupOwner) 권한을 부여하세요. dbt 모델이 쓰는 BigQuery 테이블이 포함된 각 프로젝트에 Dataplex 항목 소유자(roles/dataplex.entryOwner) 권한도 부여합니다. 맞춤 역할의 경우 항목 링크 권한은 dataplex.entryGroups.useReferenceEntryLink, dataplex.entryGroups.useSchemaJoinEntryLink, dataplex.entryLinks.reference입니다.
또는 프로젝트에 Dataplex 카탈로그 관리자(roles/dataplex.catalogAdmin) 역할과 Dataplex 메타데이터 작업 소유자(roles/dataplex.metadataJobOwner) 역할을 부여할 수 있습니다.
변환된 메타데이터를 출력 스테이징 버킷 (--storage-uri)에 업로드하려면 스테이징 버킷에 대한 스토리지 객체 생성자(roles/storage.objectCreator) 또는 스토리지 객체 관리자(roles/storage.objectAdmin)가 필요합니다.
입력 Cloud Storage 버킷에서 dbt 아티팩트를 읽으려면 (Cloud Storage를 사용하는 경우 --artifacts-path) 입력 아티팩트 버킷에 대한 스토리지 객체 뷰어(roles/storage.objectViewer) 또는 스토리지 객체 관리자(roles/storage.objectAdmin)가 필요합니다. 스토리지 객체 관리자 역할이 있는 경우 스토리지 객체 뷰어 역할은 필요하지 않습니다.
dbt 메타데이터를 보려면 프로젝트에 대한 Dataplex 카탈로그 뷰어(roles/dataplex.catalogViewer)가 필요합니다.
Cloud Logging에서 로그를 보려면 프로젝트에 대한 로그 뷰어(roles/logging.viewer)를 사용하세요.

프로젝트에서 IAM 액세스를 관리하는 데 필요한 권한이 있는 경우 다음 gcloud 명령어를 실행하여 사용자 계정에 이러한 역할을 부여할 수 있습니다.

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:USER_EMAIL" \
    --role="roles/dataplex.metadataJobOwner"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:USER_EMAIL" \
    --role="roles/dataplex.entryGroupOwner"

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="user:USER_EMAIL" \
    --role="roles/storage.objectCreator"

자동화된 CI/CD 파이프라인과 같이 서비스 계정을 사용하여 가져오기를 실행하는 경우 다음 gcloud 명령어를 실행하여 서비스 계정에 이러한 역할을 부여할 수 있습니다.

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/dataplex.metadataJobOwner"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/dataplex.entryGroupOwner"

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/storage.objectCreator"

또한 가져오기 작업이 스테이징된 메타데이터 파일을 읽을 수 있도록 출력 스테이징 Cloud Storage 버킷(--storage-uri)에 Knowledge Catalog 서비스 에이전트(service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com)에 스토리지 객체 뷰어(roles/storage.objectViewer) 역할을 부여해야 합니다.

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
    --role="roles/storage.objectViewer"

다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID입니다.
USER_EMAIL: 사용자 계정 이메일 주소
SERVICE_ACCOUNT_EMAIL: 서비스 계정 이메일 주소입니다.
STAGING_BUCKET: 출력 스테이징 Cloud Storage 버킷 (--storage-uri)의 이름입니다.
PROJECT_NUMBER: Google Cloud 프로젝트 번호입니다.

역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.

API 사용 설정

Knowledge Catalog API를 사용 설정합니다.

API 사용 설정하기

dbt 기본 요건

전체 dbt 메타데이터를 가져오려면 네 개의 dbt JSON 아티팩트 파일을 모두 생성하는 것이 좋습니다. manifest.json만 필요합니다. 다른 항목은 가져오기를 풍부하게 하고 변환은 이러한 항목이 없어도 정상적으로 저하됩니다.

manifest.json(필수): 핵심 프로젝트 구조 및 실행 그래프입니다. MetricFlow 시맨틱 모델, 측정항목, 저장된 쿼리도 포함합니다.
catalog.json: 열 이름 및 데이터 유형입니다. catalog.json가 없으면 스키마 측면이 유형이 지정되지 않은 열과 함께 가져옵니다.
run_results.json: 테스트 결과 및 실행 메타데이터입니다.
sources.json: 소스 최신성입니다.

dbt가 설치된 로컬 터미널, Cloud Shell 또는 자동화된 CI/CD 환경에서 dbt 프로젝트 루트 디렉터리로 이동하여 단일 프로필 및 타겟에 대해 다음 dbt 명령어를 순서대로 실행하여 전체 dbt 메타데이터 아티팩트 JSON 파일을 생성합니다.

dbt Core 2.x 및 dbt Fusion의 경우:
1. dbt source freshness
2. dbt build
3. dbt parse --write-catalog
  
  경고: dbt Core 2.x 또는 dbt Fusion에서 dbt docs generate를 사용하지 마세요. catalog.json를 작성하지 않으며 테스트 결과 없이 run_results.json를 덮어씁니다. dbt build --write-catalog는 카탈로그를 작성하지 않으므로 별도의 dbt parse --write-catalog 단계를 사용하세요.
dbt Core 1.x (여기서 dbt parse는 카탈로그를 작성하지 않음):
1. dbt source freshness
2. dbt build
3. dbt docs generate --no-compile
  
  경고: --no-compile이 없으면 dbt docs generate이 모든 노드에 대해 run_results.json을 success 상태로 덮어씁니다. 이전 dbt build의 테스트 결과가 손실되고 카탈로그에서 모든 데이터 품질 테스트가 통과로 보고됩니다.

Cloud Storage 역할 이해

dbt 메타데이터 가져오기에는 서로 다른 용도로 사용되며 혼동해서는 안 되는 두 가지 별도의 Cloud Storage 위치가 포함됩니다.

입력 (dbt 소스 아티팩트): 생성된 dbt JSON 파일이 있는 위치입니다. 이는 머신 또는 CI 러너의 로컬 디렉터리 경로(예: ./target/ 또는 .) 또는 입력 Cloud Storage 버킷 URI 접두사(예: gs://my-dbt-artifacts-bucket/target/)일 수 있습니다. --artifacts-path 플래그를 사용하여 이 경로를 제공합니다. gcloud 명령어는 작업 준비 중에 이러한 입력 파일을 읽습니다. Cloud Storage를 사용하는 경우 gcloud 명령어를 실행하는 호출자에게 읽기 액세스 권한 (roles/storage.objectViewer 또는 roles/storage.objectAdmin)이 필요합니다. Knowledge Catalog 서비스 에이전트에는 입력 아티팩트 버킷에 대한 액세스 권한이 필요하지 않습니다.
출력 (Knowledge Catalog 가져오기 스테이징 버킷): gcloud 명령어가 변환된 메타데이터 가져오기 파일 (dbt_metadata.jsonl)을 업로드하고 Knowledge Catalog 가져오기 작업이 수집 중에 읽어오는 Cloud Storage 버킷 URI 접두사 (예: gs://my-staging-bucket/dbt-imports/)입니다. --storage-uri 플래그를 사용하여 이 URI를 제공합니다. gcloud 명령어를 실행하는 호출자에게는 파일을 업로드할 쓰기 액세스 권한 (roles/storage.objectCreator 또는 roles/storage.objectAdmin)이 필요하고, Knowledge Catalog 서비스 에이전트에게는 파일을 가져올 읽기 액세스 권한 (roles/storage.objectViewer)이 필요합니다.

dbt Cloud 실행에서 메타데이터 가져오기

Knowledge Catalog는 dbt Cloud에 직접 연결되지 않습니다. dbt Cloud 작업은 dbt Core와 동일한 아티팩트 파일을 생성하므로 이러한 아티팩트 파일을 로컬 디렉터리 또는 입력 Cloud Storage 버킷으로 가져오고 gcloud 명령어를 실행하여 dbt Cloud에서 메타데이터를 가져올 수 있습니다.

아티팩트를 가져오기 전에 dbt Cloud 작업을 구성하여 전체 아티팩트 세트를 생성합니다. 그런 다음 다음 방법 중 하나를 사용하여 dbt Cloud 작업 실행에서 아티팩트 파일을 가져올 수 있습니다.

dbt Cloud 콘솔에서 아티팩트 다운로드: 일회성 가져오기 또는 초기 테스트를 위해 dbt Cloud 사용자 인터페이스의 작업 실행 세부정보 페이지에서 아티팩트 파일을 수동으로 다운로드합니다.
dbt 플랫폼 CLI를 사용하여 아티팩트 다운로드: 개발 중에 생성된 아티팩트를 로컬 프로젝트 디렉터리에 자동으로 저장하려면 로컬 터미널에서 dbt Cloud의 dbt 명령어를 실행하세요.
dbt 관리 API를 사용하여 아티팩트 다운로드: 자동화된 예약 파이프라인을 위해 HTTP를 통해 완료된 실행에서 아티팩트를 프로그래매틱 방식으로 검색합니다.

dbt Cloud 작업 설정

dbt Google Cloud 콘솔에서 전체 메타데이터 아티팩트를 생성하도록 작업 설정을 구성합니다.

실행 설정 섹션에서 소스 업데이트 실행을 선택합니다. dbt Cloud는 작업 명령 전에 dbt source freshness를 실행하여 sources.json를 생성합니다.
명령어 섹션에서 dbt build를 추가합니다.
출시 트랙을 기반으로 catalog.json를 생성하는 명령어를 추가합니다.
- dbt Core 2.x 및 dbt Fusion 출시 트랙의 경우: dbt parse --write-catalog를 작업 명령어로 추가합니다.
- dbt Core 1.x 출시 트랙의 경우: 실행 시 문서 생성 옵션을 선택하는 대신 dbt docs generate --no-compile을 작업 명령어로 추가합니다. 실행 시 문서 생성 체크박스는 --no-compile 없이 dbt docs generate를 실행하므로 dbt 사전 요구사항에 설명된 대로 dbt build의 테스트 결과를 덮어씁니다. 명령어 단계가 실패하면 작업도 실패하지만 체크박스 단계는 작업을 실패시키지 않습니다.

예를 들어 테스트가 실패하여 dbt build가 실패하면 dbt Cloud는 그 이후의 명령어를 건너뛰고 실행에 catalog.json이 없습니다. 항상 하나를 생성하려면 dbt build 앞에 카탈로그 명령어를 추가하세요. 그런 다음 카탈로그는 빌드 전의 테이블을 설명합니다.

자세한 내용은 dbt 문서의 작업 명령어 및 출시 트랙을 참고하세요.

dbt Google Cloud 콘솔에서 아티팩트 다운로드

dbtGoogle Cloud 콘솔에서 완료된 실행의 아티팩트를 수동으로 다운로드하려면 다음 단계를 따르세요.

dbt Google Cloud 콘솔에서 완료된 작업 실행을 엽니다.
아티팩트 탭으로 이동하여 생성된 아티팩트 파일을 확인합니다.
manifest.json, catalog.json, run_results.json, sources.json를 로컬 디렉터리에 다운로드합니다.
로컬 터미널 또는 Cloud Shell에서 dbt 연결 구성에 설명된 gcloud 가져오기 명령어를 실행하고 --artifacts-path을 다운로드한 파일이 포함된 디렉터리로 설정합니다.

자세한 내용은 dbt 문서의 실행 가시성을 참고하세요.

dbt 플랫폼 CLI를 사용하여 아티팩트 다운로드

dbt 플랫폼 CLI (이전 명칭: dbt Cloud CLI)는 로컬 터미널에서 dbt Cloud 플랫폼의 dbt 명령어를 실행하고 생성된 아티팩트를 로컬 dbt 프로젝트의 target/ 디렉터리에 자동으로 다운로드합니다.

로컬 터미널에서 dbt 프로젝트 루트 디렉터리로 이동하여 dbt 사전 요구사항에 나열된 세 가지 명령어를 실행합니다.
dbt 연결 구성에 설명된 gcloud 가져오기 명령어를 실행하고 --artifacts-path을 프로젝트 루트 또는 target/ 디렉터리로 설정합니다.

CLI는 개인 데이터 웨어하우스 사용자 인증 정보를 사용하여 개발 환경 내에서 실행되므로 생성된 메타데이터는 예약된 작업으로 빌드된 프로덕션 테이블이 아닌 개발 스키마를 반영합니다. 테스트 또는 개발 워크플로에는 CLI를 사용하고 예약된 프로덕션 가져오기에는 배포 작업을 사용하세요.

자세한 내용은 dbt 문서의 dbt 플랫폼 CLI 설치를 참고하세요.

dbt 관리 API를 사용하여 아티팩트 다운로드

dbt 관리 API를 사용하여 완료된 작업 실행에서 아티팩트를 프로그래매틱 방식으로 가져올 수 있습니다. List Run Artifacts 엔드포인트는 실행에서 생성된 파일 경로를 반환하고 Retrieve Run Artifact 엔드포인트는 다음 URL에서 특정 아티팩트 파일을 다운로드합니다.

https://ACCESS_URL/api/v2/accounts/ACCOUNT_ID/runs/RUN_ID/artifacts/FILE

ACCESS_URL은 dbt Cloud 계정을 호스팅하는 리전에 따라 다릅니다. dbt Cloud 서비스 토큰을 사용하여 요청을 인증합니다. 자세한 내용은 dbt 문서의 다음 페이지를 참고하세요.

로컬 터미널, Cloud Shell 또는 자동화된 워크플로 환경에서 manifest.json, catalog.json, run_results.json, sources.json를 로컬 디렉터리 또는 Cloud Storage 버킷에 다운로드한 다음 dbt 연결 구성에 설명된 gcloud 명령어를 해당 경로에 대해 실행합니다.

기본적으로 아티팩트 엔드포인트는 step 쿼리 매개변수를 지정하지 않는 한 실행의 마지막 단계에서 아티팩트를 반환합니다. dbt Cloud 작업 설정에 설명된 대로 작업을 구성하면 마지막 단계는 dbt parse --write-catalog 또는 dbt docs generate --no-compile이며, 이는 catalog.json만 작성하고 다른 세 아티팩트는 기본 단계에서 그대로 둡니다.

실행 ID 가져오기

특정 실행의 아티팩트를 다운로드하려면 실행 ID가 필요합니다. dbt Google Cloud 콘솔의 실행 URL에서 실행 ID를 복사하거나 터미널 또는 워크플로 스크립트에서 API를 쿼리하여 작업의 가장 최근 성공한 실행을 확인할 수 있습니다.

GET https://ACCESS_URL/api/v2/accounts/ACCOUNT_ID/runs/?job_definition_id=JOB_ID&status=10&order_by=-finished_at&limit=1

쿼리 매개변수에서 status=10는 Success 상태의 완료된 실행을 필터링합니다. 일정에 따라 이 엔드포인트를 폴링하여 가장 최근의 성공적인 실행을 식별하고, 아티팩트를 다운로드하고, gcloud 가져오기 명령어를 실행할 수 있습니다.

웹훅을 사용하여 가져오기 트리거

API를 폴링하는 대신 작업 실행이 완료될 때마다 자동 메타데이터 가져오기를 트리거하도록 dbt Cloud 웹훅을 구성할 수 있습니다. 웹훅은 사용자가 제공한 HTTP 엔드포인트로 페이로드를 전송합니다.

dbt Google Cloud 콘솔에서 계정 설정 > 웹훅으로 이동하여 웹훅 만들기 (또는 새 웹훅 만들기)를 클릭합니다. 웹훅 구독을 구성합니다.
- 이벤트: 실행 완료 (job.run.completed)를 선택합니다. 이는 실행이 완료되고 아티팩트를 다운로드할 수 있는 경우에만 트리거됩니다.
- 작업: 모니터링할 dbt Cloud 배포 작업을 선택합니다.
- 엔드포인트: 실행 중인 서비스 (예: Cloud Run 서비스 또는 Cloud Run 함수)의 HTTPS URL을 입력합니다.
dbt Cloud에 표시되는 웹훅 보안 토큰을 저장합니다. 서비스는 이 보안 비밀을 사용하여 요청 본문의 HMAC-SHA256 서명이 포함된 Authorization 헤더를 확인합니다.
서비스에서 JSON 페이로드에서 data.runId를 읽고, 앞에서 설명한 대로 관리 API를 사용하여 실행의 아티팩트를 다운로드하고, gcloud alpha dataplex dbt metadata-jobs create 명령어를 실행합니다.

웹훅 핸들러를 구현할 때는 다음 사항을 고려하세요.

dbt Cloud는 최대 10초 동안 응답을 기다립니다. 메타데이터 가져오기에 몇 분이 걸리므로 먼저 HTTP 응답을 반환하고 백그라운드에서 가져오기를 실행합니다 (예: Cloud Run 작업으로 또는 --async 플래그 사용).
job.run.completed는 실패한 실행에 대해서도 트리거되므로 테스트가 실패한 실행도 가져옵니다. job.run.errored는 실행 아티팩트가 제공되기 전에 트리거될 수 있으므로 구독하지 마세요.

웹훅 페이로드 및 서명 확인에 관한 자세한 내용은 dbt 문서의 작업용 웹훅을 참고하세요.

dbt 연결 구성

dbt 연결을 설정하려면 먼저 적절한 dbt 명령어를 실행하여 메타데이터 아티팩트를 생성해야 합니다. JSON 파일이 저장되고 액세스할 수 있게 되면 가져오기 프로세스에서 다음 작업을 실행합니다.

입력 아티팩트 읽기: dbt Core 및 MetricFlow에서 생성된 JSON 아티팩트를 입력 위치 (--artifacts-path에 지정된 로컬 디렉터리 또는 Cloud Storage URI)에서 읽습니다.
메타데이터 변환: 콘텐츠를 Knowledge Catalog 메타데이터 가져오기 형식 (dbt_metadata.jsonl)으로 변환합니다.
스테이징에 업로드: 변환된 메타데이터 가져오기 파일을 --storage-uri에 지정된 출력 스테이징 Cloud Storage 위치에 업로드합니다.
가져오기 작업 트리거: Knowledge Catalog 서비스 에이전트가 --storage-uri에서 스테이징된 메타데이터를 읽고 Knowledge Catalog 리소스에 수집하도록 지시하는 Knowledge Catalog 메타데이터 가져오기 작업을 트리거합니다.

콘솔

Google Cloud 콘솔에서 Knowledge Catalog 커넥터 페이지로 이동합니다.

커넥터로 이동
연결 추가를 클릭합니다.
커넥터 목록에서 dbt Core 및 MetricFlow 카드를 선택합니다.

참고: dbt Core 메타데이터 수집에는 수집 전에 클라이언트 측 dbt 아티팩트 JSON 파일 (manifest.json, catalog.json, run_results.json, sources.json)을 Knowledge Catalog 가져오기 형식으로 변환해야 하므로 이 카드를 선택하면 CLI 또는 API 안내로 이동합니다.
가져온 dbt 애셋을 보려면 검색 페이지로 이동하거나 대상 항목 그룹 페이지를 확인하세요.

gcloud

dbt 메타데이터 작업을 만들려면 다음 단계를 완료하세요.

dbt 메타데이터 아티팩트 파일이 로컬 또는 입력 Cloud Storage 버킷에 저장되어 있는지 확인합니다.
호출자와 Knowledge Catalog 서비스 에이전트 모두에 적절한 권한이 구성된 출력 스테이징 Cloud Storage 버킷이 있는지 확인합니다.
Cloud Shell, 로컬 터미널 또는 자동 워크플로 도구에서 gcloud 명령어를 실행합니다.
```
gcloud alpha dataplex dbt metadata-jobs create my-dbt-import \
    --project=my-project \
    --location=us-central1 \
    --artifacts-path=. \
    --entry-group=dbt-metadata-ingestion \
    --storage-uri=gs://my-bucket/dbt-imports/
```
필수 플래그
- --storage-uri=STORAGE_URI: 변환된 JSONL이 업로드되고 가져오기 작업이 수집 중에 읽어오는 (출력/스테이징) Cloud Storage URI 접두사 (gs://bucket/path/)입니다. 호출자에게는 쓰기 액세스 권한 (roles/storage.objectCreator 또는 roles/storage.objectAdmin)이 있어야 하고 Knowledge Catalog 서비스 에이전트에게는 읽기 액세스 권한 (roles/storage.objectViewer)이 있어야 합니다.
선택적 플래그
- --artifacts-path=ARTIFACTS_PATH: (입력) 소스 dbt 아티팩트의 경로입니다. 로컬 디렉터리 경로 (예: . 또는 ./target) 또는 Cloud Storage URI 접두사 (예: gs://my-bucket/dbt-artifacts/)일 수 있습니다. dbt 프로젝트 루트(target/ 하위 디렉터리가 자동으로 감지됨) 또는 manifest.json가 포함된 디렉터리를 직접 가리킬 수 있습니다. 기본값은 .입니다. Cloud Storage URI가 제공된 경우 호출자에게 입력 버킷에 대한 읽기 액세스 권한(roles/storage.objectViewer 또는 roles/storage.objectAdmin)이 있어야 합니다.
- --async: 진행 중인 작업이 완료될 때까지 기다리지 않고 즉시 반환합니다.
- --entry-group=ENTRY_GROUP: dbt 항목을 수신하는 항목 그룹의 짧은 ID입니다. 프로젝트 및 위치에 이미 있어야 합니다 (기본값은 dbt-metadata-ingestion).
- --aspects-only: 이 dbt 실행에서 관찰한 메타데이터만 업데이트하고 나머지 항목 그룹은 그대로 둡니다. 항목이 생성, 삭제 또는 재상위 지정되지 않고 항목 링크가 내보내지지 않으며 이 실행에서 dbt 아티팩트가 누락된 측면은 이전 실행에서 부여된 값을 유지합니다. 일상적이고 반복적인 수집에 사용합니다. 수집 다시 실행을 참고하세요.
- --include-entry-links: dbt 관계의 항목 링크를 내보냅니다. 이 기능은 기본적으로 사용 설정되어 있습니다. 사용 중지하려면 --no-include-entry-links을 사용합니다. 이 명령어는 다음 항목 링크 유형을 내보냅니다.
  - reference: 한 리소스가 다른 리소스에 종속되거나, 다른 리소스를 설명하거나, 다른 리소스를 사용합니다. 여기에는 노드 간의 dbt 종속 항목, 테스트 및 테스트 대상 리소스, 시맨틱 모델 또는 측정항목 및 기반 리소스, 노드 및 호출하는 프로젝트 매크로, 노드 및 구체화되는 BigQuery 테이블이 포함됩니다.
  - schema-join: dbt relationships 테스트로 선언된 조인 가능한 열입니다.
- --skip-bigquery-link: reference 링크 (dbt 노드 → 실제 BigQuery 테이블)를 건너뜁니다. 기본적으로 BigQuery 데이터 세트가 가져오기 위치 (--location)에 있는 구체화된 각 dbt 노드 (모델, 시드, 스냅샷)에 대해 reference 링크가 생성됩니다. dbt 소스는 BigQuery 테이블에 대한 reference 링크를 수신하지 않습니다. 항목 링크는 동일한 리전의 @bigquery 항목만 참조할 수 있으므로 다른 리전의 데이터 세트는 자동으로 건너뜁니다. 각 데이터 세트의 리전을 확인하기 위해 명령어는 BigQuery API를 호출하므로 호출자에게 해당 데이터 세트에 대한 bigquery.datasets.get 권한이 필요합니다. 이 권한이 없으면 명령어가 다른 리전의 데이터 세트를 건너뛸 수 없으며 해당 데이터 세트에 대한 링크가 해결되지 않습니다. BigQuery 테이블이 Knowledge Catalog에 카탈로그화되지 않은 경우 --skip-bigquery-link를 사용합니다.
- --validate-only: JSON을 빌드하고 업로드하고 메타데이터 작업을 검증하지만 실제로는 수집하지 않습니다.
Created 상태가 표시되는지 확인합니다.

REST

REST API를 사용하여 dbt 메타데이터를 가져오려면 다음 단계를 따르세요.

dbt 아티팩트를 생성하고 이를 Knowledge Catalog JSON 가져오기 파일 (dbt_metadata.jsonl)로 변환합니다.
변환된 파일을 Cloud Storage 스테이징 버킷 (gs://BUCKET_NAME/PATH/)에 업로드합니다.

projects.locations.metadataJobs.create 메서드를 호출합니다.

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/metadataJobs?metadataJobId=JOB_ID \
    -d '{
      "type": "IMPORT",
      "importSpec": {
        "sourceStorageUri": "gs://BUCKET_NAME/PATH/",
        "entrySyncMode": "FULL",
        "aspectSyncMode": "INCREMENTAL",
        "scope": {
          "entryGroups": [
            "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP"
          ],
          "entryTypes": [
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-project",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-model",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-source",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-seed",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-snapshot",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-group",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-exposure",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-metric",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-macro",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-semantic-model",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-saved-query",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-test"
          ],
          "aspectTypes": [
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-node",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-project",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-model",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-source",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-seed",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-snapshot",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-group",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-exposure",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-metric",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-macro",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-semantic-model",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-saved-query",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-data-quality",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-model-contracts"
          ]
        }
      }
    }'

다음을 바꿉니다.

PROJECT_ID: 항목 그룹이 있는 Google Cloud 프로젝트 ID입니다.
LOCATION: 항목 그룹의 리전 (예: us-central1)
JOB_ID: 메타데이터 작업의 고유 식별자입니다.
BUCKET_NAME/PATH: dbt_metadata.jsonl가 업로드된 Cloud Storage URI 접두사입니다.
ENTRY_GROUP: 대상 항목 그룹의 짧은 ID입니다.

가져오기 작업의 상태를 추적하려면 projects.locations.metadataJobs.get 메서드를 사용합니다.

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/metadataJobs/JOB_ID

작업을 만들면 Knowledge Catalog에서 구성에 따라 첫 번째 실행을 예약하거나 수동으로 시작할 수 있습니다.

수집 재실행

첫 번째 가져오기 후 대부분의 실행에서는 이미 있는 리소스의 메타데이터만 새로고침하면 됩니다. 이러한 실행에는 --aspects-only을 사용합니다. dbt 실행에서 관찰한 항목만 업데이트하고 항목 그룹의 다른 모든 항목은 그대로 두므로 어떤 일정으로든 둘 이상의 작업에서 반복적으로 실행해도 안전합니다.

항목 집합이 변경되면 전체 수집 실행 (--aspects-only 생략)

항목 그룹으로의 첫 번째 인그레이션입니다.
dbt 리소스가 추가, 이름 변경 또는 삭제됩니다.
항목의 표시 이름, 설명 또는 라벨이 변경됩니다.
항목 계층 구조가 변경됩니다.
ref(), source(), 테스트 또는 매크로 호출이 추가되거나 삭제되는 등 dbt 종속 항목이 변경됩니다. --aspects-only 실행은 항목 링크를 만들거나 업데이트하지 않습니다.
--include-entry-links 또는 --skip-bigquery-link을 변경합니다.

전체 실행은 디스크에 있는 아티팩트에서 모든 항목의 필수 측면을 다시 작성하므로 파이프라인에서 생성할 수 있는 가장 완전한 아티팩트 세트에서 운영하세요.

정기적으로 새로고침하려면 --aspects-only 실행:

파이프라인이 실행되는 dbt 명령어(dbt build, dbt test, dbt source freshness 또는 --select로 좁혀진 재빌드) 이후
열이 추가, 삭제, 다시 입력 또는 다시 설명됩니다.
모델 SQL이 변경되었고 실행에서 catalog.json도 작성했습니다.
새 테스트 결과 또는 소스 업데이트 빈도

--aspects-only는 메타데이터를 추가하고 새로고침할 수 있지만 삭제할 수는 없습니다.

dbt 메타데이터 검색 및 보기

콘솔

Google Cloud 콘솔에서 Knowledge Catalog 검색 페이지로 이동합니다.

검색 페이지로 이동
필터 패널에서 dbt 애셋을 필터링합니다.
- 시스템 섹션에서 가져온 컨텍스트를 선택합니다.
- 표시되는 관리 커넥터 하위 섹션에서 dbt를 선택합니다.
검색창에 키워드 또는 자연어 검색을 사용하여 검색어를 입력합니다. 예를 들어 키워드 검색을 사용하여 모든 dbt 애셋을 보려면 system=DBT 또는 system=DBT AND type=dbt-model를 입력합니다.
검색 결과에서 dbt 애셋을 클릭하여 항목 세부정보 페이지를 열고 스키마, 계보, 기술적 측면을 확인합니다.

gcloud

프로젝트 전체에서 dbt 항목을 검색하려면 gcloud dataplex entries search 명령어를 사용합니다.
```
gcloud dataplex entries search 'system=DBT' \
    --project=PROJECT_ID
```
특정 dbt 항목 유형 (예: 모델 또는 소스)별로 필터링하려면 다음 단계를 따르세요.
```
gcloud dataplex entries search 'system=DBT AND type=dbt-model' \
    --project=PROJECT_ID
```
특정 dbt 항목의 전체 세부정보와 측면을 보려면 gcloud dataplex entries lookup 명령어를 사용합니다.
```
gcloud dataplex entries lookup ENTRY_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --entry-group=ENTRY_GROUP \
    --view=FULL
```
다음을 바꿉니다.
- PROJECT_ID: Google Cloud 프로젝트 ID입니다.
- LOCATION: 항목 그룹의 위치 (예: us-central1)
- ENTRY_GROUP: 대상 항목 그룹의 짧은 ID (예: dbt-metadata-ingestion)
- ENTRY_ID: dbt 항목의 짧은 ID 또는 상대 리소스 이름입니다.

REST

dbt 항목을 검색하려면 projects.locations:searchEntries 메서드를 호출합니다.

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global:searchEntries \
    -d '{
      "query": "system=DBT"
    }'

특정 dbt 리소스 유형별로 필터링하려면 다음 단계를 따르세요.

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global:searchEntries \
    -d '{
      "query": "system=DBT AND type=dbt-model"
    }'

특정 항목의 전체 메타데이터 세부정보와 측면을 가져오려면 projects.locations.entryGroups.entries.get 메서드를 호출합니다.

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP/entries/ENTRY_ID?view=FULL

특정 dbt 리소스의 LLM 컨텍스트를 가져오려면 projects.locations:lookupContext API를 사용하세요.

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupContext \
    -d '{
      "resources": [
        "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP/entries/ENTRY_ID"
      ]
    }'

다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID입니다.
LOCATION: 항목 그룹의 위치 (예: us-central1)
ENTRY_GROUP: 대상 항목 그룹의 짧은 ID (예: dbt-metadata-ingestion)
ENTRY_ID: dbt 항목의 짧은 ID 또는 상대 리소스 이름입니다.

dbt 항목의 항목 링크를 나열하려면 projects.locations:lookupEntryLinks 메서드를 호출합니다. 예를 들어 dbt 모델이 구체화되는 BigQuery 테이블을 가져오려면 다음을 실행합니다.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupEntryLinks?entry=ENTRY_NAME&entryMode=SOURCE&entryLinkTypes=projects/dataplex-types/locations/global/entryLinkTypes/reference"

ENTRY_NAME은 dbt 항목의 전체 리소스 이름입니다. 결과는 페이지로 나뉘며 페이지당 최대 10개의 링크가 표시됩니다.

리소스 검색에 대해 자세히 알아보려면 Knowledge Catalog에서 리소스 검색을 참고하세요. 쿼리 표현식 및 필터에 대해 자세히 알아보려면 Knowledge Catalog 검색 구문을 참고하세요.

다음 단계

커넥터 작업 관리 방법 알아보기

dbt Core에서 메타데이터 가져오기 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

제한사항

시작하기 전에

IAM 역할 및 권한

API 사용 설정

dbt 기본 요건

Cloud Storage 역할 이해

dbt Cloud 실행에서 메타데이터 가져오기

dbt Cloud 작업 설정

dbt Google Cloud 콘솔에서 아티팩트 다운로드

dbt 플랫폼 CLI를 사용하여 아티팩트 다운로드

dbt 관리 API를 사용하여 아티팩트 다운로드

실행 ID 가져오기

웹훅을 사용하여 가져오기 트리거

dbt 연결 구성

콘솔

gcloud

필수 플래그

선택적 플래그

REST

수집 재실행

dbt 메타데이터 검색 및 보기

콘솔

gcloud

REST

다음 단계

dbt Core에서 메타데이터 가져오기