Mengimpor metadata dari dbt Core

Dokumen ini menjelaskan cara mengimpor metadata dari dbt Core dan MetricFlow ke Knowledge Catalog (sebelumnya Dataplex Universal Catalog) menggunakan perintah gcloud.

Metadata berikut diambil oleh integrasi dbt:

  • Metadata teknis: ini mencakup resource utama (sumber, data awal, model) dan properti teknisnya (nama kolom, jenis data, jumlah baris).
  • Metadata bisnis dan semantik: didukung oleh dbt MetricFlow, ini mencakup definisi dan logika bisnis seperti model semantik, metrik, dan kueri tersimpan.
  • Metadata operasional dan kualitas data: ini mencakup metadata eksekusi seperti waktu, status keberhasilan atau kegagalan, keaktualan data, pengujian, dan hasil pengujian.
  • Metadata silsilah dan hubungan: mencakup grafik transformasi (DAG) dan dependensi antara resource dbt, silsilah fisik yang melacak dan menautkan blok transformasi fisik, kunci gabungan dan gabungan dinamis, serta hubungan induk-turunan.
  • Metadata konsumsi: ini mencakup metadata yang diambil dalam eksposur yang memetakan cara data digunakan di luar dbt.

Sebelum dapat mengimpor metadata dari dbt Core dan MetricFlow, selesaikan tugas-tugas berikut:

  1. Berikan peran dan izin yang diperlukan.
  2. Aktifkan Knowledge Catalog API.
  3. Penuhi prasyarat dbt.
  4. Buat grup entri tujuan jika belum ada.
  5. Pahami peran Cloud Storage.

Peran dan izin IAM

Untuk membuat dan mengelola tugas konektor Knowledge Catalog, Anda memerlukan peran Identity and Access Management (IAM) yang memberikan izin untuk Knowledge Catalog dan Cloud Storage.

Untuk mendapatkan izin yang Anda perlukan guna mengonfigurasi konektor dbt, minta administrator Anda untuk memberi Anda peran IAM berikut:

Selain itu, Anda harus memberikan peran Storage Object Viewer (roles/storage.objectViewer) kepada agen layanan Knowledge Catalog (service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com) di bucket Cloud Storage penyiapan output (--storage-uri) agar tugas impor dapat membaca file metadata yang disiapkan.

Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses.

Mengaktifkan API

Aktifkan Knowledge Catalog API.

Mengaktifkan API

Prasyarat dbt

Untuk mengimpor set lengkap metadata dbt, sebaiknya buat keempat file artefak JSON dbt. Hanya manifest.json yang diperlukan; yang lain memperkaya impor dan transformasi akan berjalan dengan baik tanpa parameter tersebut:

  • manifest.json (wajib): Struktur project inti dan grafik eksekusi. Juga membawa model semantik, metrik, dan kueri tersimpan MetricFlow.
  • catalog.json: Nama kolom dan jenis data. Tanpa catalog.json, aspek skema diimpor dengan kolom yang tidak diketik.
  • run_results.json: Hasil pengujian dan metadata eksekusi.
  • sources.json: Keaktualan sumber.

Untuk membuat file JSON artefak metadata dbt lengkap, Anda dapat menjalankan perintah dbt berikut dalam urutan ini:

  1. dbt source freshness
  2. dbt build

  3. dbt docs generate --no-compile

Memahami peran Cloud Storage

