Mengimpor metadata dari dbt Core

Pratinjau

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

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: mencakup resource utama (sumber, seed, 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: mencakup metadata eksekusi seperti waktu, status berhasil atau gagal, 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 penggunaan: 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 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 untuk mengonfigurasi konektor dbt, minta administrator Anda untuk memberi Anda peran IAM berikut:

• Untuk membuat dan mengelola grup 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: Untuk mengikuti prinsip hak istimewa terendah, 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.

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

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

• 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.

Selain itu, Anda harus memberikan peran Storage Object Viewer (roles/storage.objectViewer) kepada agen layanan Knowledge Catalog ([e-mail]) di bucket Cloud Storage penahapan output (--storage-uri) sehingga tugas impor dapat membaca file metadata yang ditahapkan.

Catatan: Tugas impor juga memerlukan izin untuk menggunakan jenis aspek dbt pihak pertama (dataplex.aspectTypes.use). Izin ini diberikan secara default pada project sistem publik yang menghosting jenis tersebut.

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

Mengaktifkan API

Aktifkan 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; file lainnya memperkaya impor dan transformasi akan menurun dengan baik tanpa file 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 kumpulan lengkap file JSON artefak metadata dbt, Anda dapat menjalankan perintah dbt berikut dalam urutan ini:

1. dbt source freshness
2. dbt build

3. dbt docs generate --no-compile

   Peringatan: Tanpa --no-compile, dbt docs generate akan menimpa run_results.json dengan status success untuk setiap node. Hasil pengujian dari dbt build sebelumnya akan hilang dan katalog melaporkan setiap pengujian kualitas data sebagai lulus.

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 dibuat berada. Ini dapat berupa jalur direktori lokal di mesin 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 penahapan impor Knowledge Catalog): Awalan URI bucket Cloud Storage (seperti gs://my-staging-bucket/dbt-imports/) tempat perintah gcloud mengupload file impor metadata yang 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.

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, Anda dapat menggunakan perintah gcloud alpha dataplex dbt metadata-jobs create untuk:

1. Membaca artefak input: Membaca artefak JSON yang dibuat oleh dbt Core dan MetricFlow dari lokasi input (direktori lokal atau URI Cloud Storage yang ditentukan di --artifacts-path).
2. Mengubah metadata: Mengubah konten ke format impor metadata Knowledge Catalog (dbt_metadata.jsonl).
3. Mengupload ke penahapan: Mengupload file impor metadata yang diubah ke lokasi Cloud Storage penahapan 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 ditahapkan dari --storage-uri ke resource Knowledge Catalog.

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 penahapan 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: (Output/Penahapan) Awalan Cloud Storage URI (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 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 default-nya adalah .. Jika URI Cloud Storage diberikan, pemanggil harus memiliki akses baca (roles/storage.objectViewer atau roles/storage.objectAdmin) ke bucket input.
   • --async: Langsung kembali, 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-nya adalah dbt-metadata-ingestion).
   • --aspects-only: Hanya perbarui metadata yang diamati oleh dbt ini dan biarkan bagian 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 akan mempertahankan nilai yang diberikan oleh proses sebelumnya. Gunakan ini untuk penyerapan rutin dan berulang. Lihat Menjalankan ulang penyerapan.
   • --validate-only: Buat dan upload JSON serta validasi tugas metadata, tetapi jangan benar-benar menyerap.

4. Pastikan Anda menerima status Dibuat.

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

Menjalankan ulang penyerapan

Setelah impor pertama, sebagian besar proses hanya perlu memperbarui metadata untuk resource yang sudah ada. Gunakan --aspects-only untuk proses tersebut. Tindakan ini hanya memperbarui apa yang diamati oleh proses 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 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.

Proses penuh akan menulis ulang aspek yang diperlukan setiap entri dari artefak di disk, jadi eksekusi dari kumpulan artefak selengkap mungkin yang dapat dihasilkan oleh pipeline Anda.

Jalankan --aspects-only untuk pembaruan rutin:

• Setelah perintah dbt mana pun yang dijalankan oleh pipeline Anda: dbt build, dbt test, dbt source freshness, atau pembuatan ulang yang dipersempit dengan --select.
• Kolom ditambahkan, dihapus, diketik ulang, atau dideskripsikan ulang.
• SQL model diubah 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

1. DI Google Cloud konsol, buka halaman Knowledge Catalog Search.

   Buka Penelusuran

2. Di panel Filters, Anda dapat memfilter aset dbt menggunakan bagian Project, System, dan Type aliases. Di bagian System, pilih Imported Context. Memilih filter ini akan membuka sub-bagian Managed Connectors. Pilih dbt untuk memfilter semua metadata dbt.

3. Anda dapat menggunakan kolom penelusuran untuk melakukan kueri penelusuran. Anda dapat melakukan penelusuran kata kunci atau bahasa alami. Misalnya, untuk melihat semua aset dbt melalui penelusuran kata kunci, masukkan system=DBT.

   Untuk mempelajari lebih lanjut cara menelusuri resource, lihat Menelusuri resource di Knowledge Catalog. Untuk mempelajari lebih lanjut ekspresi yang dapat Anda gunakan di kolom penelusuran, lihat Sintaksis penelusuran untuk Knowledge Catalog.

4. Anda juga dapat menggunakan LookupContext API untuk mengambil konteks LLM untuk resource dbt tertentu.

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 dapat melebihi batas ukuran per aspek, sehingga skema yang bertingkat dalam mungkin kehilangan kolom akhir.
• --aspects-only dapat menambahkan dan memperbarui metadata, tetapi tidak dapat menghapusnya. Menghapus resource dbt memerlukan proses penuh.
• Link entri tidak didukung.
• Integrasi ini hanya mendukung peristiwa silsilah dbt pada resource BigQuery di Data Lineage API dan grafik. Entri dbt (sumber, seed, model) untuk sumber 3P eksternal tidak diambil dalam silsilah data.
  • Untuk menyerap semua peristiwa silsilah dbt di Data Lineage API, gunakan integrasi dbt OpenLineage. Kemudian, integrasikan OpenLineage dengan Knowledge Catalog untuk mengimpor dan memvisualisasikan data silsilah dari dbt.

Langkah berikutnya

• Pelajari cara Mengelola tugas konektor.