Mengimpor metadata dari dbt Core

Bagi engineer data, engineer analisis, dan data steward, memusatkan metadata sangat penting untuk penemuan dan tata kelola data perusahaan. Saat tim menggunakan dbt untuk transformasi data, metadata operasional, semantik, dan silsilah yang berharga akan dihasilkan, tetapi sering kali tetap terisolasi dalam ekosistem dbt.

Untuk mengintegrasikan informasi ini ke dalam katalog terpusat, Anda dapat mengimpor metadata dari dbt Core, dbt Cloud, dan MetricFlow ke dalam Knowledge Catalog (sebelumnya Dataplex Universal Catalog).

Karena dbt Core beroperasi sebagai mesin transformasi, bukan sistem penyimpanan seperti Oracle atau PostgreSQL, mengimpor metadatanya memungkinkan berbagai kasus penggunaan. Anda mengimpor metadata Oracle atau PostgreSQL untuk menjawab "Data mentah apa yang kita miliki?", dan Anda mengimpor metadata dbt Core untuk menjawab "Bagaimana data kita ditransformasi, apakah data tersebut dapat diandalkan, dan apa artinya bagi bisnis?"

Dokumen ini menjelaskan cara mengimpor metadata menggunakan perintah Google Cloud CLI dan file artefak dbt Anda.

Saat menjalankan integrasi dbt, Anda akan mengambil metadata berikut:

  • Metadata teknis: temukan data perusahaan dengan menjelajahi resource utama (sumber, data awal, model) dan properti teknisnya (nama kolom, jenis data, jumlah baris).
  • Metadata bisnis dan semantik: memberikan konteks untuk alat BI dan agen AI dengan menjelajahi definisi dan logika bisnis yang didukung oleh dbt MetricFlow, seperti model semantik, metrik, dan kueri tersimpan.
  • Metadata kualitas data dan operasional: pantau kondisi pipeline dan pecahkan masalah data dengan menjelajahi metadata eksekusi seperti waktu, status berhasil atau gagal, keaktualan data, dan hasil pengujian.
  • Metadata silsilah dan hubungan: memungkinkan analisis dampak hilir dan pelacakan penyebab utama dengan menjelajahi 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 penggunaan: memecahkan masalah terkait cara aplikasi hilir menggunakan data yang diubah dengan menjelajahi metadata yang diambil dalam eksposur yang memetakan cara data digunakan di luar dbt.

Batasan

  • Mendukung dbt Core v1 (divalidasi terhadap versi 1.11 dan 1.12), dbt Core v2, dan dbt Fusion.
  • gcloud CLI versi 586.0.0 dan yang lebih baru mendukung integrasi dbt dan BigQuery. Untuk menginstal atau mengupdate CLI, lihat Menginstal CLI Google Cloud CLI.
  • Tidak ada koneksi langsung ke dbt Cloud. Untuk mengimpor metadata dari tugas dbt Cloud, dapatkan artefak tugas terlebih dahulu. Lihat Mengimpor metadata dari eksekusi dbt Cloud.
  • 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.
  • Integrasi ini hanya mendukung peristiwa silsilah dbt pada resource BigQuery di API dan grafik Silsilah Data. Entri dbt (sumber, seed, model) untuk sumber pihak ketiga eksternal tidak dicatat dalam silsilah data.

Sebelum memulai

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:

  • Untuk membuat dan mengelola grup entri dan link entri: Admin Katalog Dataplex (roles/dataplex.catalogAdmin), Editor Katalog Dataplex (roles/dataplex.catalogEditor), atau Pemilik Grup Entri Dataplex (roles/dataplex.entryGroupOwner) di project.

  • Untuk menjalankan perintah dbt gcloud dan membuat tugas impor metadata: Ikuti prinsip hak istimewa terendah dan berikan peran berikut:

    • Pemilik Tugas Metadata Dataplex (roles/dataplex.metadataJobOwner) di project.
    • Pengimpor Grup Entri Dataplex (roles/dataplex.entryGroupImporter) di grup entri target atau project. Jika Anda juga mengimpor link entri, berikan Pemilik Grup Entri Dataplex (roles/dataplex.entryGroupOwner) di project. Berikan juga Pemilik Entri Dataplex (roles/dataplex.entryOwner) di setiap project yang menyimpan tabel BigQuery yang ditulisi oleh model dbt Anda. Untuk peran kustom, izin link entri adalah dataplex.entryGroups.useReferenceEntryLink, dataplex.entryGroups.useSchemaJoinEntryLink, dan dataplex.entryLinks.reference.

    Atau, Anda dapat memberikan peran Admin Katalog Dataplex (roles/dataplex.catalogAdmin) dan peran Pemilik Tugas Metadata Dataplex (roles/dataplex.metadataJobOwner) di project.

  • Untuk mengupload metadata yang telah diubah ke bucket penyiapan output (--storage-uri): Storage Object Creator (roles/storage.objectCreator) atau Storage Object Admin (roles/storage.objectAdmin) di bucket penyiapan.

  • Untuk membaca artefak dbt dari bucket Cloud Storage input (--artifacts-path, jika menggunakan Cloud Storage): Storage Object Viewer (roles/storage.objectViewer) atau Storage Object Admin (roles/storage.objectAdmin) di bucket artefak input. Jika Anda memiliki peran Storage Object Admin, peran Storage Object Viewer tidak diperlukan.

  • Untuk melihat metadata dbt: Dataplex Catalog Viewer (roles/dataplex.catalogViewer) di project.

  • Untuk melihat log di Cloud Logging: Logs Viewer (roles/logging.viewer) di project.

