Mengimpor metadata dari dbt Core

Knowledge Catalog (sebelumnya Dataplex Universal Catalog) memungkinkan Anda mengimpor metadata operasional, semantik, dan silsilah dari dbt Core, dbt Cloud, dan MetricFlow menggunakan Google Cloud CLI dan file artefak dbt Anda. Daripada membiarkan metadata transformasi terpisah dalam ekosistem dbt, Anda dapat memusatkannya untuk membantu data engineer, analytics engineer, dan data steward menemukan dan mengatur data perusahaan.

Metadata dan kasus penggunaan yang diimpor

Karena dbt Core beroperasi sebagai mesin transformasi, bukan sistem penyimpanan seperti Oracle atau PostgreSQL, mengimpor metadatanya mendukung kasus penggunaan yang berbeda. 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 diubah, apakah data tersebut dapat diandalkan, dan apa artinya bagi bisnis?"

Saat menjalankan integrasi dbt, Anda akan mengambil metadata berikut:

  • Metadata teknis: temukan data perusahaan dengan menjelajahi resource utama (sumber, seed, 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 operasional dan kualitas data: pantau kondisi pipeline dan pecahkan masalah data dengan mempelajari metadata eksekusi seperti pengaturan waktu, status keberhasilan atau kegagalan, keaktualan data, dan hasil pengujian.
  • Metadata silsilah dan hubungan: melakukan analisis dampak downstream dan pelacakan akar masalah 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 konsumsi: memecahkan masalah terkait cara aplikasi downstream 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 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 operasi dbt Cloud.
  • Skema yang sangat besar atau bertingkat dalam akan dipotong: satu aspek tidak boleh melebihi batas ukuran per aspek, sehingga skema bertingkat dalam mungkin kehilangan kolom di bagian akhir.
  • --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 Data Lineage. Entri dbt (sumber, seed, model) untuk sumber pihak ketiga eksternal tidak dicatat dalam silsilah data.

Sebelum memulai

Sebelum Anda 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. Memenuhi 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 untuk mengonfigurasi konektor dbt, minta administrator untuk memberi Anda peran IAM berikut:

  • Untuk membuat dan mengelola grup entri dan link entri: Dataplex Catalog Admin (roles/dataplex.catalogAdmin), Dataplex Catalog Editor (roles/dataplex.catalogEditor), atau Dataplex Entry Group Owner (roles/dataplex.entryGroupOwner) di project.

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

    • Dataplex Metadata Job Owner (roles/dataplex.metadataJobOwner) di project.
    • Dataplex Entry Group Importer (roles/dataplex.entryGroupImporter) di grup entri target atau project. Jika Anda juga mengimpor link entri, berikan Dataplex Entry Group Owner (roles/dataplex.entryGroupOwner) pada project. Berikan juga Dataplex Entry Owner (roles/dataplex.entryOwner) pada setiap project yang menyimpan tabel BigQuery yang menjadi tujuan penulisan model dbt Anda. Untuk peran khusus, izin link entri adalah dataplex.entryGroups.useReferenceEntryLink, dataplex.entryGroups.useSchemaJoinEntryLink, dan dataplex.entryLinks.reference.

    Atau, Anda dapat memberikan peran Dataplex Catalog Admin (roles/dataplex.catalogAdmin) dan peran Dataplex Metadata Job Owner (roles/dataplex.metadataJobOwner) pada project.

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

  • 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 Anda 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-stage:

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: Project ID Google Cloud Anda.
  • USER_EMAIL: alamat email akun pengguna Anda.
  • SERVICE_ACCOUNT_EMAIL: alamat email akun layanan Anda.
  • STAGING_BUCKET: nama bucket Cloud Storage staging output Anda (--storage-uri).
  • PROJECT_NUMBER: nomor project Google Cloud Anda.

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

Mengaktifkan API

Mengaktifkan Knowledge Catalog API.

Mengaktifkan API

Prasyarat dbt

Untuk mengimpor kumpulan lengkap metadata dbt, sebaiknya buat keempat file artefak JSON dbt. Hanya manifest.json yang diperlukan; yang lain memperkaya impor dan transformasi akan menurun secara halus tanpa elemen 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 tanpa jenis.
  • 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 utama 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 (tempat 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 digabungkan:

  • Input (artefak sumber dbt): Tempat file JSON dbt yang Anda buat berada. Ini dapat berupa jalur direktori lokal di komputer atau runner CI Anda (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 persiapan 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 staging 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 tempat tugas impor Knowledge Catalog membaca 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 operasi 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, konfigurasikan tugas dbt Cloud untuk membuat set artefak lengkap. Kemudian, Anda dapat mengambil file artefak dari operasi tugas dbt Cloud menggunakan salah satu metode berikut:

Menyiapkan tugas dbt Cloud

Di konsol dbt Google Cloud , konfigurasikan 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 membuat 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 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 menggagalkan tugas.

Jika dbt build gagal, misalnya karena pengujian gagal, dbt Cloud akan melewati perintah setelahnya dan operasi tidak memiliki catalog.json. Untuk selalu menghasilkan satu, tambahkan perintah katalog sebelum dbt build. Kemudian, katalog akan mendeskripsikan 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 operasi yang telah selesai di konsolGoogle Cloud dbt:

  1. Di konsol dbt Google Cloud , buka operasi 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 operasi dalam dokumentasi dbt.

Mendownload artefak menggunakan CLI platform dbt

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 dalam 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, sehingga metadata yang dihasilkan mencerminkan skema pengembangan, 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 CLI platform dbt dalam dokumentasi dbt.

Mendownload artefak menggunakan dbt Administrative API

Anda dapat menggunakan dbt Administrative API untuk mengambil artefak secara terprogram dari setiap operasi tugas yang telah selesai. Endpoint List Run Artifacts menampilkan jalur file yang dihasilkan oleh operasi, 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 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 eksekusi, 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 pada langkah default.

Mengambil ID operasi

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

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 operasi yang telah selesai dengan status Success. Anda dapat melakukan polling endpoint ini sesuai jadwal untuk mengidentifikasi eksekusi terbaru yang berhasil, mendownload artefaknya, dan menjalankan perintah impor gcloud.

Memicu impor menggunakan webhook

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

  1. Di konsol dbt Google Cloud , buka Account settings > Webhooks dan klik Create webhook (atau Create new webhook). Konfigurasi langganan webhook:
    • Events: pilih Run completed (job.run.completed), yang hanya dipicu setelah operasi 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 operasi 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 maksimal 10 detik. Karena impor metadata memerlukan waktu beberapa menit, tampilkan respons HTTP terlebih dahulu dan jalankan impor di latar belakang (misalnya, sebagai tugas Cloud Run atau dengan flag --async).
  • job.run.completed juga dipicu untuk operasi yang gagal, sehingga operasi dengan pengujian yang gagal tetap diimpor. Jangan berlangganan job.run.errored, karena dapat dipicu sebelum artefak operasi tersedia.

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

Mengonfigurasi konektivitas dbt

Untuk membuat konektivitas dbt, Anda harus menjalankan perintah dbt yang sesuai terlebih dahulu untuk membuat artefak metadata. Setelah file JSON disimpan dan dapat diakses, proses impor akan 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 di --artifacts-path).
  2. Mentransformasi metadata: Transformasikan konten ke dalam format impor metadata Knowledge Catalog (dbt_metadata.jsonl).
  3. Upload ke staging: Upload file impor metadata yang telah diubah ke lokasi Cloud Storage staging output yang ditentukan di --storage-uri.
  4. Memicu tugas impor: Memicu tugas impor metadata Knowledge Catalog yang menginstruksikan agen layanan Knowledge Catalog untuk membaca dan menyerap metadata yang di-stage dari --storage-uri ke dalam resource Knowledge Catalog.

Konsol

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

    Buka Connectors

  2. Klik Tambahkan koneksi.

  3. Dalam daftar Connectors, pilih kartu dbt Core and MetricFlow.

  4. Untuk melihat aset dbt yang diimpor, buka halaman Search atau lihat halaman Entry groups 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 memiliki bucket Cloud Storage staging output yang dikonfigurasi 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 yang diperlukan

    • --storage-uri=STORAGE_URI: Awalan Cloud Storage URI (Output/Staging) (gs://bucket/path/) tempat JSONL yang diubah diupload dan tempat tugas impor membaca 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 awalan 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 Cloud Storage URI disediakan, pemanggil harus memiliki akses baca (roles/storage.objectViewer atau roles/storage.objectAdmin) ke bucket input.
    • --async: Langsung menampilkan, 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 (defaultnya adalah dbt-metadata-ingestion).
    • --aspects-only: Hanya perbarui metadata yang diamati oleh operasi dbt ini dan biarkan grup entri lainnya tidak tersentuh. Tidak ada entri yang dibuat, dihapus, atau diubah induknya, tidak ada link entri yang ditampilkan, dan aspek yang artefak dbt-nya tidak ada dalam operasi ini akan mempertahankan nilai yang diberikan oleh operasi sebelumnya. Gunakan metode ini untuk penyerapan rutin dan berulang. Lihat Menjalankan ulang penyerapan.
    • --include-entry-links: Memunculkan link entri untuk hubungan dbt. Fitur ini diaktifkan secara default. Untuk menonaktifkannya, gunakan --no-include-entry-links. Perintah ini memunculkan jenis link entri berikut:
      • reference: satu resource bergantung pada, mendeskripsikan, atau menggunakan resource lain. Hal ini mencakup dependensi dbt antara node, pengujian dan resource yang diujinya, model semantik atau metrik dan resource yang menjadi dasarnya, node dan makro project yang dipanggilnya, serta node dan tabel BigQuery yang dimaterialisasikannya.
      • schema-join: kolom yang dapat digabungkan yang dideklarasikan oleh pengujian relationships dbt.
    • --skip-bigquery-link: Lewati link reference (node dbt → tabel BigQuery fisik). Secara default, link reference akan ditampilkan untuk setiap node dbt terwujud (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 ini 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 akan di-resolve. Jika tabel BigQuery tidak dikatalogkan di Knowledge Catalog, gunakan --skip-bigquery-link.
    • --validate-only: Mem-build dan mengupload JSON serta memvalidasi tugas metadata, tetapi tidak benar-benar menyerap.

  4. Pastikan Anda menerima status Created.

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 staging 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: project ID Google Cloud tempat grup entri Anda berada.
    • LOCATION: region grup entri Anda (misalnya, us-central1).
    • JOB_ID: ID unik untuk tugas metadata.
    • BUCKET_NAME/PATH: awalan Cloud Storage URI 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 akan menjadwalkan operasi pertama sesuai dengan konfigurasi Anda, atau Anda dapat memulainya secara manual.

Menjalankan ulang penyerapan

Setelah impor pertama, sebagian besar operasi hanya perlu memuat ulang metadata untuk resource yang sudah ada. Gunakan --aspects-only untuk operasi tersebut. Alat ini hanya mengupdate apa yang diamati oleh dbt run dan membiarkan semua hal lain dalam grup entri, sehingga aman untuk dijalankan berulang kali, sesuai jadwal, dan dari lebih dari satu tugas.

Jalankan penyerapan penuh (hilangkan --aspects-only) saat kumpulan 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 ref(), source(), pengujian, atau panggilan makro ditambahkan atau dihapus. --aspects-only tidak membuat atau memperbarui link entri.
  • Anda mengubah --include-entry-links atau --skip-bigquery-link.

Eksekusi penuh akan menulis ulang aspek yang diperlukan setiap entri dari artefak di disk, jadi jalankan dari set artefak selengkap mungkin yang dapat dihasilkan pipeline Anda.

Jalankan --aspects-only untuk pemuatan ulang rutin:

  • Setelah perintah dbt apa 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 operasi 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 Search Knowledge Catalog.

    Buka Penelusuran

  2. Di panel Filters, filter aset dbt:

    • Di bagian System, pilih Imported Context.
    • Di subbagian Managed Connectors yang muncul, pilih dbt.

  3. Di kolom penelusuran, masukkan kueri Anda menggunakan kata kunci atau penelusuran 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 mana pun untuk membuka halaman detail entrinya guna melihat skema, silsilah, 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 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: Project ID Google Cloud 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 dari 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 API projects.locations:lookupContext:

    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: Project ID Google Cloud 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 dari entri dbt.

Untuk mencantumkan link entri dari entri dbt, panggil metode projects.locations:lookupEntryLinks. Misalnya, untuk mengambil tabel BigQuery yang dimaterialisasi 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 resource lengkap 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