Dengan menetapkan aturan pembuatan profil dan kualitas data otomatis, Anda memperkaya metadata dengan sinyal kepercayaan dan konteks bisnis.
Dengan menggunakan pendekatan Human-in-the-Loop, yaitu AI menyusun aturan awal dan Anda meninjau, menyempurnakan, dan memvalidasinya, Anda dapat dengan cepat menerjemahkan statistik profil menjadi framework kualitas data.
Tujuan
- Meratakan data BigQuery bertingkat dengan tampilan terwujud untuk mengaktifkan pembuatan profil Knowledge Catalog.
- Menjalankan pemindaian profil Knowledge Catalog menggunakan library klien Python.
- Menggunakan Antigravity CLI untuk membuat aturan kualitas data berdasarkan statistik profil.
- Validasi dan deploy aturan yang dihasilkan AI sebagai pemindaian kualitas Knowledge Catalog menggunakan proses peninjauan Human-in-the-Loop.
Sebelum memulai
Sebelum memulai, pastikan Anda memiliki project Google Cloud dengan penagihan yang diaktifkan.
Menyiapkan lingkungan Anda
Langkah-langkah berikut menggunakan Cloud Shell, yaitu lingkungan command line yang berjalan di cloud.
Di konsol Google Cloud , klik Activate Cloud Shell di toolbar kanan atas. Lingkungan memerlukan waktu beberapa saat untuk menyediakan dan terhubung.
Di Cloud Shell, siapkan project ID dan variabel lingkungan Anda:
export PROJECT_ID=$(gcloud config get-value project) gcloud config set project $PROJECT_ID export LOCATION="us-central1" export BQ_LOCATION="us" export DATASET_ID="kc_dq_codelab" export TABLE_ID="ga4_transactions"Gunakan
us(multi-region) sebagai lokasi karena data sampel publik juga berada dius(multi-region). Untuk kueri BigQuery, data sumber dan tabel tujuan harus berada di lokasi yang sama.Aktifkan layanan yang diperlukan:
gcloud services enable dataplex.googleapis.com \ bigquery.googleapis.com \ serviceusage.googleapis.com \ aiplatform.googleapis.comBuat set data BigQuery untuk menyimpan data sampel dan hasil:
bq --location=us mk --dataset $PROJECT_ID:$DATASET_IDSiapkan data sampel, yang berasal dari set data e-commerce publik dari Google Merchandise Store.
Perintah
bqberikut membuat tabel baru,ga4_transactions, di set datakc_dq_codelabAnda. Untuk memastikan pemindaian berjalan cepat, kueri ini hanya menyalin data dari satu hari (31-01-2021).bq query \ --use_legacy_sql=false \ --destination_table=$PROJECT_ID:$DATASET_ID.$TABLE_ID \ --replace=true \ 'SELECT * FROM `bigquery-public-data.ga4_obfuscated_sample_ecommerce.events_20210131`'Clone repositori GitHub yang berisi struktur folder dan file pendukung untuk tutorial ini:
# Perform a shallow clone to get only the latest repository structure without the full history git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git cd devrel-demos # Specify and download only the folder we need for this lab git sparse-checkout set data-analytics/programmatic-dq cd data-analytics/programmatic-dqDirektori ini adalah area kerja aktif Anda.
Membuat profil data bertingkat
Dengan pembuatan profil data, Knowledge Catalog menemukan statistik untuk kolom tingkat teratas, seperti persentase null, keunikan, dan distribusi nilai dalam data Anda untuk membantu Anda memahaminya.
Untuk mendapatkan statistik kolom bertingkat, Anda dapat meratakan data menggunakan kumpulan tampilan terwujud. Tindakan ini akan mengubah setiap kolom bertingkat menjadi kolom tingkat atas yang dapat diprofilkan oleh Knowledge Catalog.
Mendapatkan skema bertingkat
Dapatkan skema lengkap tabel sumber Anda, termasuk semua struktur bertingkat, dan simpan output sebagai file JSON:
bq show --schema --format=json $PROJECT_ID:$DATASET_ID.$TABLE_ID > bq_schema.json
Lihat skema:
jq < bq_schema.json
File bq_schema.json mengungkapkan struktur yang kompleks.
Meratakan data dengan tampilan terwujud
Saat Anda meratakan data bertingkat, penting untuk tidak membatalkan penyusunan bertingkat beberapa array independen dalam tampilan yang sama. Tindakan ini akan melakukan cross join implisit (Cartesian product) di antara array, yang akan mengalikan baris secara tidak benar dan merusak data Anda.
Sebaiknya buat beberapa tampilan, yang masing-masing dibuat untuk tujuan tertentu. Setiap tampilan harus mempertahankan satu tingkat detail yang jelas. Pada langkah ini, Anda akan membuat tampilan terwujud berikut:
- Tampilan datar sesi (
mv_ga4_user_session_flat.sql): satu baris per peristiwa. - Tampilan transaksi (
mv_ga4_ecommerce_transactions.sql): satu baris per transaksi. - Tampilan item (
mv_ga4_ecommerce_items.sql): satu baris per item.
Repositori project menyediakan tiga file SQL di direktori devrel-demos/data-analytics/programmatic-dq yang menentukan tabel virtual ini.
Jalankan file ini dari Cloud Shell menggunakan perintah BigQuery berikut.
envsubst < mv_ga4_user_session_flat.sql | bq query --use_legacy_sql=false
envsubst < mv_ga4_ecommerce_transactions.sql | bq query --use_legacy_sql=false
envsubst < mv_ga4_ecommerce_items.sql | bq query --use_legacy_sql=false
Menjalankan pemindaian profil dengan klien Python
Sekarang Anda dapat membuat dan menjalankan pemindaian profil data Knowledge Catalog untuk setiap tampilan terwujud. Skrip Python berikut menggunakan library klien google-cloud-dataplex untuk mengotomatiskan proses ini.
Sebelum menjalankan skrip, buat lingkungan virtual Python yang terisolasi di direktori project Anda.
# Create the virtual environment
python3 -m venv dq_venv
# Activate the environment
source dq_venv/bin/activate
Instal library klien Knowledge Catalog di dalam lingkungan virtual.
# Install the Knowledge Catalog client library
pip install google-cloud-dataplex
Setelah menyiapkan lingkungan dan menginstal library, Anda siap menggunakan skrip 1_run_scan.py. Skrip ini membuat profil tiga tampilan terwujud Anda dengan membuat dan menjalankan pemindaian untuk setiap tampilan. Setelah selesai, tugas ini akan menghasilkan ringkasan statistik lengkap yang akan Anda gunakan pada langkah berikutnya untuk membuat aturan kualitas data yang didukung AI.
Jalankan skrip dari terminal Cloud Shell Anda.
python3 1_run_scan.py
Memeriksa pemindaian profil Anda
Anda dapat melihat pemindaian profil baru di konsol Google Cloud .
- Di menu navigasi, buka Knowledge Catalog dan Data profiling & quality di bagian Govern.
- Temukan tiga pemindaian profil yang tercantum, beserta status tugas terbarunya. Klik pemindaian untuk mempelajari hasil mendetailnya.
Mengekspor hasil profil ke JSON
Agar Antigravity CLI dapat membaca pemindaian profil, Anda harus mengekstrak kontennya ke dalam file lokal.
Gunakan skrip 2_dq_profile_save.py untuk menemukan pemindaian terbaru yang berhasil untuk tampilan mv_ga4_user_session_flat, download data profil, dan simpan ke file bernama dq_profile_results.json.
python3 2_dq_profile_save.py
Setelah selesai, skrip akan membuat file dq_profile_results.json di direktori. File ini menyimpan metadata statistik mendetail yang Anda perlukan untuk membuat aturan kualitas data. Lihat kontennya dengan menjalankan perintah berikut:
cat dq_profile_results.json
Membuat aturan kualitas data dengan Antigravity CLI
Sekarang Anda dapat menggunakan Antigravity CLI untuk membaca hasil pemindaian profil lokal.
Menulis spesifikasi kualitas data secara manual untuk set data yang kompleks akan memakan waktu dan rentan terhadap error. Penggunaan agen AI generatif mempercepat alur kerja ini dengan membuat draf konfigurasi deklaratif awal dalam hitungan detik. Hal ini memungkinkan tim data beralih dari penyusunan sintaksis manual ke pengawasan Human-in-the-Loop (HITL) tingkat tinggi yang selaras dengan bisnis.
Untuk memulai Antigravity CLI, gunakan perintah berikut:
agy
Sekarang Anda siap membuat aturan kualitas. Karena dapat membaca file di direktori Anda saat ini, CLI dapat langsung menggunakan data pemindaian profil baru Anda.
Beri agen ini perintah untuk membuat rencana
Pertama, minta agen untuk menganalisis profil statistik dan mengusulkan rencana tindakan. Perintahkan untuk tidak menulis file YAML terlebih dahulu agar Gemini dapat berfokus pada analisis dan justifikasi.
Dalam sesi Antigravity CLI interaktif, masukkan perintah terstruktur berikut:
# Context
You are preparing a data quality rule configuration plan for Google Cloud Knowledge Catalog based on data profile statistics.
# Input
- File Path: `./dq_profile_results.json` (contains metrics like null percentage, distinct counts, and distributions)
# Task
Analyze the input statistics and propose a step-by-step plan for establishing automated data quality rules.
*Do not write any YAML code in this step.* Focus only on analytical planning.
# Rule Mapping Strategy
For candidate columns, match the statistical metrics to the most appropriate expectations:
- `nonNullExpectation`: Propose for columns with 0% null values in the profile.
- `setExpectation`: Propose for columns with a highly limited, stable set of categorical values.
- `rangeExpectation`: Propose for numeric columns with consistent and predictable value boundaries.
# Guidelines
- Provide a metric-based justification for each proposed rule (for example, "Recommend nonNullExpectation for column 'user_pseudo_id' because its null percentage is 0%").
- Flag volatile metrics such as hardcoded row counts that could cause false-positive alerts in production.
# Output Format
Provide your analysis and proposed rules as a structured, step-by-step markdown plan with clear headings.
Agen akan menganalisis file JSON dan menampilkan rencana terstruktur seperti berikut:
Automated Data Quality Rule Configuration Plan
Google Cloud Knowledge Catalog (Dataplex Data Quality)
──────
## Executive Summary
This analytical planning document outlines a step-by-step strategy for
configuring automated data quality (DQ) rules in Google Cloud
Knowledge Catalog (formerly Dataplex Data Quality) based on profiling
statistics.
The dataset contains 26,489 rows representing GA4 event logs. Based on
statistical metrics (null ratios, distinct value distributions, and data
types), candidate columns are mapped to appropriate expectation rules.
──────
## 1. Data Profile Overview & Statistical Highlights
Column Name │ Data Type │ Null Ratio │ Distinct Count │ Key Value Range / Categories
─────────────────┼───────────┼────────────────┼────────────────┼──────────────────────────────────────────────────
event_date │ STRING │ 0.0% (0) │ 1 (3.78e-05) │ "20210131" (100%)
event_timestamp │ INTEGER │ 0.0% (0) │ ~16,539 (0.62) │ Min: 1612051200657906, Max: 1612137595412363
event_name │ STRING │ 0.0% (0) │ 16 (0.0006) │ page_view (35.8%), user_engagement (18.9%), etc.
user_pseudo_id │ STRING │ 0.0% (0) │ ~2,545 (0.09) │ 18-21 characters string identifiers
user_id │ STRING │ 100.0% (1.0) │ 0 (0.0) │ Entirely NULL
device_category │ STRING │ 0.0% (0) │ 3 (0.0001) │ desktop (57.5%), mobile (40.1%), tablet (2.4%)
... │ ... │ ... │ ... │ ...
──────
## 2. Rule Mapping Strategy & Analytical Justifications
### Step 1: Nullability Rules (nonNullExpectation)
Propose nonNullExpectation for mandatory columns where the data profile
demonstrates 0% null values.
• user_pseudo_id, event_timestamp, event_name, event_date, stream_id,
platform, device_category (Metric Justification: nullRatio is 0.0%)
│ [!NOTE] Exclusions:
│ • user_id: Has a nullRatio of 100.0% (unauthenticated traffic).
│ • device_language: Has a nullRatio of 37.53%.
──────
### Step 2: Categorical Value Set Validation (setExpectation)
Propose setExpectation for columns with a highly limited, stable set of
categorical domain values.
• device_category: Distinct count is exactly 3. Allowed set:
['desktop', 'mobile', 'tablet']
• platform: Distinct count is 1. Allowed set expanded to:
['WEB', 'ANDROID', 'IOS'] to avoid over-fitting.
• geo_continent: Distinct count is 6. Allowed set:
['Americas', 'Asia', 'Europe', 'Africa', 'Oceania', 'Antarctica', '(not set)']
──────
### Step 3: Numeric & Timestamp Boundary Validation (rangeExpectation)
Propose rangeExpectation for numeric columns with consistent and predictable
value boundaries.
• event_timestamp: rangeExpectation requiring event_timestamp > 0 (avoid
dynamic microsecond range hardcoding)
• stream_id: rangeExpectation requiring positive integer stream IDs
(stream_id > 0)
──────
## 3. Risk Warning: Volatile Metrics & Production False Positives
│ [!WARNING] Volatile Metrics Flagged for Risk Mitigation:
1. Hardcoded Total Row Count (rowCount = 26,489) -> Daily event volume
fluctuates. Use dynamic volume thresholds.
2. Hardcoded Partition Date (event_date = '20210131') -> Breaks on future
runs. Validate against YYYYMMDD regex patterns.
3. Exact Timestamp Range Bounds -> Enforcing these microsecond limits on
incoming live pipelines will reject all future data.
4. Single-Value Domain Restrictions -> Single profile sample might lack
active streams. Set sets according to enterprise schema.
──────
## Summary Table of Proposed Rules
Target Column │ Rule Type │ Metric-Based Justification │ Operational Considerations
─────────────────┼────────────────────┼────────────────────────────┼──────────────────────────────────────────────────
user_pseudo_id │ nonNullExpectation │ Null Ratio: 0.0% │ Core identifier, strictly required
event_timestamp │ nonNullExpectation │ Null Ratio: 0.0% │ Temporal key, strictly required
event_timestamp │ rangeExpectation │ Min: > 0 (Microseconds) │ Avoid hardcoding epoch min/max
event_name │ nonNullExpectation │ Null Ratio: 0.0% │ Required event taxonomy key
event_name │ setExpectation │ Categorical distribution │ Map to standard GA4 event taxonomy
device_category │ nonNullExpectation │ Null Ratio: 0.0% │ Required form-factor dimension
device_category │ setExpectation │ Distinct Count: 3 values │ ['desktop', 'mobile', 'tablet']
... │ ... │ ... │ ...
Membuat aturan kualitas data
Ini adalah langkah paling penting dalam seluruh alur kerja: peninjauan Human-in-the-Loop (HITL). Rencana yang dibuat agen murni didasarkan pada pola statistik dalam data. Agen tidak memahami konteks bisnis Anda, perubahan data di masa mendatang, atau maksud spesifik di balik data Anda. Peran Anda sebagai pakar manusia adalah memvalidasi, mengoreksi, dan menyetujui rencana ini sebelum mengubahnya menjadi kode.
Yang perlu divalidasi selama peninjauan HITL
Periksa rencana yang diusulkan agen berdasarkan kriteria bisnis inti berikut:
- Anomali statistik vs. realitas bisnis:
- Alasan: Agen AI mungkin mengasumsikan bahwa kolom dengan 0% null dalam sampel satu hari tidak boleh berisi null, atau menetapkan rentang numerik yang ketat berdasarkan distribusi historis yang terbatas.
- Tindakan: Verifikasi apakah batas yang disarankan (seperti
rangeExpectationataunonNullExpectation) mencerminkan batasan bisnis yang sebenarnya atau sekadar artefak set sampel.
- Metrik yang tidak stabil (seperti jumlah baris):
- Alasan: Metrik seperti
rowCountatau pertumbuhan tabel bervariasi setiap hari di lingkungan perusahaan yang aktif. Aturan statis akan menyebabkan pemberitahuan positif palsu. - Tindakan: Tolak atau ubah aturan yang menerapkan nilai minimum statis pada tabel transaksional dinamis.
- Alasan: Metrik seperti
- Kelengkapan kategoris (
setExpectation):- Alasan: Data profil hanya menampilkan nilai yang ada di jendela sampel yang dipindai. Model ini tidak dapat memprediksi kategori valid yang tidak terjadi selama jangka waktu tersebut.
- Tindakan: Periksa daftar kategoris terhadap glosarium bisnis resmi atau data referensi Anda, tambahkan nilai valid yang dihilangkan dari sampel (misalnya, menambahkan kode wilayah atau kategori produk yang tidak ada).
Menyempurnakan rencana dengan masukan perintah
Berikan masukan kepada agen dan berikan perintah akhir untuk membuat kode. Sesuaikan perintah berikut berdasarkan rencana yang Anda terima dan koreksi yang ingin Anda buat.
Perintah ini hanyalah template. Baris pertama adalah tempat Anda menambahkan koreksi spesifik.
Perintah ini memerlukan kesesuaian dengan spesifikasi DataQualityRule karena
Knowledge Catalog memerlukan struktur YAML yang tepat, sehingga mencegah error
sintaksis atau versi skema yang sudah tidak berlaku.
# Feedback & Approvals
[YOUR CORRECTIONS AND APPROVAL GO HERE. Examples:
- "The plan looks good. Please proceed."
- "The rowCount rule is not necessary, as the table size changes daily. The rest of the plan is approved. Please proceed."
- "For the setExpectation on the geo_continent column, please also include 'Antarctica'."]
# Objective
Based on the approved analysis plan and the provided feedback, generate the final `dq_rules.yaml` file conforming to the standard `DataQualityRule` schema.
# Instructions
1. **Rule Justifications**: For every generated rule, add a YAML comment (`#`) on the line directly above it, briefly explaining the justification established in the plan.
2. **Schema Alignment**: Ensure the structure strictly adheres to the required Knowledge Catalog data quality scan specification. Refer to the `sample_rule.yaml` file in the current directory and the `DataQualityRule` class definition as the schema authority. Search for the `data_quality.py` file inside the `./dq_venv/lib/` directory to read this class definition.
3. **Data-Driven Values**: Derive all rule parameters, such as thresholds or expected values, directly from the statistical metrics in `dq_profile_results.json`.
# Constraints
- **Output Purity**: Return ONLY the raw, valid, and properly formatted YAML code block.
- Do not include conversational preambles, introductory sentences, explanations, or markdown blocks around the YAML.
Agen kini akan membuat file YAML bernama dq_rules.yaml di direktori kerja Anda, berdasarkan petunjuk yang telah divalidasi.
Membuat dan menjalankan pemindaian kualitas data
Sekarang Anda memiliki kumpulan aturan kualitas data yang dibuat oleh agen dan divalidasi oleh manusia, yang dapat Anda daftarkan dan deploy sebagai pemindaian.
Keluar dari Antigravity CLI dengan memasukkan
/quitatau menekanCtrl+Cdua kali.Kemudian, buat pemindaian data di Knowledge Catalog:
export DQ_SCAN="dq-scan" gcloud dataplex datascans create data-quality $DQ_SCAN \ --project=$PROJECT_ID \ --location=$LOCATION \ --data-quality-spec-file=dq_rules.yaml \ --data-source-resource="//bigquery.googleapis.com/projects/$PROJECT_ID/datasets/$DATASET_ID/tables/mv_ga4_user_session_flat"Jalankan pemindaian:
gcloud dataplex datascans run $DQ_SCAN --location=$LOCATION --project=$PROJECT_IDPerintah ini akan membuat pemindaian kualitas data bernama
dq-scan.Periksa progres pemindaian Anda di bagian Knowledge Catalog di konsol Google Cloud .
- Di menu navigasi, buka Knowledge Catalog dan Data profiling & quality di bagian Govern.
- Temukan
dq-scan. Setelah pemindaian selesai, klik pemindaian untuk melihat hasilnya.
Pembersihan
Agar tidak dikenai biaya penagihan berulang untuk resource yang Anda buat dalam tutorial ini, hapus resource tersebut.
Menghapus pemindaian Knowledge Catalog
Hapus profil dan pemindaian kualitas Anda menggunakan nama pemindaian tertentu dari codelab ini:
# Delete the Data Quality Scan
gcloud dataplex datascans delete dq-scan \
--location=us-central1 \
--project=$PROJECT_ID --quiet
# Delete the Data Profile Scans
gcloud dataplex datascans delete profile-scan-mv-ga4-user-session-flat \
--location=us-central1 \
--project=$PROJECT_ID --quiet
gcloud dataplex datascans delete profile-scan-mv-ga4-ecommerce-transactions \
--location=us-central1 \
--project=$PROJECT_ID --quiet
gcloud dataplex datascans delete profile-scan-mv-ga4-ecommerce-items \
--location=us-central1 \
--project=$PROJECT_ID --quiet
Menghapus set data sampel
Hapus set data BigQuery sementara dan tabelnya.
bq rm -r -f --dataset $PROJECT_ID:kc_dq_codelab
Menghapus file lokal
Nonaktifkan lingkungan virtual Python dan hapus repositori yang di-clone beserta kontennya:
deactivate
cd ../../..
rm -rf devrel-demos
Kesimpulan
Selamat, Anda telah membangun alur kerja pengayaan metadata dan kualitas data terprogram secara menyeluruh.
Dengan menyambungkan agen Antigravity CLI dengan Knowledge Catalog, Anda akan membangun fondasi yang dapat diverifikasi untuk pengayaan metadata yang dibantu AI. Pendekatan ini mempercepat pembuatan aturan deklaratif sehingga Data Steward dapat berfokus pada validasi Human-in-the-Loop (HITL) dan menyempurnakan aturan terhadap logika bisnis—memastikan Data Catalog Anda berfungsi sebagai mesin konteks tepercaya untuk konsumsi AI perusahaan.
Langkah berikutnya
- Baca selengkapnya filosofi di balik arsitektur ini dalam Tata Kelola yang Dibantu AI: Mempercepat Kualitas Data dengan Pengawasan Manusia.
- Kelola kualitas data sebagai kode dengan membuat pipeline CI/CD.
- Pelajari penggunaan aturan SQL kustom untuk menerapkan logika khusus bisnis.
- Optimalkan pemindaian Anda dengan filter dan pengambilan sampel untuk mengurangi biaya.
- Otomatiskan infrastruktur Anda dengan menyediakan resource Knowledge Catalog dengan Terraform untuk mengelola spesifikasi kualitas data dan pengayaan metadata dalam skala besar.
- Pelajari lebih lanjut menggunakan panduan memulai Antigravity CLI.
- Coba kasus penggunaan Knowledge Catalog lainnya.