Jika memiliki izin yang diperlukan untuk mengelola akses IAM di project, Anda dapat memberikan peran ini ke akun pengguna Anda sendiri dengan menjalankan perintah gcloud berikut:

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"

Jika Anda menjalankan impor menggunakan akun layanan, seperti dalam pipeline CI/CD otomatis, Anda dapat memberikan peran ini ke akun layanan dengan menjalankan perintah gcloud berikut:

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"

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 staging output (--storage-uri) agar tugas impor dapat membaca file metadata yang di-staging:

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"

Ganti kode berikut:

  • PROJECT_ID: Google Cloud Project ID Anda.
  • USER_EMAIL: alamat email akun pengguna Anda.
  • SERVICE_ACCOUNT_EMAIL: alamat email akun layanan Anda.
  • STAGING_BUCKET: nama bucket Cloud Storage penyiapan output Anda (--storage-uri).
  • PROJECT_NUMBER: nomor project Google Cloud Anda.

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.

Di terminal lokal, Cloud Shell, atau lingkungan CI/CD otomatis tempat dbt diinstal, buka direktori root project dbt dan jalankan perintah dbt berikut secara berurutan terhadap satu profil dan target untuk menghasilkan kumpulan lengkap file JSON artefak metadata dbt:

  • Untuk dbt Core 2.x dan dbt Fusion:

    1. dbt source freshness
    2. dbt build

    3. dbt parse --write-catalog

  • Untuk dbt Core 1.x (jika dbt parse tidak menulis katalog):

    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.

Mengimpor metadata dari eksekusi dbt Cloud

Knowledge Catalog tidak terhubung langsung ke dbt Cloud. Karena tugas dbt Cloud menghasilkan file artefak yang sama dengan dbt Core, Anda dapat mengimpor metadata dari dbt Cloud dengan mengambil file artefak tersebut ke direktori lokal atau bucket Cloud Storage input dan menjalankan perintah gcloud.

Sebelum mengambil artefak, konfigurasi tugas dbt Cloud untuk menghasilkan set artefak lengkap. Kemudian, Anda dapat mengambil file artefak dari eksekusi tugas dbt Cloud menggunakan salah satu metode berikut:

Menyiapkan tugas dbt Cloud

Di konsol dbt Google Cloud , konfigurasi setelan tugas Anda untuk membuat set lengkap artefak metadata:

  1. Di bagian Execution settings, pilih Run source freshness. dbt Cloud menjalankan dbt source freshness sebelum perintah tugas untuk menghasilkan sources.json.
  2. Di bagian Commands, tambahkan dbt build.
  3. Tambahkan perintah untuk membuat catalog.json berdasarkan jalur rilis Anda:
    • Untuk jalur rilis dbt Core 2.x dan dbt Fusion: tambahkan dbt parse --write-catalog sebagai perintah tugas.
    • Untuk jalur rilis dbt Core 1.x: tambahkan dbt docs generate --no-compile sebagai perintah tugas, bukan memilih opsi Generate docs on run. Kotak centang Generate docs on run menjalankan dbt docs generate tanpa --no-compile, yang akan menimpa hasil pengujian dari dbt build, seperti yang dijelaskan dalam prasyarat dbt. Perhatikan bahwa jika langkah perintah gagal, tugas juga akan gagal, sedangkan langkah kotak centang tidak akan menyebabkan tugas gagal.

Jika dbt build gagal, misalnya karena pengujian gagal, dbt Cloud akan melewati perintah setelahnya dan run tidak memiliki catalog.json. Untuk selalu menghasilkan satu, tambahkan perintah katalog sebelum dbt build. Kemudian, katalog menjelaskan tabel seperti sebelum build.

Untuk mengetahui informasi selengkapnya, lihat Perintah tugas dan Jalur rilis dalam dokumentasi dbt.

Mendownload artefak dari konsol dbt Google Cloud

Untuk mendownload artefak secara manual dari proses yang selesai di konsol dbt Google Cloud :

  1. Di konsol dbt Google Cloud , buka eksekusi tugas yang telah selesai.
  2. Buka tab Artifacts untuk melihat file artefak yang dihasilkan.
  3. Download manifest.json, catalog.json, run_results.json, dan sources.json ke direktori lokal.
  4. Di terminal lokal atau Cloud Shell, jalankan perintah impor gcloud yang dijelaskan dalam Mengonfigurasi konektivitas dbt dan tetapkan --artifacts-path ke direktori yang berisi file yang didownload.

Untuk mengetahui informasi selengkapnya, lihat Visibilitas eksekusi dalam dokumentasi dbt.

Mendownload artefak menggunakan dbt CLI platform

CLI platform dbt (sebelumnya dbt Cloud CLI) menjalankan perintah dbt di platform dbt Cloud dari terminal lokal Anda dan otomatis mendownload artefak yang dihasilkan ke direktori target/ project dbt lokal Anda.

  1. Di terminal lokal, buka direktori root project dbt Anda dan jalankan tiga perintah yang tercantum di prasyarat dbt.
  2. Jalankan perintah impor gcloud yang dijelaskan dalam Mengonfigurasi konektivitas dbt dan tetapkan --artifacts-path ke root project atau direktori target/.

CLI berjalan dalam lingkungan pengembangan Anda menggunakan kredensial data warehouse pribadi Anda, sehingga metadata yang dihasilkan mencerminkan skema pengembangan Anda, bukan tabel produksi yang dibuat oleh tugas terjadwal. Gunakan CLI untuk alur kerja pengujian atau pengembangan, dan gunakan tugas deployment untuk impor produksi terjadwal.

Untuk mengetahui informasi selengkapnya, lihat Menginstal dbt CLI platform di dokumentasi dbt.

Mendownload artefak menggunakan dbt Administrative API

Anda dapat menggunakan dbt Administrative API untuk mengambil artefak secara terprogram dari setiap run tugas yang telah selesai. Endpoint List Run Artifacts menampilkan jalur file yang dihasilkan oleh proses, dan endpoint Retrieve Run Artifact mendownload file artefak tertentu dari URL berikut:

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

ACCESS_URL bergantung pada region yang menghosting akun dbt Cloud Anda. Mengautentikasi permintaan menggunakan token layanan dbt Cloud. Untuk mengetahui informasi selengkapnya, lihat halaman berikut dalam dokumentasi dbt:

Dari terminal lokal, Cloud Shell, atau lingkungan alur kerja otomatis, download manifest.json, catalog.json, run_results.json, dan sources.json ke direktori lokal atau bucket Cloud Storage, lalu jalankan perintah gcloud yang dijelaskan dalam Mengonfigurasi konektivitas dbt terhadap jalur tersebut.

Secara default, endpoint artefak menampilkan artefak dari langkah terakhir run, kecuali jika Anda menentukan parameter kueri step. Saat Anda mengonfigurasi tugas seperti yang dijelaskan dalam Menyiapkan tugas dbt Cloud, langkah terakhirnya adalah dbt parse --write-catalog atau dbt docs generate --no-compile, yang hanya menulis catalog.json dan membiarkan tiga artefak lainnya tetap utuh di langkah default.

Mengambil ID proses

Untuk mendownload artefak dari proses tertentu, Anda memerlukan ID prosesnya. Anda dapat menyalin ID proses dari URL proses di konsol dbt Google Cloud , atau membuat kueri API dari skrip terminal atau alur kerja untuk proses tugas yang berhasil terbaru:

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

Dalam parameter kueri, status=10 memfilter untuk menjalankan yang telah selesai dengan status Success. Anda dapat melakukan polling pada endpoint ini sesuai jadwal untuk mengidentifikasi run yang berhasil terbaru, mendownload artefaknya, dan menjalankan perintah impor gcloud.

Memicu impor menggunakan webhook

Daripada melakukan polling API, Anda dapat mengonfigurasi webhook dbt Cloud untuk memicu impor metadata otomatis setiap kali tugas selesai dijalankan. Webhook mengirimkan payload ke endpoint HTTP yang Anda berikan:

  1. Di konsol dbt Google Cloud , buka Account settings > Webhooks, lalu klik Create webhook (atau Create new webhook). Konfigurasi langganan webhook:
    • Peristiwa: pilih Run selesai (job.run.completed), yang dipicu hanya setelah run selesai dan artefaknya tersedia untuk didownload.
    • Jobs: pilih tugas deployment dbt Cloud yang ingin Anda pantau.
    • Endpoint: masukkan URL HTTPS layanan yang Anda jalankan (misalnya, layanan Cloud Run atau fungsi Cloud Run).
  2. Simpan token rahasia webhook yang ditampilkan dbt Cloud. Layanan Anda menggunakan rahasia ini untuk memverifikasi header Authorization, yang berisi tanda tangan HMAC-SHA256 dari isi permintaan.
  3. Di layanan Anda, baca data.runId dari payload JSON, download artefak run menggunakan Administrative API seperti yang dijelaskan sebelumnya, dan jalankan perintah gcloud alpha dataplex dbt metadata-jobs create.

Saat menerapkan pengendali webhook, pertimbangkan hal berikut:

  • dbt Cloud menunggu respons paling lama 10 detik. Karena impor metadata memerlukan waktu beberapa menit, kembalikan respons HTTP terlebih dahulu dan jalankan impor di latar belakang (misalnya, sebagai tugas Cloud Run atau dengan tanda --async).
  • job.run.completed juga dipicu untuk proses yang gagal, sehingga proses dengan pengujian yang gagal tetap diimpor. Jangan berlangganan job.run.errored, karena dapat dipicu sebelum artefak run tersedia.

Untuk mengetahui informasi selengkapnya tentang payload webhook dan verifikasi tanda tangan, lihat Webhook untuk tugas Anda di dokumentasi dbt.

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, tidak ada link entri yang dikeluarkan, dan aspek yang artefak dbt-nya tidak ada dalam proses ini akan mempertahankan nilai yang diberikan oleh proses sebelumnya. Gunakan ini untuk penyerapan rutin dan berulang. Lihat Menjalankan ulang penyerapan.
    • --include-entry-links: Memancarkan link entri untuk hubungan dbt. Opsi ini diaktifkan secara default. Untuk menonaktifkannya, gunakan --no-include-entry-links. Perintah memancarkan jenis link entri berikut:
      • reference: satu resource bergantung pada, menjelaskan, atau menggunakan resource lain. Hal ini mencakup dependensi dbt antar-node, pengujian dan resource yang diuji, model semantik atau metrik dan resource yang menjadi dasarnya, node dan makro project yang dipanggilnya, serta node dan tabel BigQuery yang diwujudkan.
      • schema-join: kolom yang dapat digabungkan yang dideklarasikan oleh uji relationships dbt.
    • --skip-bigquery-link: Lewati link reference (node dbt → tabel BigQuery fisik). Secara default, link reference dikeluarkan untuk setiap node dbt yang diwujudkan (model, seed, snapshot) yang set data BigQuery-nya berada di lokasi impor (--location). Sumber dbt tidak menerima link reference ke tabel BigQuery-nya. Link entri hanya dapat mereferensikan entri @bigquery di region yang sama, sehingga set data di region lain akan otomatis dilewati. Untuk menentukan region setiap set data, perintah memanggil BigQuery API, sehingga pemanggil memerlukan izin bigquery.datasets.get pada set data tersebut; tanpa izin ini, perintah tidak dapat melewati set data di region lain dan link ke set data tersebut tidak dapat diselesaikan. Jika tabel BigQuery tidak dikatalogkan di Knowledge Catalog, gunakan --skip-bigquery-link.
    • --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.
  • Dependensi dbt berubah, misalnya saat panggilan ref(), source(), pengujian, atau makro ditambahkan atau dihapus. --aspects-only tidak membuat atau memperbarui link entri.
  • Anda mengubah --include-entry-links atau --skip-bigquery-link.

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 mencantumkan link entri dari entri dbt, panggil metode projects.locations:lookupEntryLinks. Misalnya, untuk mengambil tabel BigQuery yang diwujudkan oleh model dbt:

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 adalah nama lengkap resource entri dbt. Hasil diberi nomor halaman, dengan maksimal 10 link per halaman.

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.

Langkah berikutnya