Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Mengelola metadata dan silsilah data Dataform dengan Knowledge Catalog

Dokumen ini menjelaskan cara menggunakan Knowledge Catalog untuk melihat metadata repositori Dataform, memberi anotasi pada repositori dengan aspek, dan melacak silsilah data untuk eksekusi alur kerja Dataform.

Knowledge Catalog memungkinkan Anda menyimpan dan mengelola metadata. Repositori Dataform tersedia di Knowledge Catalog secara default, tanpa konfigurasi tambahan. Knowledge Catalog otomatis mengambil metadata berikut dari repositori Dataform:

Nama aset data
Induk aset data
Lokasi aset data
Jenis aset data
Project Google Cloud terkait
Sumber repositori pihak ketiga
Akun layanan

Sebelum memulai

Di konsol Google Cloud , pada halaman pemilih project, pilih atau buat project Google Cloud .
Peran yang diperlukan untuk memilih atau membuat project
- Memilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project apa pun yang perannya telah diberikan kepada Anda.
- Membuat project: Untuk membuat project, Anda memerlukan peran Project Creator (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.
Catatan: Jika tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang akan menghapus semua resource yang terkait dengan project ini.

Buka pemilih project
Aktifkan Dataplex API dan Data Lineage API, jika belum diaktifkan.
Peran yang diperlukan untuk mengaktifkan API
Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.
Aktifkan API
Pastikan Anda memiliki izin Identity and Access Management (IAM) yang diperlukan.

Peran yang diperlukan

Untuk mengelola repositori Dataform dan melihat silsilah data di Knowledge Catalog, Anda memerlukan peran Dataform yang telah ditetapkan yang memberi Anda akses ke resource Dataform, dan peran Knowledge Catalog yang diperlukan.

Tabel berikut mencantumkan peran yang diperlukan setiap akun utama untuk mencatat dan melihat silsilah data Dataform:

Tugas	Utama	Peran yang diperlukan	Tempat untuk memberikan peran
Mencatat silsilah dari pemanggilan alur kerja	Akun layanan kustom repositori, konfigurasi rilis, atau konfigurasi alur kerja. Jika tidak ada akun layanan kustom yang ditetapkan, Agen layanan Dataform (`service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com`).	Data Lineage Events Producer (`roles/datalineage.producer`)	Project yang berisi repositori
Mencatat silsilah dari Dataform CLI	Kredensial Default Aplikasi yang digunakan CLI	Produsen Peristiwa Silsilah Data (`roles/datalineage.producer`)	Project setiap tabel output
Melihat grafik silsilah	Pengguna yang melihat silsilah	Data Lineage Viewer (`roles/datalineage.viewer`)	Project tempat silsilah dicatat dan project tempat Anda melihat silsilah
Membuka Dataform dari grafik silsilah	Pengguna yang melihat silsilah	Dataform Viewer (`roles/dataform.viewer`), atau izin `dataform.repositories.get` dan `dataform.workflowInvocations.get`	Project yang berisi repositori
Melihat detail tabel BigQuery	Pengguna yang melihat silsilah	BigQuery Data Viewer (`roles/bigquery.dataViewer`), atau izin `bigquery.tables.get`	Project yang menyimpan tabel
Melihat detail tugas BigQuery	Pengguna yang melihat silsilah	BigQuery Resource Viewer (`roles/bigquery.resourceViewer`), atau izin `bigquery.jobs.get`	Project yang menjalankan tugas

Peran Data Lineage Events Producer berisi izin datalineage.locations.processOpenLineageMessage, yang diperlukan untuk mencatat silsilah.

Mengelola metadata di Knowledge Catalog

Knowledge Catalog mencatat repositori Dataform sebagai entri dengan nilai entri berikut:

Grup entri sistem: Grup entri sistem untuk repositori Dataform adalah @dataform. Untuk melihat detail entri repositori di Knowledge Catalog, Anda perlu melihat grup entri sistem dataform. Untuk mengetahui petunjuk tentang cara melihat daftar semua entri dalam grup entri, lihat Melihat detail grup entri dalam dokumentasi Knowledge Catalog.
Jenis entri sistem: Jenis entri sistem untuk repositori Dataform adalah dataform-repository. Untuk melihat detail repositori Dataform, Anda perlu melihat jenis entri sistem dataform-repository. Untuk mengetahui petunjuk tentang cara melihat detail jenis entri yang dipilih, lihat Melihat detail jenis entri dalam dokumentasi Knowledge Catalog. Untuk mengetahui petunjuk tentang cara melihat detail entri yang dipilih, lihat Melihat detail entri dalam dokumentasi Knowledge Catalog.

Menelusuri aset

Untuk mengetahui petunjuk tentang cara menelusuri aset data di Knowledge Catalog, lihat Menelusuri aset data di Knowledge Catalog dalam dokumentasi Knowledge Catalog.

Repositori anotasi

Untuk memberikan konteks tambahan ke repositori Dataform di Knowledge Catalog, Anda dapat menganotasi entri Dataform dengan aspek.

Jenis aspek sistem untuk repositori Dataform adalah dataform-repository.

Untuk mengetahui petunjuk tentang cara menganotasi entri dengan aspek, lihat Mengelola aspek dan memperkaya metadata dalam dokumentasi Knowledge Catalog.

Melacak silsilah data di Knowledge Catalog

Dataform melaporkan silsilah data ke Knowledge Catalog untuk tindakan yang dijalankannya di alur kerja Dataform dan pipeline BigQuery. Untuk setiap tindakan yang dijalankan, grafik silsilah di Knowledge Catalog dan BigQuery menampilkan proses Dataform antara tabel yang dibaca tindakan dan tabel yang ditulisnya. Anda tidak perlu mengubah file SQLX untuk melaporkan silsilah.

Anda dapat menggunakan silsilah data Dataform untuk tugas berikut:

Analisis dampak: identifikasi setiap tindakan dan tabel downstream sebelum Anda mengubah tabel.
Analisis akar masalah: melacak data yang salah kembali ke tindakan dan pemanggilan alur kerja yang menulisnya.
Tata kelola: menunjukkan cara data mengalir di seluruh project dan pipeline mana yang memindahkan data.
Silsilah end-to-end: lihat silsilah Dataform dalam satu grafik bersama dengan silsilah dari BigQuery, Managed Service untuk Apache Airflow, Managed Service untuk Apache Spark, dan Dataflow.

Cara kerja silsilah data

Dataform mengirimkan peristiwa OpenLineage START ke Data Lineage API saat tindakan dimulai. Saat tindakan berakhir, Dataform akan mengirim peristiwa COMPLETE, FAIL, atau ABORT. Setiap tindakan Dataform muncul di Knowledge Catalog sebagai proses dengan jenis sumber BIGQUERY_PIPELINES, dan setiap eksekusi tindakan muncul sebagai operasi dari proses tersebut.

Tabel berikut menjelaskan jenis tindakan Dataform yang melaporkan silsilah:

Jenis tindakan	Silsilah laporan
Tabel, tampilan, tabel inkremental, tampilan terwujud, pernyataan, grafik properti, persiapan data, dan operasi dengan `hasOutput: true`	Ya. Melaporkan link silsilah proses, operasi, dan tabel ke tabel.
Operasi tanpa `hasOutput: true`	Hanya proses dan jalankan. Input dan output kosong, sehingga tidak ada link silsilah tabel ke tabel yang dibuat.
Pernyataan	Tidak. Deklarasi hanya muncul sebagai input untuk tindakan lain.
Notebook, pengujian unit SQL	Tidak

Pelaporan silsilah tidak pernah menyebabkan pemanggilan alur kerja gagal. Jika Data Lineage API dinonaktifkan, izin tidak ada, atau kuota terlampaui, Dataform akan melewati pelaporan silsilah dan pemanggilan alur kerja akan berlanjut tanpa perubahan.

Dataform menulis silsilah ke endpoint regional lokasi pemrosesan BigQuery dari setiap tindakan. Jika endpoint regional tidak tersedia, Dataform akan menulis silsilah ke endpoint global.

Cara alur kerja Dataform dipetakan ke silsilah data

Tabel berikut menjelaskan cara entity eksekusi Dataform dipetakan ke model informasi silsilah data Knowledge Catalog:

Objek silsilah data	Setara dengan Dataform
Proses	Tindakan Dataform
Jalankan	Satu eksekusi tindakan dalam pemanggilan alur kerja
Peristiwa silsilah	Link dari tabel input ke tabel output untuk operasi tersebut

Menyiapkan silsilah data

Untuk menyiapkan Dataform agar melaporkan silsilah data, ikuti langkah-langkah berikut:

Aktifkan Data Lineage API (datalineage.googleapis.com) di project yang berisi repositori Dataform dan di project tempat pengguna melihat silsilah.
Dalam project yang berisi repositori, berikan peran Produsen Peristiwa Silsilah Data (roles/datalineage.producer) ke identitas yang menjalankan alur kerja Anda:
- Jika repositori, konfigurasi rilis, atau konfigurasi alur kerja menggunakan akun layanan kustom, berikan peran tersebut ke akun layanan kustom.
- Jika tidak ada akun layanan kustom yang ditetapkan, berikan peran tersebut kepada agen layanan Dataform (service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com).

Pemanggilan alur kerja yang berjalan dengan kredensial pengguna untuk Akun Google tidak melaporkan silsilah.

Mengaktifkan atau menonaktifkan silsilah data

Selama periode peluncuran awal, pelaporan silsilah data bersifat keikutsertaan.

Untuk mengontrol pelaporan silsilah data untuk repositori atau pipeline BigQuery, tetapkan properti lineage.enabled dalam file workflow_settings.yaml:

Di konsol Google Cloud , buka halaman Dataform.

Buka Dataform
Pilih repositori, lalu pilih ruang kerja pengembangan.
Di panel Files, buka file workflow_settings.yaml.
Untuk mengaktifkan pelaporan silsilah data, tambahkan blok lineage berikut:
```
lineage:
  enabled: true
```
Untuk memilih tidak ikut pelaporan silsilah data setelah silsilah diaktifkan secara default, tetapkan enabled ke false:
```
lineage:
  enabled: false
```
Commit dan kirim perubahan Anda ke repositori Anda.

Untuk menghentikan pelaporan silsilah data untuk seluruh project, nonaktifkan Data Lineage API di project. Menonaktifkan API juga akan menghentikan pelaporan silsilah data dari layanan lain dalam project.

Melihat silsilah data

Untuk melihat silsilah data untuk tabel yang dihasilkan oleh tindakan Dataform, ikuti langkah-langkah berikut:

Di konsol Google Cloud , buka halaman BigQuery.

Buka BigQuery
Di panel Explorer, luaskan project dan set data Anda, lalu pilih tabel yang dihasilkan oleh tindakan Dataform.
Klik tab Silsilah.
Untuk melihat tindakan, repositori, dan operasi, pilih node proses Dataform.
Untuk membuka repositori di Dataform, klik Open in Dataform.

Untuk mengetahui informasi selengkapnya tentang cara menjelajahi grafik silsilah, lihat Melihat silsilah data di Knowledge Catalog.

Melaporkan silsilah data dari Dataform CLI

Untuk melaporkan silsilah data dari operasi lokal atau CI Dataform CLI, tetapkan lineage.enabled: true di workflow_settings.yaml, atau jalankan perintah berikut:

dataform run --emit-lineage

Flag --emit-lineage dan --no-emit-lineage mengganti setelan lineage.enabled untuk satu operasi.

Dataform CLI menggunakan Kredensial Default Aplikasi dan mencatat silsilah dalam project setiap tabel output. Di setiap project ini, aktifkan Data Lineage API dan berikan peran Data Lineage Events Producer (roles/datalineage.producer) ke kredensial. CLI menulis pesan silsilah ke stderr dengan awalan [lineage].

Untuk mengetahui informasi selengkapnya tentang cara melaporkan silsilah dari CLI, lihat referensi Dataform CLI di GitHub.

Memecahkan masalah silsilah data

Tabel berikut menjelaskan masalah umum silsilah data dan cara memperbaikinya:

Gejala	Kemungkinan penyebab	Perbaiki
Tab Lineage tidak menampilkan node Dataform.	Data Lineage API dinonaktifkan.	Aktifkan API di project yang berisi repositori dan di project tempat Anda melihat silsilah.
Repositori tidak melaporkan silsilah.	Identitas yang menjalankan alur kerja tidak memiliki peran Data Lineage Events Producer.	Berikan `roles/datalineage.producer` ke akun layanan kustom atau ke agen layanan Dataform.
Pemanggilan alur kerja yang dijalankan dengan kredensial pengguna tidak melaporkan silsilah.	Pelaporan silsilah tidak mendukung kredensial pengguna.	Jalankan alur kerja dengan akun layanan kustom.
Repositori tidak melaporkan silsilah meskipun peran telah diberikan.	Dataform tidak dapat bertindak sebagai akun layanan kustom.	Berikan peran Service Account Token Creator (`roles/iam.serviceAccountTokenCreator`) kepada agen layanan Dataform di akun layanan kustom.
Satu repositori tidak melaporkan silsilah.	Repositori tidak diikutsertakan.	Menghapus `lineage.enabled: false` dari `workflow_settings.yaml`.
Silsilah tidak ada untuk beberapa operasi.	Kuota Data Lineage API terlampaui.	Sebarkan eksekusi alur kerja atau minta kuota yang lebih tinggi.
Eksekusi CLI tidak melaporkan silsilah untuk beberapa tabel.	API tidak diaktifkan atau peran tidak diberikan dalam project tabel output.	Aktifkan API dan berikan peran dalam project tersebut.
Mengklik Open in Dataform akan menampilkan error izin.	Pengguna tidak memiliki akses ke Dataform.	Berikan peran Dataform Viewer (`roles/dataform.viewer`) kepada pengguna.

Setelah error izin atau API pertama dalam pemanggilan alur kerja, Dataform berhenti melaporkan silsilah untuk sisa pemanggilan alur kerja tersebut. Pemanggilan alur kerja berikutnya akan mencoba melaporkan silsilah lagi.

Saat Anda menghubungi dukungan terkait masalah silsilah data, sertakan ID pemanggilan alur kerja, project ID, dan region.

Melihat log silsilah untuk pemanggilan alur kerja

Di Cloud Logging, Dataform menulis entri log silsilah ke log dataform.googleapis.com/lineage_emission. Setiap entri menyertakan kolom workflowInvocationId, actionTarget, dan eventType.

Untuk melihat log silsilah untuk pemanggilan alur kerja, ikuti langkah-langkah berikut:

Di konsol Google Cloud , buka halaman detail pemanggilan alur kerja.
Klik Lihat log.

Logging akan terbuka dengan log yang difilter ke pemanggilan alur kerja oleh jsonPayload.workflowInvocationId.

Kolom outcome di setiap entri log silsilah memiliki salah satu nilai berikut:

SUCCEEDED: Data Lineage API menerima peristiwa. Entri ini memiliki tingkat keparahan DEBUG, dan eventType adalah START, COMPLETE, FAIL, atau ABORT.
SKIPPED: Dataform melewati pelaporan silsilah. Entri ini memiliki tingkat keparahan INFO dan dicatat dalam log satu kali untuk setiap alasan dalam pemanggilan alur kerja. Kolom skipReason adalah API_DISABLED, PERMISSION_DENIED, EUC_UNSUPPORTED, atau AUTHORITY_UNAVAILABLE, dan kolom errorMessage berisi langkah-langkah perbaikan.
FAILED: pelaporan silsilah gagal setelah dicoba lagi. Entri ini memiliki tingkat keparahan WARNING dan menyertakan kolom errorCode dan errorMessage.

Untuk memfilter pelaporan silsilah yang dilewati atau gagal di Logs Explorer, jalankan kueri berikut:

log_id("dataform.googleapis.com/lineage_emission")
jsonPayload.outcome=("SKIPPED" OR "FAILED")

Pesan silsilah data dari Dataform CLI

Dataform CLI menulis pesan silsilah berikut ke stderr:

skip_reason=workflow_opt_out: lineage.enabled ditetapkan ke false.
skip_reason=invocation_override: pelaporan silsilah dinonaktifkan untuk operasi ini dengan --no-emit-lineage atau --emit-lineage=false.
skip_reason=dry_run: uji coba tidak melaporkan silsilah.
skip_reason=api_disabled: Data Lineage API tidak diaktifkan. CLI tidak akan mengirim permintaan silsilah lagi dalam operasi ini.
skip_reason=permission_denied: kredensial tidak memiliki peran Data Lineage Events Producer (roles/datalineage.producer). CLI tidak mengirimkan permintaan silsilah lagi dalam operasi ini.
Failed to emit lineage for action ...: pelaporan silsilah gagal untuk satu tindakan. Pelaporan silsilah untuk tindakan lain akan dilanjutkan.

Batasan

Mengelola repositori Dataform dan melacak silsilah data di Knowledge Catalog tunduk pada batasan berikut:

Hanya entri tingkat repositori dan tingkat alur kerja yang tersedia di Knowledge Catalog. Aset kode tingkat file individual di Dataform, seperti file definisi SQLX, tidak dikatalogkan sebagai entri terpisah.
Dataform hanya melaporkan silsilah tingkat tabel. Silsilah tingkat kolom tidak dilaporkan.
Deklarasi, notebook, dan pengujian unit SQL tidak melaporkan silsilah. Deklarasi hanya muncul sebagai input untuk tindakan lain. Operasi tanpa hasOutput: true hanya melaporkan proses dan operasi, tanpa link silsilah tabel ke tabel.
Pemanggilan alur kerja yang berjalan dengan kredensial pengguna untuk Akun Google tidak melaporkan silsilah. Untuk melaporkan silsilah, gunakan akun layanan kustom.
Pelaporan silsilah data tunduk pada kuota Data Lineage API untuk penulisan per project, identitas, dan region. Pada paket standar, kuotanya adalah sekitar 1.000 tindakan per menit.

Lokasi

Anda dapat menggunakan Knowledge Catalog untuk mengelola repositori Dataform dari semua lokasi Dataform.

Kuota

Pengelolaan repositori Dataform di Knowledge Catalog tunduk pada kuota dan batas Knowledge Catalog.

Harga

Pengelolaan repositori Dataform di Knowledge Catalog tunduk pada harga Knowledge Catalog.

Penyerapan silsilah data ditagih berdasarkan SKU Pemrosesan Premium Knowledge Catalog, dan hanya peristiwa yang menulis link silsilah tabel ke tabel yang ditagih. Penyimpanan silsilah data ditagih berdasarkan SKU penyimpanan metadata. Untuk mengontrol biaya silsilah data, nonaktifkan alur kerja di workflow_settings.yaml atau nonaktifkan Data Lineage API.

Langkah berikutnya

Untuk mempelajari Knowledge Catalog lebih lanjut, lihat Ringkasan Knowledge Catalog dalam dokumentasi Knowledge Catalog.