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

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

이 문서에서는 gcloud 명령어를 사용하여 dbt Core 및 MetricFlow에서 Knowledge Catalog (이전의 Dataplex Universal Catalog)로 메타데이터를 가져오는 방법을 설명합니다.

다음 메타데이터는 dbt 통합에 의해 캡처됩니다.

기술 메타데이터: 여기에는 주요 리소스 (소스, 시드, 모델)와 기술 속성 (열 이름, 데이터 유형, 행 수)이 포함됩니다.
비즈니스 및 의미 메타데이터: dbt MetricFlow로 구동되며 의미 모델, 측정항목, 저장된 쿼리와 같은 비즈니스 정의 및 로직이 포함됩니다.
운영 및 데이터 품질 메타데이터: 여기에는 타이밍, 성공 또는 실패 상태, 데이터 최신 상태, 테스트 및 테스트 결과와 같은 실행 메타데이터가 포함됩니다.
계보 및 관계 메타데이터: 여기에는 변환 그래프 (DAG) 및 dbt 리소스 간의 종속 항목, 실제 변환 블록을 추적하고 연결하는 실제 계보, 조인 키 및 동적 조인, 상위-하위 관계가 포함됩니다.
사용 메타데이터: 여기에는 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.catalogAdmin) 역할과 Dataplex 메타데이터 작업 소유자 (roles/dataplex.metadataJobOwner) 역할을 부여할 수 있습니다.
변환된 메타데이터를 출력 스테이징 버킷 (--storage-uri)에 업로드하려면: 스토리지 객체 제작자 (roles/storage.objectCreator) 또는 스토리지 객체 관리자 (roles/storage.objectAdmin)를 스테이징 버킷에.
입력 Cloud Storage 버킷에서 dbt 아티팩트를 읽으려면 (--artifacts-path, Cloud Storage를 사용하는 경우): 스토리지 객체 뷰어 (roles/storage.objectViewer) 또는 스토리지 객체 관리자 (roles/storage.objectAdmin) 입력 아티팩트 버킷에. 스토리지 객체 관리자 역할이 있는 경우 스토리지 객체 뷰어 역할은 필요하지 않습니다.
dbt 메타데이터를 보려면 프로젝트에 대한 Dataplex 카탈로그 뷰어 (roles/dataplex.catalogViewer).
Cloud Logging에서 로그를 보려면 프로젝트에 대한 로그 뷰어 (roles/logging.viewer).

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

역할 부여에 대한 자세한 내용은 Manage access를 참조하세요.

API 사용 설정

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

API 사용 설정하기

dbt 기본 요건

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

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

전체 dbt 메타데이터 아티팩트 JSON 파일을 생성하려면 다음 dbt 명령어를 이 순서대로 실행하면 됩니다.

dbt source freshness
dbt build
dbt docs generate --no-compile

경고: --no-compile이 없으면 dbt docs generate가 모든 노드의 success 상태로 run_results.json을 덮어씁니다. 이전 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 가져오기 스테이징 버킷): 명령어가 변환된 메타데이터 가져오기 파일 (dbt_metadata.jsonl)을 업로드하고 gcloud 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 연결 구성

dbt 연결을 설정하려면 먼저 적절한 dbt 명령어를 실행하여 메타데이터 아티팩트를 생성해야 합니다. JSON 파일이 저장되고 액세스할 수 있게 되면 gcloud alpha dataplex dbt metadata-jobs create 명령어를 사용하여 다음 작업을 할 수 있습니다.

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

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 아티팩트가 없는 관점은 이전 실행에서 제공한 값을 유지합니다. 일상적이고 반복적인 수집에 사용합니다. 수집 다시 실행을 참조하세요.
- --validate-only: JSON을 빌드하고 업로드하고 메타데이터 작업을 검증하지만 실제로 수집하지는 않습니다.
생성됨 상태를 받았는지 확인합니다.
작업을 만든 후 Knowledge Catalog는 구성에 따라 첫 번째 실행을 예약하거나 수동으로 시작할 수 있습니다.

수집 다시 실행

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

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

항목 그룹으로의 첫 번째 수집.
dbt 리소스가 추가, 이름 변경 또는 삭제됩니다.
항목의 표시 이름, 설명 또는 라벨이 변경됩니다.
항목 계층 구조가 변경됩니다.

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

일상적인 새로고침을 위해 --aspects-only를 실행합니다.

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

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

dbt 메타데이터 검색 및 보기

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

검색으로 이동
필터 패널에서 프로젝트, 시스템, 유형 별칭 섹션을 사용하여 dbt 애셋을 필터링할 수 있습니다. 시스템 섹션에서 가져온 컨텍스트 를 선택합니다. 이 필터를 선택하면 관리형 커넥터 하위 섹션이 열립니다. 모든 dbt 메타데이터를 필터링하려면 dbt 를 선택합니다.
검색 필드를 사용하여 검색어를 실행할 수 있습니다. 키워드 또는 자연어 검색을 실행할 수 있습니다. 예를 들어 키워드 검색을 통해 모든 dbt 애셋을 보려면 system=DBT를 입력합니다.

리소스 검색에 대한 자세한 내용은 Knowledge Catalog에서 리소스 검색을 참조하세요. 검색창에서 사용할 수 있는 표현식에 대한 자세한 내용은 Knowledge Catalog의 검색 문법을 참조하세요.
LookupContext API를 사용하여 특정 dbt 리소스의 LLM 컨텍스트를 가져올 수도 있습니다.

제한사항

최신 dbt Core v1 버전 (버전 1.11 및 1.12에 대해 검증됨)을 지원합니다. dbt Core v2 및 dbt Fusion은 지원되지 않습니다.
모델 버전 관리를 사용하는 dbt 모델은 지원되지 않습니다.
dbt Cloud는 지원되지 않습니다.
매우 크거나 깊게 중첩된 스키마는 잘립니다. 단일 관점은 관점당 크기 한도를 초과할 수 없으므로 깊게 중첩된 스키마는 후행 필드를 잃을 수 있습니다.
--aspects-only는 메타데이터를 추가하고 새로고침할 수 있지만 삭제할 수는 없습니다. dbt 리소스를 삭제하려면 전체 실행이 필요합니다.
항목 링크는 지원되지 않습니다.
이 통합은 Data Lineage API 및 그래프의 BigQuery 리소스에 대한 dbt 계보 이벤트만 지원합니다. 외부 서드 파티 소스의 dbt 항목 (소스, 시드, 모델)은 데이터 계보에 캡처되지 않습니다.
- Data Lineage API에서 모든 dbt 계보 이벤트를 수집하려면 다음 항목을 사용합니다. OpenLineage dbt 통합 그런 다음 OpenLineage를 Knowledge Catalog와 통합하여 dbt에서 데이터 lineage를 가져오고 시각화합니다.

다음 단계

커넥터 작업 관리 방법을 알아봅니다.