1. Pengantar
Codelab ini memberikan cetak biru teknis untuk praktisi data. Dokumen ini menguraikan pendekatan "code-first" untuk tata kelola data, yang menunjukkan cara menyematkan pengelolaan metadata dan kualitas yang andal langsung ke dalam siklus proses pengembangan. Pada intinya, Knowledge Catalog berfungsi sebagai data fabric cerdas, yang memungkinkan organisasi mengelola, memantau, dan mengatur data secara terpusat di seluruh aset mereka, dari data lake hingga data warehouse.
Codelab ini menunjukkan cara memanfaatkan Knowledge Catalog, BigQuery, dan Antigravity CLI untuk meratakan data yang kompleks, membuat profilnya secara terprogram, membuat saran aturan kualitas data yang cerdas, dan men-deploy pemindaian kualitas otomatis. Tujuan utamanya adalah untuk melampaui proses manual yang didorong UI, yang rentan terhadap error dan sulit diskalakan, dan sebagai gantinya, membuat framework "kebijakan sebagai kode" yang tangguh dan dapat dikontrol versinya.
Yang akan Anda pelajari
- Cara meratakan data BigQuery bertingkat menggunakan Tampilan Terwujud untuk mengaktifkan pembuatan profil yang komprehensif.
- Cara memicu dan mengelola pemindaian profil Knowledge Catalog secara terprogram menggunakan Library Klien Python Knowledge Catalog.
- Cara mengekspor data profil dan menyusunnya sebagai input untuk model AI generatif.
- Cara membuat perintah untuk Antigravity CLI guna menganalisis data profil dan menghasilkan file aturan YAML yang kompatibel dengan Knowledge Catalog.
- Pentingnya proses interaktif human-in-the-loop (HITL) untuk memvalidasi konfigurasi yang dihasilkan AI.
- Cara men-deploy aturan yang dihasilkan sebagai pemindaian kualitas data otomatis.
Yang Anda butuhkan
- Akun Google Cloud dan Project Google Cloud
- Browser web seperti Chrome
Konsep utama: pilar kualitas data Knowledge Catalog
Memahami komponen inti Knowledge Catalog sangat penting untuk membangun strategi kualitas data yang efektif.
- Pemindaian Profil Data: Tugas Knowledge Catalog yang menganalisis data dan menghasilkan metadata statistik, termasuk persentase null, jumlah nilai unik, dan distribusi nilai. Hal ini berfungsi sebagai fase "penemuan" terprogram kami.
- Aturan Kualitas Data: Pernyataan deklaratif yang menentukan kondisi yang harus dipenuhi data Anda (misalnya,
NonNullExpectation,SetExpectation,RangeExpectation). - AI Generatif untuk Saran Aturan: Menggunakan model bahasa besar (seperti Gemini) untuk menganalisis profil data dan menyarankan aturan kualitas data yang relevan. Hal ini mempercepat proses penentuan kerangka kerja kualitas dasar.
- Pemindaian Kualitas Data: Tugas Knowledge Catalog yang memvalidasi data terhadap serangkaian aturan kustom atau yang telah ditentukan sebelumnya.
- Tata Kelola Terprogram: Tema utama pengelolaan kontrol tata kelola (seperti aturan kualitas) sebagai kode (misalnya, dalam file YAML dan skrip Python). Hal ini memungkinkan otomatisasi, pembuatan versi, dan integrasi ke dalam pipeline CI/CD.
- Human-in-the-Loop (HITL): Titik kontrol penting untuk mengintegrasikan keahlian dan pengawasan manusia ke dalam alur kerja otomatis. Untuk konfigurasi yang dibuat AI, HITL sangat penting untuk memvalidasi kebenaran, relevansi bisnis, dan keamanan saran sebelum di-deploy.
2. Penyiapan dan persyaratan
Mulai Cloud Shell
Meskipun Google Cloud dapat dioperasikan dari jarak jauh menggunakan laptop Anda, dalam codelab ini, Anda akan menggunakan Google Cloud Shell, lingkungan command line yang berjalan di Cloud.
Dari Google Cloud Console, klik ikon Cloud Shell di toolbar kanan atas:
Hanya perlu waktu beberapa saat untuk penyediaan dan terhubung ke lingkungan. Jika sudah selesai, Anda akan melihat tampilan seperti ini:
Mesin virtual ini berisi semua alat pengembangan yang Anda perlukan. Layanan ini menawarkan direktori beranda tetap sebesar 5 GB dan beroperasi di Google Cloud, sehingga sangat meningkatkan performa dan autentikasi jaringan. Semua pekerjaan Anda dalam codelab ini dapat dilakukan di browser. Anda tidak perlu menginstal apa pun.
Aktifkan API yang diperlukan dan konfigurasi lingkungan
Di dalam Cloud Shell, pastikan project ID Anda sudah disiapkan:
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"
gcloud services enable dataplex.googleapis.com \
bigquery.googleapis.com \
serviceusage.googleapis.com \
aiplatform.googleapis.com
Dalam contoh ini, kita menggunakan us (multi-region) sebagai lokasi karena data contoh publik yang akan kita gunakan juga berada di us (multi-region). BigQuery mewajibkan data sumber dan tabel tujuan untuk kueri berada di lokasi yang sama.
Buat set data BigQuery khusus
Buat set data BigQuery baru untuk menampung data dan hasil sampel kita.
bq --location=us mk --dataset $PROJECT_ID:$DATASET_ID
Menyiapkan data sampel
Untuk codelab ini, Anda akan menggunakan set data publik yang berisi data e-commerce dengan obfuscation dari Google Merchandise Store. Karena set data publik bersifat hanya baca, Anda harus membuat salinan yang dapat diubah di set data Anda sendiri. Perintah bq berikut membuat tabel baru, ga4_transactions, di set data kc_dq_codelab Anda. Tindakan ini menyalin data dari satu hari (2021-01-31) untuk memastikan pemindaian berjalan dengan cepat.
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`'
Menyiapkan direktori demo
Untuk memulai, Anda akan meng-clone repositori GitHub yang berisi struktur folder dan file pendukung yang diperlukan untuk codelab 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-dq
Direktori ini sekarang menjadi area kerja aktif Anda. Semua file berikutnya akan dibuat di sini.
3. Penemuan data otomatis dengan pembuatan profil Knowledge Catalog
Pembuatan profil data Knowledge Catalog adalah alat canggih untuk otomatis menemukan informasi statistik tentang data Anda, seperti persentase null, keunikan, dan distribusi nilai. Proses ini penting untuk memahami struktur dan kualitas data Anda. Namun, keterbatasan yang diketahui dalam pembuatan profil Knowledge Catalog adalah ketidakmampuannya untuk memeriksa sepenuhnya kolom bertingkat atau berulang (misalnya, jenis RECORD atau ARRAY) dalam tabel. Fitur ini dapat mengidentifikasi bahwa kolom adalah jenis kompleks, tetapi tidak dapat membuat profil masing-masing kolom dalam struktur bertingkat tersebut.
Untuk mengatasinya, kita akan meratakan data ke dalam Tampilan Terwujud yang dibuat khusus. Strategi ini menjadikan setiap kolom sebagai kolom tingkat teratas, sehingga Knowledge Catalog dapat membuat profil setiap kolom secara terpisah.
Memahami skema bertingkat
Pertama, mari kita periksa skema tabel sumber. Set data Google Analytics 4 (GA4) berisi beberapa kolom bertingkat dan berulang. Untuk mengambil skema lengkap secara terprogram, termasuk semua struktur bertingkat, Anda dapat menggunakan perintah bq show dan menyimpan output sebagai file JSON.
bq show --schema --format=json $PROJECT_ID:$DATASET_ID.$TABLE_ID > bq_schema.json
Memeriksa file bq_schema.json akan menampilkan struktur kompleks seperti perangkat, geo, e-commerce, dan item data berulang. Ini adalah struktur yang memerlukan perataan untuk pembuatan profil yang efektif.
Meratakan data dengan Tampilan Terwujud
Membuat Tampilan Material (MV) adalah solusi paling efektif dan praktis untuk tantangan data bertingkat ini. Dengan menghitung terlebih dahulu hasil yang diratakan, MV menawarkan keuntungan signifikan dalam performa dan biaya kueri, sekaligus memberikan struktur yang lebih sederhana dan mirip relasional untuk analis dan alat pembuatan profil.
Pemikiran pertama yang muncul mungkin adalah meratakan semuanya menjadi satu tampilan besar. Namun, pendekatan intuitif ini menyembunyikan jebakan berbahaya yang dapat menyebabkan kerusakan data parah. Mari kita pelajari mengapa hal ini merupakan kesalahan yang sangat fatal.
mv_ga4_user_session_flat.sql
CREATE OR REPLACE MATERIALIZED VIEW `$PROJECT_ID.$DATASET_ID.mv_ga4_user_session_flat`
OPTIONS (
enable_refresh = true,
refresh_interval_minutes = 30
) AS
SELECT
event_date, event_timestamp, event_name, user_pseudo_id, user_id, stream_id, platform,
device.category AS device_category,
device.operating_system AS device_os,
device.operating_system_version AS device_os_version,
device.language AS device_language,
device.web_info.browser AS device_browser,
geo.continent AS geo_continent,
geo.country AS geo_country,
geo.region AS geo_region,
geo.city AS geo_city,
traffic_source.name AS traffic_source_name,
traffic_source.medium AS traffic_source_medium,
traffic_source.source AS traffic_source_source
FROM
`$PROJECT_ID.$DATASET_ID.ga4_transactions`;
mv_ga4_ecommerce_transactions.sql
CREATE OR REPLACE MATERIALIZED VIEW `$PROJECT_ID.$DATASET_ID.mv_ga4_ecommerce_transactions`
OPTIONS (
enable_refresh = true,
refresh_interval_minutes = 30
) AS
SELECT
event_date, event_timestamp, user_pseudo_id, ecommerce.transaction_id,
ecommerce.total_item_quantity,
ecommerce.purchase_revenue_in_usd,
ecommerce.purchase_revenue,
ecommerce.refund_value_in_usd,
ecommerce.refund_value,
ecommerce.shipping_value_in_usd,
ecommerce.shipping_value,
ecommerce.tax_value_in_usd,
ecommerce.tax_value,
ecommerce.unique_items
FROM
`$PROJECT_ID.$DATASET_ID.ga4_transactions`
WHERE
ecommerce.transaction_id IS NOT NULL;
mv_ga4_ecommerce_items.sql
CREATE OR REPLACE MATERIALIZED VIEW `$PROJECT_ID.$DATASET_ID.mv_ga4_ecommerce_items`
OPTIONS (
enable_refresh = true,
refresh_interval_minutes = 30
) AS
SELECT
event_date, event_timestamp, event_name, user_pseudo_id, ecommerce.transaction_id,
item.item_id,
item.item_name,
item.item_brand,
item.item_variant,
item.item_category,
item.item_category2,
item.item_category3,
item.item_category4,
item.item_category5,
item.price_in_usd,
item.price,
item.quantity,
item.item_revenue_in_usd,
item.item_revenue,
item.coupon,
item.affiliation,
item.item_list_name,
item.promotion_name
FROM
`$PROJECT_ID.$DATASET_ID.ga4_transactions`,
UNNEST(items) AS item
WHERE
ecommerce.transaction_id IS NOT NULL;
Sekarang, jalankan template ini menggunakan alat command line bq. Perintah envsubst akan membaca setiap file, mengganti variabel seperti $PROJECT_ID dan $DATASET_ID dengan nilainya dari lingkungan shell Anda, dan menyalurkan SQL akhir yang valid ke perintah kueri bq.
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 melalui klien Python
Setelah memiliki tampilan yang diratakan dan dapat diprofilkan, kita dapat membuat dan menjalankan pemindaian profil data Knowledge Catalog secara terprogram untuk setiap tampilan. Skrip Python berikut menggunakan library klien google-cloud-dataplex untuk mengotomatiskan proses ini.
Sebelum menjalankan skrip, praktik terbaik yang sangat penting adalah membuat lingkungan Python yang terisolasi dalam direktori project Anda. Tindakan ini memastikan bahwa dependensi project dikelola secara terpisah, sehingga mencegah konflik dengan paket lain di lingkungan Cloud Shell Anda.
# Create the virtual environment
python3 -m venv dq_venv
# Activate the environment
source dq_venv/bin/activate
Sekarang, instal library klien Knowledge Catalog di dalam lingkungan yang baru diaktifkan.
# Install the Knowledge Catalog client library
pip install google-cloud-dataplex
Setelah lingkungan disiapkan dan library diinstal, Anda siap membuat skrip orkestrasi.
Di toolbar Cloud Shell, klik Open Editor. Buat file baru bernama 1_run_scan.py dan tempelkan kode Python berikut ke dalamnya. Jika Anda meng-clone repositori GitHub, file ini sudah ada di folder Anda.
Skrip ini akan membuat pemindaian untuk setiap Tampilan Terwujud (jika belum ada), menjalankan pemindaian, lalu melakukan polling hingga semua tugas pemindaian selesai.
import os
import sys
import time
from google.cloud import dataplex_v1
from google.api_core.exceptions import AlreadyExists
def create_and_run_scan(
client: dataplex_v1.DataScanServiceClient,
project_id: str,
location: str,
data_scan_id: str,
target_resource: str,
) -> dataplex_v1.DataScanJob | None:
"""
Creates and runs a single data profile scan.
Returns the executed Job object without waiting for completion.
"""
parent = client.data_scan_path(project_id, location, data_scan_id).rsplit('/', 2)[0]
scan_path = client.data_scan_path(project_id, location, data_scan_id)
# 1. Create Data Scan (skips if it already exists)
try:
data_scan = dataplex_v1.DataScan()
data_scan.data.resource = target_resource
data_scan.data_profile_spec = dataplex_v1.DataProfileSpec()
print(f"[INFO] Creating data scan '{data_scan_id}'...")
client.create_data_scan(
parent=parent,
data_scan=data_scan,
data_scan_id=data_scan_id
).result() # Wait for creation to complete
print(f"[SUCCESS] Data scan '{data_scan_id}' created.")
except AlreadyExists:
print(f"[INFO] Data scan '{data_scan_id}' already exists. Skipping creation.")
except Exception as e:
print(f"[ERROR] Error creating data scan '{data_scan_id}': {e}")
return None
# 2. Run Data Scan
try:
print(f"[INFO] Running data scan '{data_scan_id}'...")
run_response = client.run_data_scan(name=scan_path)
print(f"[SUCCESS] Job started for '{data_scan_id}'. Job ID: {run_response.job.name.split('/')[-1]}")
return run_response.job
except Exception as e:
print(f"[ERROR] Error running data scan '{data_scan_id}': {e}")
return None
def main():
"""Main execution function"""
# --- Load configuration from environment variables ---
PROJECT_ID = os.environ.get("PROJECT_ID")
LOCATION = os.environ.get("LOCATION")
DATASET_ID = os.environ.get("DATASET_ID")
if not all([PROJECT_ID, LOCATION, DATASET_ID]):
print("[ERROR] One or more required environment variables are not set.")
print("Please ensure PROJECT_ID, LOCATION, and DATASET_ID are exported in your shell.")
sys.exit(1)
print(f"[INFO] Using Project: {PROJECT_ID}, Location: {LOCATION}, Dataset: {DATASET_ID}")
# List of Materialized Views to profile
TARGET_VIEWS = [
"mv_ga4_user_session_flat",
"mv_ga4_ecommerce_transactions",
"mv_ga4_ecommerce_items"
]
# ----------------------------------------------------
client = dataplex_v1.DataScanServiceClient()
running_jobs = []
# 1. Create and run jobs for all target views
print("\n--- Starting Data Profiling Job Creation and Execution ---")
for view_name in TARGET_VIEWS:
data_scan_id = f"profile-scan-{view_name.replace('_', '-')}"
target_resource = f"//bigquery.googleapis.com/projects/{PROJECT_ID}/datasets/{DATASET_ID}/tables/{view_name}"
job = create_and_run_scan(client, PROJECT_ID, LOCATION, data_scan_id, target_resource)
if job:
running_jobs.append(job)
print("-------------------------------------------------------\n")
if not running_jobs:
print("[ERROR] No jobs were started. Exiting.")
return
# 2. Poll for all jobs to complete
print("--- Monitoring job completion status (checking every 30 seconds) ---")
completed_jobs = {}
while running_jobs:
jobs_to_poll_next = []
print(f"\n[STATUS] Checking status for {len(running_jobs)} running jobs...")
for job in running_jobs:
job_id_short = job.name.split('/')[-1][:13]
try:
updated_job = client.get_data_scan_job(name=job.name)
state = updated_job.state
if state in (dataplex_v1.DataScanJob.State.RUNNING, dataplex_v1.DataScanJob.State.PENDING, dataplex_v1.DataScanJob.State.CANCELING):
print(f" - Job {job_id_short}... Status: {state.name}")
jobs_to_poll_next.append(updated_job)
else:
print(f" - Job {job_id_short}... Status: {state.name} (Complete)")
completed_jobs[job.name] = updated_job
except Exception as e:
print(f"[ERROR] Could not check status for job {job_id_short}: {e}")
running_jobs = jobs_to_poll_next
if running_jobs:
time.sleep(30)
# 3. Print final results
print("\n--------------------------------------------------")
print("[SUCCESS] All data profiling jobs have completed.")
print("\nFinal Job Status Summary:")
for job_name, job in completed_jobs.items():
job_id_short = job_name.split('/')[-1][:13]
print(f" - Job {job_id_short}: {job.state.name}")
if job.state == dataplex_v1.DataScanJob.State.FAILED:
print(f" - Failure Message: {job.message}")
print("\nNext step: Analyze the profile results and generate quality rules.")
if __name__ == "__main__":
main()
Sekarang, jalankan skrip dari terminal Cloud Shell Anda.
python 1_run_scan.py
Skrip kini akan mengatur pembuatan profil tiga Materialized View Anda, dengan memberikan pembaruan status real-time. Setelah selesai, Anda akan memiliki profil statistik yang kaya dan dapat dibaca mesin untuk setiap tampilan, yang siap untuk tahap berikutnya dalam alur kerja kami: pembuatan aturan kualitas data yang didukung AI.
Anda dapat melihat pemindaian profil yang telah selesai di Konsol Google Cloud.
- Di menu navigasi, buka Knowledge Catalog dan Data profiling & quality di bagian Govern.
- Anda akan melihat tiga pemindaian profil Anda yang tercantum, beserta status tugas terbarunya. Anda dapat mengklik pemindaian untuk melihat hasil mendetail.
Dari profil BigQuery ke input yang siap digunakan AI
Pemindaian profil Knowledge Catalog telah berhasil dijalankan. Meskipun hasilnya tersedia dalam Knowledge Catalog API, untuk menggunakannya sebagai input bagi model AI generatif, kita perlu mengekstraknya ke dalam file lokal terstruktur.
Skrip Python berikut, 2_dq_profile_save.py, secara terprogram menemukan tugas pemindaian profil yang berhasil terbaru untuk tampilan mv_ga4_user_session_flat kita. Kemudian, ia mengambil hasil profil yang lengkap dan mendetail, lalu menyimpannya sebagai file JSON lokal bernama dq_profile_results.json. File ini akan berfungsi sebagai input langsung untuk analisis AI kita pada langkah berikutnya.
Di editor Cloud Shell, buat file baru bernama 2_dq_profile_save.py dan tempelkan kode berikut ke dalamnya. Sama seperti langkah sebelumnya, Anda dapat melewati pembuatan file jika Anda meng-clone repositori.
import os
import sys
import json
from google.cloud import dataplex_v1
from google.api_core.exceptions import NotFound
from google.protobuf.json_format import MessageToDict
# --- Configuration ---
# The Materialized View to analyze is fixed for this step.
TARGET_VIEW = "mv_ga4_user_session_flat"
OUTPUT_FILENAME = "dq_profile_results.json"
def save_to_json_file(content: dict, filename: str):
"""Saves the given dictionary content to a JSON file."""
try:
with open(filename, "w", encoding="utf-8") as f:
# Use indent=2 for a readable, "pretty-printed" JSON file.
json.dump(content, f, indent=2, ensure_ascii=False)
print(f"\n[SUCCESS] Profile results were saved to '{filename}'.")
except (IOError, TypeError) as e:
print(f"[ERROR] An error occurred while saving the file: {e}")
def get_latest_successful_job(
client: dataplex_v1.DataScanServiceClient,
project_id: str,
location: str,
data_scan_id: str
) -> dataplex_v1.DataScanJob | None:
"""Finds and returns the most recently succeeded job for a given data scan."""
scan_path = client.data_scan_path(project_id, location, data_scan_id)
print(f"\n[INFO] Looking for the latest successful job for scan '{data_scan_id}'...")
try:
# List all jobs for the specified scan, which are ordered most-recent first.
jobs_pager = client.list_data_scan_jobs(parent=scan_path)
# Iterate through jobs to find the first one that succeeded.
for job in jobs_pager:
if job.state == dataplex_v1.DataScanJob.State.SUCCEEDED:
return job
# If no successful job is found after checking all pages.
return None
except NotFound:
print(f"[WARN] No scan history found for '{data_scan_id}'.")
return None
def main():
"""Main execution function."""
# --- Load configuration from environment variables ---
PROJECT_ID = os.environ.get("PROJECT_ID")
LOCATION = os.environ.get("LOCATION")
if not all([PROJECT_ID, LOCATION]):
print("[ERROR] Required environment variables PROJECT_ID or LOCATION are not set.")
sys.exit(1)
print(f"[INFO] Using Project: {PROJECT_ID}, Location: {LOCATION}")
print(f"--- Starting Profile Retrieval for: {TARGET_VIEW} ---")
# Construct the data_scan_id based on the target view name.
data_scan_id = f"profile-scan-{TARGET_VIEW.replace('_', '-')}"
# 1. Initialize client and get the latest successful job.
client = dataplex_v1.DataScanServiceClient()
latest_job = get_latest_successful_job(client, PROJECT_ID, LOCATION, data_scan_id)
if not latest_job:
print(f"\n[ERROR] No successful job record was found for '{data_scan_id}'.")
print("Please ensure the '1_run_scan.py' script has completed successfully.")
return
job_id_short = latest_job.name.split('/')[-1]
print(f"[SUCCESS] Found the latest successful job: '{job_id_short}'.")
# 2. Fetch the full, detailed profile result for the job.
print(f"[INFO] Retrieving detailed profile results for job '{job_id_short}'...")
try:
request = dataplex_v1.GetDataScanJobRequest(
name=latest_job.name,
view=dataplex_v1.GetDataScanJobRequest.DataScanJobView.FULL,
)
job_with_full_results = client.get_data_scan_job(request=request)
except Exception as e:
print(f"[ERROR] Failed to retrieve detailed job results: {e}")
return
# 3. Convert the profile result to a dictionary and save it to a JSON file.
if job_with_full_results.data_profile_result:
profile_dict = MessageToDict(job_with_full_results.data_profile_result._pb)
save_to_json_file(profile_dict, OUTPUT_FILENAME)
else:
print("[WARN] The job completed, but no data profile result was found within it.")
print("\n[INFO] Script finished successfully.")
if __name__ == "__main__":
main()
Sekarang, jalankan skrip dari terminal Anda:
python 2_dq_profile_save.py
Setelah berhasil diselesaikan, Anda akan memiliki file baru bernama dq_profile_results.json di direktori Anda. File ini berisi metadata statistik yang kaya dan mendetail yang akan kita gunakan untuk membuat aturan kualitas data. Jika Anda ingin memeriksa isi dq_profile_results.json, jalankan perintah berikut:
cat dq_profile_results.json
4. Membuat aturan kualitas data dengan Antigravity CLI
Sekarang Anda dapat menggunakan Antigravity CLI (agy) untuk membaca hasil pemindaian profil lokal. Menulis spesifikasi kualitas data secara manual untuk set data yang kompleks memakan waktu dan rentan terhadap error. Menggunakan agen AI generatif dalam terminal Anda akan 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, jalankan perintah berikut di terminal Anda:
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, kita akan meminta agen Antigravity untuk menganalisis profil statistik dan mengusulkan rencana tindakan. Kita secara eksplisit menginstruksikannya untuk tidak menulis file YAML terlebih dahulu. Bagian ini memfokuskan perhatiannya 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 (e.g., "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 harus menampilkan rencana terstruktur yang mirip dengan ini:
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 oleh agen hanya didasarkan pada pola statistik dalam data. Agen tersebut 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.
Tinjau dengan cermat rencana yang diberikan agen.
- Apakah masuk akal?
- Apakah model ini sesuai dengan pengetahuan bisnis Anda?
- Apakah ada aturan yang valid secara statistik, tetapi tidak berguna secara praktis?
Output yang Anda terima dari agen dapat bervariasi. Tujuan Anda adalah menyempurnakannya. Misalnya, bayangkan rencana menyarankan aturan rowCount karena tabel memiliki jumlah baris tetap dalam data sampel. Sebagai pakar manusia, Anda mungkin tahu bahwa ukuran tabel ini diperkirakan akan bertambah setiap hari, sehingga aturan jumlah baris yang ketat tidak praktis dan cenderung menyebabkan pemberitahuan palsu. Ini adalah contoh sempurna penerapan konteks bisnis yang tidak dimiliki AI.
Sekarang, Anda akan memberikan masukan kepada agen dan memberikan perintah akhir untuk membuat kode. Anda harus menyesuaikan perintah berikut berdasarkan paket yang benar-benar Anda terima dan koreksi yang ingin Anda lakukan.
Perintah di bawah adalah template. Baris pertama adalah tempat Anda memberikan koreksi spesifik. Jika rencana yang diberikan agen sudah sempurna dan tidak perlu diubah, Anda cukup menghapus baris tersebut.
Dalam sesi Antigravity yang sama, masukkan perintah berikut yang telah Anda sesuaikan:
# 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 in the local virtual environment path (`./dq_venv/.../google/cloud/dataplex_v1/types/data_quality.py`) as the schema authority.
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 konten YAML berdasarkan petunjuk Anda yang tepat dan divalidasi oleh manusia. Setelah selesai, Anda akan menemukan file baru bernama dq_rules.yaml di direktori kerja Anda.
Membuat dan menjalankan pemindaian kualitas data
Setelah memiliki file dq_rules.yaml yang dibuat agen dan divalidasi manusia, Anda dapat men-deploy-nya dengan yakin.
Keluar dari Antigravity CLI dengan mengetik /quit atau menekan Ctrl+C dua kali.
Perintah gcloud berikut membuat resource pemindaian data Knowledge Catalog baru. Pindai belum dijalankan; perintah ini hanya mendaftarkan definisi dan konfigurasi pemindaian (file YAML) dengan Knowledge Catalog.
Jalankan perintah ini di terminal Anda:
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"
Setelah pemindaian ditentukan, Anda dapat memicu tugas untuk menjalankannya.
gcloud dataplex datascans run $DQ_SCAN --location=$LOCATION --project=$PROJECT_ID
Perintah ini akan menghasilkan ID tugas. Anda dapat memantau status tugas ini di bagian Knowledge Catalog di Konsol Google Cloud. Setelah selesai, hasilnya akan ditulis ke tabel BigQuery untuk dianalisis.
5. Peran penting Human-In-The-Loop (HITL)
Meskipun penggunaan agen Antigravity untuk mempercepat pembuatan aturan sangat efektif, Anda harus memperlakukan AI sebagai kopilot yang sangat terampil, bukan pilot yang sepenuhnya otonom. Proses Human-in-the-Loop (HITL) bukanlah saran opsional; ini adalah langkah mendasar yang tidak dapat dinegosiasikan dalam alur kerja tata kelola data apa pun. Menerapkan artefak yang dihasilkan AI tanpa pengawasan manusia yang ketat akan berujung pada kegagalan.
Anggap dq_rules.yaml yang dihasilkan AI sebagai permintaan pull yang dikirimkan oleh developer AI yang sangat cepat, tetapi tidak berpengalaman. Hal ini memerlukan peninjauan menyeluruh dari pakar senior—Anda—sebelum dapat digabungkan ke "cabang utama" kebijakan tata kelola Anda dan di-deploy. Peninjauan ini penting untuk mengurangi kelemahan bawaan Model Bahasa Besar.
Berikut perincian mendetail tentang alasan peninjauan manual ini sangat diperlukan dan hal yang harus Anda perhatikan secara khusus:
1. Validasi kontekstual: AI tidak memiliki pemahaman bisnis
- Kelemahan LLM: LLM sangat ahli dalam pola dan statistik, tetapi tidak memiliki pemahaman tentang konteks bisnis Anda. Misalnya, jika kolom,
new_campaign_idmemiliki rasio null 98%, LLM mungkin mengabaikan kolom ini karena alasan statistik. - Peran penting manusia: Anda, sebagai pakar manusia, tahu bahwa kolom
new_campaign_idbaru ditambahkan kemarin untuk peluncuran produk besar minggu depan. Anda tahu bahwa rasio null-nya seharusnya tinggi sekarang, tetapi diperkirakan akan turun secara signifikan. Anda juga tahu bahwa setelah diisi, kolom tersebut harus mengikuti format tertentu. AI tidak mungkin menyimpulkan pengetahuan bisnis eksternal ini. Peran Anda adalah menerapkan konteks bisnis ini pada saran statistik AI, mengganti atau menambahkannya sesuai kebutuhan.
2. Ketepatan dan presisi: melindungi dari halusinasi dan kesalahan halus
- Kelemahan LLM: LLM bisa "salah dengan percaya diri". AI dapat "berhalusinasi" atau menghasilkan kode yang sedikit salah. Misalnya, alat ini dapat membuat file YAML dengan aturan yang diberi nama dengan benar, tetapi memiliki parameter yang tidak valid, atau salah mengeja jenis aturan (misalnya,
setExpectations, bukansetExpectationyang benar). Error kecil ini akan menyebabkan deployment gagal, tetapi sulit untuk ditemukan. - Peran penting manusia: Tugas Anda adalah bertindak sebagai validator skema dan linter utama. Anda harus memeriksa YAML yang dihasilkan dengan cermat berdasarkan spesifikasi
DataQualityRuleKnowledge Catalog resmi. Anda tidak hanya memeriksa apakah "terlihat benar"; Anda memvalidasi kebenaran sintaksis dan semantiknya untuk memastikan 100% sesuai dengan API target. Itulah sebabnya codelab meminta agen untuk mereferensikan file skema—untuk mengurangi kemungkinan terjadinya error—tetapi verifikasi akhir tetap ada pada Anda.
3. Keselamatan dan mitigasi risiko: mencegah konsekuensi hilir
- Kelemahan LLM: Aturan kualitas data yang salah yang di-deploy ke produksi dapat menimbulkan konsekuensi yang berat. Jika AI menyarankan
rangeExpectationuntuk jumlah transaksi keuangan yang terlalu luas, AI tersebut mungkin gagal mendeteksi aktivitas penipuan. Sebaliknya, jika menyarankan aturan yang terlalu ketat berdasarkan sampel data kecil, hal ini dapat membanjiri tim siaga Anda dengan ribuan pemberitahuan positif palsu, sehingga menyebabkan kelelahan akibat pemberitahuan dan menyebabkan masalah sebenarnya terlewatkan. - Peran penting manusia: Anda adalah engineer keselamatan. Anda harus menilai potensi dampak hilir dari setiap aturan yang disarankan AI. Tanyakan pada diri Anda: "Apa yang terjadi jika aturan ini gagal? Apakah pemberitahuan tersebut memerlukan tindakan? Apa risikonya jika aturan ini salah lulus?" Penilaian risiko ini adalah kemampuan unik manusia yang menimbang biaya kegagalan terhadap manfaat pemeriksaan.
4. Tata kelola sebagai proses berkelanjutan: menggabungkan pengetahuan yang berorientasi ke depan
- Kelemahan LLM: Pengetahuan AI didasarkan pada snapshot data statis—hasil profil dari titik waktu tertentu. Model ini tidak memiliki pengetahuan tentang peristiwa mendatang.
- Peran penting manusia: Strategi tata kelola Anda harus berorientasi ke masa depan. Anda tahu bahwa sumber data dijadwalkan untuk dimigrasikan bulan depan, yang akan mengubah stream_id. Anda tahu bahwa negara baru sedang ditambahkan ke daftar
geo_country. Proses HITL adalah tempat Anda memasukkan pengetahuan tentang kondisi masa depan ini, memperbarui atau menonaktifkan aturan untuk sementara guna mencegah kerusakan selama evolusi bisnis atau teknis yang direncanakan. Kualitas data bukanlah penyiapan satu kali; ini adalah proses berkelanjutan yang harus berkembang, dan hanya manusia yang dapat memandu evolusi tersebut.
Singkatnya, HITL adalah mekanisme uji mutu dan keamanan penting yang mengubah tata kelola berbasis AI dari ide baru yang berisiko menjadi praktik yang bertanggung jawab, skalabel, dan tingkat perusahaan. Hal ini memastikan bahwa kebijakan akhir yang di-deploy tidak hanya dipercepat oleh AI, tetapi juga divalidasi oleh manusia, sehingga menggabungkan kecepatan mesin dengan kebijaksanaan dan konteks pakar manusia.
Namun, penekanan pada pengawasan manusia ini tidak mengurangi nilai AI. Sebaliknya, AI generatif memainkan peran penting dalam mempercepat proses HITL itu sendiri.
Tanpa AI, seorang data engineer harus:
- Tulis kueri SQL kompleks secara manual untuk memprofilkan data (misalnya,
COUNT DISTINCT,AVG,MIN,MAXuntuk setiap kolom). - Menganalisis hasil spreadsheet satu per satu dengan cermat.
- Menulis setiap baris file aturan YAML dari awal, tugas yang membosankan dan rentan terhadap error.
AI mengotomatiskan langkah-langkah yang sulit dan memakan waktu ini. Alat ini bertindak sebagai analis yang tidak kenal lelah yang langsung memproses profil statistik dan memberikan "draf pertama" kebijakan yang terstruktur dengan baik dan 80% selesai.
Hal ini mengubah sifat pekerjaan manusia secara mendasar. Alih-alih menghabiskan waktu berjam-jam untuk memproses data secara manual dan membuat kode boilerplate, pakar manusia dapat langsung berfokus pada tugas-tugas bernilai paling tinggi:
- Menerapkan konteks bisnis yang penting.
- Memvalidasi kebenaran logika AI.
- Membuat keputusan strategis tentang aturan mana yang benar-benar penting.
Dalam kemitraan ini, AI menangani "apa" (apa pola statistiknya?), sehingga manusia dapat berfokus pada "mengapa" (mengapa pola ini penting bagi bisnis kita?) dan "lalu bagaimana" (lalu bagaimana kebijakan kita seharusnya?). Oleh karena itu, AI tidak menggantikan loop; AI membuat setiap siklus melalui loop lebih cepat, lebih cerdas, dan lebih berdampak.
6. Membersihkan lingkungan Anda
Agar tidak menimbulkan biaya di masa mendatang pada akun Google Cloud Anda untuk resource yang digunakan dalam codelab ini, Anda harus menghapus project yang berisi resource tersebut. Namun, jika ingin mempertahankan project, Anda dapat menghapus resource individual yang telah dibuat.
Menghapus pemindaian Knowledge Catalog
Pertama, hapus profil dan pemindaian kualitas yang Anda buat. Untuk mencegah penghapusan resource penting secara tidak sengaja, perintah ini menggunakan nama spesifik hasil pemindaian yang dibuat dalam 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 BigQuery
Selanjutnya, hapus set data BigQuery. Perintah ini tidak dapat diurungkan dan menggunakan flag -f (force) untuk menghapus set data dan semua tabelnya tanpa konfirmasi.
# Manually type this command to confirm you are deleting the correct dataset
bq rm -r -f --dataset $PROJECT_ID:kc_dq_codelab
7. Selamat!
Anda berhasil menyelesaikan codelab.
Anda telah membangun alur kerja tata kelola data terprogram secara menyeluruh. Anda memulai dengan menggunakan Tampilan Material untuk meratakan data BigQuery yang kompleks, sehingga cocok untuk analisis. Kemudian, Anda menjalankan pemindaian profil Knowledge Catalog secara terprogram untuk menghasilkan metadata statistik. Yang terpenting, Anda memanfaatkan Antigravity CLI untuk menganalisis output profil dan membuat artefak "kebijakan sebagai kode" (dq_rules.yaml) secara cerdas. Kemudian, Anda menggunakan CLI untuk men-deploy konfigurasi ini sebagai Pemindaian Kualitas Data otomatis, sehingga melengkapi strategi tata kelola yang modern dan skalabel.
Sekarang Anda telah dilengkapi dengan pola dasar untuk membangun sistem kualitas data yang andal, dipercepat AI, dan divalidasi manusia di Google Cloud.
Apa langkah selanjutnya?
- Integrasikan dengan CI/CD: Ambil file
dq_rules.yamldan lakukan commit ke repositori Git. Buat pipeline CI/CD (misalnya, menggunakan Cloud Build atau GitHub Actions) yang otomatis men-deploy pemindaian Knowledge Catalog setiap kali file aturan diperbarui. - Jelajahi aturan SQL kustom: Melampaui jenis aturan standar. Knowledge Catalog mendukung aturan SQL kustom untuk menerapkan logika khusus bisnis yang lebih kompleks yang tidak dapat dinyatakan dengan pemeriksaan yang telah ditentukan sebelumnya. Ini adalah fitur untuk menyesuaikan validasi dengan persyaratan unik Anda.
- Mengoptimalkan pemindaian untuk efisiensi dan biaya: Untuk tabel yang sangat besar, Anda dapat meningkatkan performa dan mengurangi biaya dengan tidak selalu memindai seluruh set data. Pelajari penggunaan filter untuk mempersempit pemindaian ke rentang waktu atau segmen data tertentu, atau konfigurasi pemindaian yang disampel untuk memeriksa persentase data yang representatif.
- Visualisasikan hasil: Output setiap pemindaian kualitas data Knowledge Catalog ditulis ke tabel BigQuery. Hubungkan tabel ini ke Looker Studio untuk membuat dasbor yang melacak skor kualitas data Anda dari waktu ke waktu, yang diagregasi menurut dimensi yang Anda tentukan (misalnya, Kelengkapan, Validitas). Hal ini membuat pemantauan menjadi proaktif dan dapat dilihat oleh semua pemangku kepentingan.
- Bagikan praktik terbaik: Dorong berbagi pengetahuan dalam organisasi Anda untuk memanfaatkan pengalaman kolektif dan meningkatkan strategi kualitas data Anda. Mendorong budaya kepercayaan data adalah kunci untuk mengoptimalkan upaya tata kelola Anda.
- Baca dokumentasi: