Dengan menetapkan aturan kualitas data dan profiling otomatis, Anda memperkaya metadata dengan sinyal kepercayaan dan konteks bisnis.
Dengan menggunakan pendekatan Human-in-the-Loop, di mana AI membuat draf aturan awal dan Anda meninjau, menyempurnakan, serta memvalidasinya, Anda dapat dengan cepat menerjemahkan statistik profil ke dalam framework kualitas data.
Tujuan
- Meratakan data BigQuery bertingkat dengan tampilan terwujud untuk mengaktifkan pembuatan profil Knowledge Catalog.
- Jalankan pemindaian profil Knowledge Catalog menggunakan library klien Python.
- Gunakan 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 Google Cloud project dengan penagihan diaktifkan.
Menyiapkan lingkungan Anda
Langkah-langkah berikut menggunakan Cloud Shell, lingkungan command line yang berjalan di cloud.
Di Google Cloud konsol, klik Activate Cloud Shell di toolbar kanan atas. Penyediaan dan koneksi lingkungan memerlukan waktu beberapa saat.
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 contoh 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 dan hasil sampel:
bq --location=us mk --dataset $PROJECT_ID:$DATASET_IDSiapkan contoh data, 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, alat 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 pemrofilan 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 untuk kolom bertingkat, Anda dapat meratakan data menggunakan serangkaian tampilan terwujud. Tindakan ini mengubah setiap kolom bertingkat menjadi kolom tingkat teratas 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
Melihat skema:
jq < bq_schema.json
File bq_schema.json menampilkan struktur yang kompleks.
Meratakan data dengan tampilan terwujud
Saat meratakan data bertingkat, Anda tidak boleh memisahkan beberapa array independen dalam tampilan yang sama. Tindakan ini akan melakukan cross join implisit (produk Cartesian) 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 dalam direktori devrel-demos/data-analytics/programmatic-dq yang menentukan tampilan 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 memprofilkan tiga tampilan terwujud Anda dengan membuat dan menjalankan pemindaian untuk setiap tampilan. Setelah selesai, ringkasan statistik yang kaya akan dihasilkan dan 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 hasil pindaian profil Anda
Anda dapat melihat hasil pemindaian profil baru di konsol Google Cloud .
- Di menu navigasi, buka Knowledge Catalog dan Data profiling & quality di bagian Govern.
- Temukan tiga pemindaian profil Anda yang tercantum, beserta status tugas terbarunya. Klik pemindaian untuk menjelajahi hasil mendetailnya.
Mengekspor hasil pembuatan profil ke JSON
Agar Antigravity CLI dapat membaca pemindaian profil Anda, Anda harus mengekstrak isinya ke file lokal.
Gunakan skrip 2_dq_profile_save.py untuk menemukan pemindaian berhasil terbaru untuk tampilan mv_ga4_user_session_flat, mendownload data profil, dan menyimpannya ke file bernama dq_profile_results.json.
python3 2_dq_profile_save.py
Setelah skrip selesai, skrip akan membuat file dq_profile_results.json di direktori. File ini berisi metadata statistik mendetail yang Anda perlukan untuk membuat aturan kualitas data. Lihat isinya 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 CLI dapat membaca file di direktori saat ini, CLI dapat menggunakan data pemindaian profil baru Anda secara langsung.
Beri agen ini perintah untuk membuat rencana
Pertama, minta agen untuk menganalisis profil statistik dan mengusulkan rencana tindakan. Instruksikan untuk tidak menulis file YAML terlebih dahulu agar berfokus pada analisis dan justifikasi.
Dalam sesi interaktif Antigravity CLI, 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 dihasilkan 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% nilai null dalam sampel satu hari tidak boleh berisi nilai 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 hanya artefak kumpulan 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: Menolak atau mengubah aturan yang menerapkan nilai minimum statis pada tabel transaksional dinamis.
- Alasan: Metrik seperti
- Kelengkapan kategoris (
setExpectation):- Alasan: Data profil hanya mengungkapkan 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 berdasarkan glosarium bisnis resmi atau data referensi Anda, dengan menambahkan nilai valid yang tidak ada dalam sampel (misalnya, menambahkan kode wilayah atau kategori produk yang tidak ada).
Sempurnakan rencana dengan masukan perintah
Memberikan masukan kepada agen dan memberinya perintah akhir untuk membuat kode. Sesuaikan perintah berikut berdasarkan paket yang benar-benar Anda terima dan koreksi yang ingin Anda lakukan.
Perintah ini hanyalah template. Baris pertama adalah tempat Anda menambahkan koreksi spesifik.
Perintah ini memerlukan kepatuhan terhadap spesifikasi DataQualityRule karena Knowledge Catalog memerlukan struktur YAML yang tepat, sehingga mencegah kesalahan 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 menghasilkan 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 pada 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
Untuk menghindari biaya penagihan berulang untuk resource yang Anda buat dalam tutorial ini, hapus resource tersebut.
Menghapus pemindaian Knowledge Catalog
Hapus profil dan pemindaian berkualitas 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 isinya:
deactivate
cd ../../..
rm -rf devrel-demos
Kesimpulan
Selamat, Anda telah membangun alur kerja kualitas data dan pengayaan metadata terprogram secara menyeluruh.
Dengan menyandingkan agen CLI Antigravity dengan Knowledge Catalog, Anda akan membangun fondasi yang dapat diverifikasi untuk pengayaan metadata yang dibantu AI. Pendekatan ini mempercepat pembuatan aturan deklaratif sehingga Pengelola Data dapat berfokus pada validasi Human-in-the-Loop (HITL) dan menyempurnakan aturan terhadap logika bisnis—memastikan katalog data Anda berfungsi sebagai mesin konteks tepercaya untuk penggunaan AI perusahaan.
Langkah berikutnya
- Baca selengkapnya tentang filosofi di balik arsitektur ini di 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 spesifik per bisnis.
- Optimalkan pemindaian Anda dengan filter dan pengambilan sampel untuk mengurangi biaya.
- Otomatiskan infrastruktur Anda dengan menyediakan resource Knowledge Catalog menggunakan 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