Mengimpor metadata dbt melibatkan dua lokasi Cloud Storage berbeda yang memiliki tujuan berbeda dan tidak boleh disamakan:

  • Input (artefak sumber dbt): Tempat file JSON dbt yang dihasilkan berada. Ini dapat berupa jalur direktori lokal di komputer atau runner CI (seperti ./target/ atau .) atau awalan URI bucket Cloud Storage input (seperti gs://my-dbt-artifacts-bucket/target/). Anda memberikan jalur ini menggunakan flag --artifacts-path. Perintah gcloud membaca file input ini selama penyiapan tugas. Pemanggil yang menjalankan perintah gcloud memerlukan akses baca (roles/storage.objectViewer atau roles/storage.objectAdmin) jika menggunakan Cloud Storage. Agen layanan Knowledge Catalog tidak memerlukan akses ke bucket artefak input.
  • Output (bucket penyiapan impor Knowledge Catalog): Awalan URI bucket Cloud Storage (seperti gs://my-staging-bucket/dbt-imports/) tempat perintah gcloud mengupload file impor metadata yang telah diubah (dbt_metadata.jsonl), dan dari mana tugas impor Knowledge Catalog dibaca selama penyerapan. Anda memberikan URI ini menggunakan flag --storage-uri. Pemanggil yang menjalankan perintah gcloud memerlukan akses tulis (roles/storage.objectCreator atau roles/storage.objectAdmin) untuk mengupload file, dan agen layanan Knowledge Catalog memerlukan akses baca (roles/storage.objectViewer) untuk mengimpornya.

Mengonfigurasi konektivitas dbt

Untuk membuat konektivitas dbt, Anda harus menjalankan perintah dbt yang sesuai terlebih dahulu untuk menghasilkan artefak metadata. Setelah file JSON disimpan dan dapat diakses, proses impor melakukan tindakan berikut:

  1. Membaca artefak input: Membaca artefak JSON yang dihasilkan oleh dbt Core dan MetricFlow dari lokasi input (direktori lokal atau URI Cloud Storage yang ditentukan dalam --artifacts-path).
  2. Transformasi metadata: Mengubah konten menjadi format impor metadata Knowledge Catalog (dbt_metadata.jsonl).
  3. Upload ke penyiapan: Upload file impor metadata yang telah diubah ke lokasi Cloud Storage penyiapan output yang ditentukan dalam --storage-uri.
  4. Memicu tugas impor: Memicu tugas impor metadata Knowledge Catalog yang menginstruksikan agen layanan Knowledge Catalog untuk membaca dan menyerap metadata bertahap dari --storage-uri ke resource Knowledge Catalog.

Konsol

  1. Di konsol Google Cloud , buka halaman Konektor Knowledge Catalog.

    Buka Konektor

  2. Klik Tambahkan koneksi.

  3. Di daftar Konektor, pilih kartu dbt Core dan MetricFlow.

  4. Untuk melihat aset dbt yang diimpor, buka halaman Penelusuran atau lihat halaman Grup entri tujuan.

gcloud

Untuk membuat tugas metadata dbt, selesaikan langkah-langkah berikut:

  1. Pastikan file artefak metadata dbt disimpan secara lokal atau di bucket Cloud Storage input.
  2. Pastikan Anda telah mengonfigurasi bucket Cloud Storage penyiapan output dengan izin yang sesuai untuk pemanggil dan agen layanan Knowledge Catalog.

  3. Dari Cloud Shell, terminal lokal, atau alat alur kerja otomatis, jalankan perintah 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/

    Flag wajib

    • --storage-uri=STORAGE_URI: Awalan URI Cloud Storage (Output/Penyiapan) (gs://bucket/path/) tempat JSONL yang diubah diupload dan tempat tugas impor dibaca selama penyerapan. Pemanggil harus memiliki akses tulis (roles/storage.objectCreator atau roles/storage.objectAdmin), dan agen layanan Knowledge Catalog harus memiliki akses baca (roles/storage.objectViewer).

    Flag opsional

    • --artifacts-path=ARTIFACTS_PATH: (Input) Jalur ke artefak dbt sumber. Ini dapat berupa jalur direktori lokal (seperti . atau ./target) atau prefiks URI Cloud Storage (seperti gs://my-bucket/dbt-artifacts/). Dapat mengarah ke root project dbt (subdirektori target/ terdeteksi secara otomatis) atau langsung ke direktori yang berisi manifest.json. Nilai defaultnya adalah .. Jika URI Cloud Storage diberikan, pemanggil harus memiliki akses baca (roles/storage.objectViewer atau roles/storage.objectAdmin) ke bucket input.
    • --async: Langsung ditampilkan, tanpa menunggu operasi yang sedang berlangsung selesai.
    • --entry-group=ENTRY_GROUP: ID singkat grup entri yang menerima entri dbt. Harus sudah ada di project dan lokasi (default adalah dbt-metadata-ingestion).
    • --aspects-only: Hanya memperbarui metadata yang diamati oleh proses dbt ini dan membiarkan grup entri lainnya tidak berubah. Tidak ada entri yang dibuat, dihapus, atau diubah induknya, dan aspek yang artefak dbt-nya tidak ada dari proses ini mempertahankan nilai yang diberikan oleh proses sebelumnya. Gunakan ini untuk penyerapan rutin dan berulang. Lihat Menjalankan ulang penyerapan.
    • --validate-only: Bangun dan upload JSON serta validasi tugas metadata, tetapi jangan menyerap.

  4. Pastikan Anda menerima status Dibuat.

REST

Untuk mengimpor metadata dbt menggunakan REST API:

  1. Buat artefak dbt dan ubah menjadi file impor JSON Knowledge Catalog (dbt_metadata.jsonl).
  2. Upload file yang telah diubah ke bucket penyiapan Cloud Storage Anda (gs://BUCKET_NAME/PATH/).

  3. Panggil metode 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"
          ]
        }
      }
    }'

    Ganti kode berikut:

    • PROJECT_ID: Google Cloud Project ID tempat grup entri Anda berada.
    • LOCATION: region grup entri Anda (misalnya, us-central1).
    • JOB_ID: ID unik untuk tugas metadata.
    • BUCKET_NAME/PATH: awalan URI Cloud Storage tempat dbt_metadata.jsonl diupload.
    • ENTRY_GROUP: ID singkat grup entri tujuan.

  4. Untuk melacak status tugas impor, gunakan metode 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

Setelah Anda membuat tugas, Knowledge Catalog menjadwalkan tugas pertama sesuai dengan konfigurasi Anda, atau Anda dapat memulainya secara manual.

Menjalankan ulang penyerapan

Setelah impor pertama, sebagian besar proses hanya perlu memuat ulang metadata untuk resource yang sudah ada. Gunakan --aspects-only untuk menjalankan tugas tersebut. Tindakan ini hanya memperbarui apa yang diamati oleh eksekusi dbt dan membiarkan semuanya di grup entri, sehingga aman untuk dijalankan berulang kali, pada jadwal apa pun, dan dari lebih dari satu tugas.

Jalankan penyerapan penuh (hilangkan --aspects-only) saat set entri berubah:

  • Penyerapan pertama ke dalam grup entri.
  • Resource dbt ditambahkan, diganti namanya, atau dihapus.
  • Nama tampilan, deskripsi, atau label entri berubah.
  • Hierarki entri berubah.

Run lengkap menulis ulang setiap aspek yang diperlukan entri dari artefak di disk, jadi eksekusi dari set artefak selengkap mungkin yang dapat dihasilkan pipeline Anda.

Jalankan --aspects-only untuk refresh rutin:

  • Setelah perintah dbt mana pun yang dijalankan pipeline Anda: dbt build, dbt test, dbt source freshness, atau pembangunan ulang yang dipersempit --select.
  • Kolom ditambahkan, dihapus, diketik ulang, atau dideskripsikan ulang.
  • SQL model berubah dan proses juga menulis catalog.json.
  • Hasil pengujian baru atau keaktualan sumber.

--aspects-only dapat menambahkan dan memperbarui metadata, tetapi tidak dapat menghapusnya.

Menelusuri dan melihat metadata dbt

Konsol

  1. Di konsol Google Cloud , buka halaman Penelusuran Knowledge Catalog.

    Buka Penelusuran

  2. Di panel Filter, filter aset dbt:

    • Di bagian Sistem, pilih Konteks yang Diimpor.
    • Di subbagian Managed Connectors yang muncul, pilih dbt.

  3. Di kolom penelusuran, masukkan kueri Anda menggunakan penelusuran kata kunci atau bahasa alami. Misalnya, untuk melihat semua aset dbt menggunakan penelusuran kata kunci, masukkan system=DBT atau system=DBT AND type=dbt-model.

  4. Di hasil penelusuran, klik aset dbt apa pun untuk membuka halaman detail entri guna melihat skema, asal-usul, dan aspek teknisnya.

gcloud

  1. Untuk menelusuri entri dbt di seluruh project Anda, gunakan perintah gcloud dataplex entries search:

    gcloud dataplex entries search 'system=DBT' \
    --project=PROJECT_ID

    Untuk memfilter menurut jenis entri dbt tertentu (seperti model atau sumber):

    gcloud dataplex entries search 'system=DBT AND type=dbt-model' \
    --project=PROJECT_ID

  2. Untuk melihat detail dan aspek lengkap dari entri dbt tertentu, gunakan perintah gcloud dataplex entries lookup:

    gcloud dataplex entries lookup ENTRY_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --entry-group=ENTRY_GROUP \
    --view=FULL

    Ganti kode berikut:

    • PROJECT_ID: Google Cloud Project ID Anda.
    • LOCATION: lokasi grup entri (misalnya, us-central1).
    • ENTRY_GROUP: ID singkat grup entri tujuan Anda (misalnya, dbt-metadata-ingestion).
    • ENTRY_ID: ID singkat atau nama resource relatif entri dbt.

REST

  1. Untuk menelusuri entri dbt, panggil metode 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"
    }'

    Untuk memfilter menurut jenis resource dbt tertentu:

    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. Untuk mengambil detail dan aspek metadata lengkap untuk entri tertentu, panggil metode 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. Untuk mengambil konteks LLM untuk resource dbt tertentu, gunakan 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"
      ]
    }'

    Ganti kode berikut:

    • PROJECT_ID: Google Cloud Project ID Anda.
    • LOCATION: lokasi grup entri (misalnya, us-central1).
    • ENTRY_GROUP: ID singkat grup entri tujuan Anda (misalnya, dbt-metadata-ingestion).
    • ENTRY_ID: ID singkat atau nama resource relatif entri dbt.

Untuk mempelajari lebih lanjut cara menelusuri resource, lihat Menelusuri resource di Knowledge Catalog. Untuk mempelajari lebih lanjut ekspresi dan filter kueri, lihat Sintaksis penelusuran untuk Knowledge Catalog.

Batasan

  • Mendukung versi dbt Core v1 terbaru (divalidasi terhadap versi 1.11 dan 1.12). dbt Core v2 dan dbt Fusion tidak didukung.
  • Model dbt yang menggunakan pembuatan versi model tidak didukung.
  • dbt Cloud tidak didukung.
  • Skema yang sangat besar atau bertingkat dalam akan dipangkas: satu aspek tidak boleh melebihi batas ukuran per aspek, sehingga skema bertingkat dalam mungkin kehilangan kolom berikutnya.
  • --aspects-only dapat menambahkan dan memperbarui metadata, tetapi tidak dapat menghapusnya. Menghapus resource dbt memerlukan eksekusi penuh.
  • Link entri tidak didukung.
  • Integrasi ini hanya mendukung peristiwa silsilah dbt pada resource BigQuery di API dan grafik Silsilah Data. Entri dbt (sumber, seed, model) untuk sumber 3P eksternal tidak dicatat dalam silsilah data.

Langkah berikutnya