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

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

dbt 통합으로 캡처되는 메타데이터는 다음과 같습니다.

  • 기술 메타데이터: 주요 리소스 (소스, 시드, 모델) 및 기술 속성 (열 이름, 데이터 유형, 행 수)이 포함됩니다.
  • 비즈니스 및 시맨틱 메타데이터: dbt MetricFlow로 구동되며 시맨틱 모델, 측정항목, 저장된 쿼리와 같은 비즈니스 정의와 로직이 포함됩니다.
  • 운영 및 데이터 품질 메타데이터: 여기에는 타이밍, 성공 또는 실패 상태, 데이터 업데이트 빈도, 테스트 및 테스트 결과와 같은 실행 메타데이터가 포함됩니다.
  • 계보 및 관계 메타데이터: 여기에는 변환 그래프 (DAG)와 dbt 리소스 간의 종속성, 물리적 변환 블록을 추적하고 연결하는 물리적 계보, 조인 키 및 동적 조인, 상위-하위 관계가 포함됩니다.
  • 사용 메타데이터: dbt 외부에서 데이터가 사용되는 방식을 매핑하는 노출에 포착된 메타데이터가 포함됩니다.

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

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

IAM 역할 및 권한

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

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

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

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

API 사용 설정

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

API 사용 설정하기

dbt 기본 요건

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

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

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

  1. dbt source freshness
  2. dbt build
  3. dbt docs generate --no-compile

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 연결 구성

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

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

콘솔

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

    커넥터로 이동

  2. 연결 추가를 클릭합니다.

  3. 커넥터 목록에서 dbt Core 및 MetricFlow 카드를 선택합니다.

  4. 가져온 dbt 애셋을 보려면 검색 페이지로 이동하거나 대상 항목 그룹 페이지를 확인하세요.

gcloud

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

  1. dbt 메타데이터 아티팩트 파일이 로컬 또는 입력 Cloud Storage 버킷에 저장되어 있는지 확인합니다.
  2. 호출자와 Knowledge Catalog 서비스 에이전트 모두에 적절한 권한이 구성된 출력 스테이징 Cloud Storage 버킷이 있는지 확인합니다.
  3. 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을 빌드하고 업로드하고 메타데이터 작업을 검증하지만 실제로는 수집하지 않습니다.
  4. Created 상태가 표시되는지 확인합니다.

REST

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

  1. dbt 아티팩트를 생성하고 이를 Knowledge Catalog JSON 가져오기 파일 (dbt_metadata.jsonl)로 변환합니다.
  2. 변환된 파일을 Cloud Storage 스테이징 버킷 (gs://BUCKET_NAME/PATH/)에 업로드합니다.
  3. 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입니다.
  4. 가져오기 작업의 상태를 추적하려면 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 리소스가 추가, 이름 변경 또는 삭제됩니다.
  • 항목의 표시 이름, 설명 또는 라벨이 변경됩니다.
  • 항목 계층 구조가 변경됩니다.

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

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

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

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

dbt 메타데이터 검색 및 보기

콘솔

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

    검색 페이지로 이동

  2. 필터 패널에서 dbt 애셋을 필터링합니다.

    • 시스템 섹션에서 가져온 컨텍스트를 선택합니다.
    • 표시되는 관리 커넥터 하위 섹션에서 dbt를 선택합니다.
  3. 검색창에 키워드 또는 자연어 검색을 사용하여 검색어를 입력합니다. 예를 들어 키워드 검색을 사용하여 모든 dbt 애셋을 보려면 system=DBT 또는 system=DBT AND type=dbt-model를 입력합니다.

  4. 검색 결과에서 dbt 애셋을 클릭하여 항목 세부정보 페이지를 열고 스키마, 계보, 기술적 측면을 확인합니다.

gcloud

  1. 프로젝트 전체에서 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
    
  2. 특정 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

  1. 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"
        }'
    
  2. 특정 항목의 전체 메타데이터 세부정보와 측면을 가져오려면 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
    
  3. 특정 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 또는 상대 리소스 이름입니다.

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

제한사항

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

다음 단계