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 kualitas dan metadata yang andal langsung ke dalam siklus proses pengembangan. Pada intinya, Dataplex Universal Catalog berfungsi sebagai data fabric cerdas, yang memungkinkan organisasi mengelola, memantau, dan mengatur data secara terpusat di seluruh aset mereka—dari data lake hingga warehouse.
Codelab ini menunjukkan cara memanfaatkan Dataplex, BigQuery, dan Gemini CLI untuk meratakan data yang kompleks, membuat profilnya secara terprogram, menghasilkan 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 andal dan dapat dikontrol versinya.
Prasyarat
- Pemahaman dasar tentang Konsol Google Cloud
- Keterampilan dasar dalam antarmuka command line dan Google Cloud Shell
Yang akan Anda pelajari
- Cara meratakan data BigQuery bertingkat menggunakan Tampilan Terwujud untuk mengaktifkan pembuatan profil yang komprehensif.
- Cara memicu dan mengelola pemindaian profil Dataplex secara terprogram menggunakan Library Klien Python Dataplex.
- Cara mengekspor data profil dan menyusunnya sebagai input untuk model AI generatif.
- Cara membuat perintah untuk Gemini CLI guna menganalisis data profil dan membuat file aturan YAML yang kompatibel dengan Dataplex.
- Pentingnya proses human-in-the-loop (HITL) yang interaktif untuk memvalidasi konfigurasi yang dihasilkan AI.
- Cara men-deploy aturan yang dibuat sebagai pemindaian kualitas data otomatis.
Yang Anda butuhkan
- Akun Google Cloud dan Project Google Cloud
- Browser web seperti Chrome
Konsep utama: pilar kualitas data Dataplex
Memahami komponen inti Dataplex sangat penting untuk membangun strategi kualitas data yang efektif.
- Pemindaian Profil Data: Tugas Dataplex 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 Dataplex yang memvalidasi data terhadap serangkaian aturan yang telah ditentukan atau kustom.
- 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="dataplex_dq_codelab"
export TABLE_ID="ga4_transactions"
gcloud services enable dataplex.googleapis.com \
bigquery.googleapis.com \
serviceusage.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 dataplex_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.
git clone https://github.com/GoogleCloudPlatform/devrel-demos
cd devrel-demos/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 Dataplex
Pembuatan profil data Dataplex adalah alat canggih untuk menemukan informasi statistik tentang data Anda secara otomatis, seperti persentase null, keunikan, dan distribusi nilai. Proses ini penting untuk memahami struktur dan kualitas data Anda. Namun, batasan yang diketahui dari pembuatan profil Dataplex adalah ketidakmampuannya untuk memeriksa sepenuhnya kolom bertingkat atau berulang (misalnya, RECORD atau ARRAY) dalam tabel. Fitur ini dapat mengidentifikasi bahwa kolom adalah jenis kompleks, tetapi tidak dapat membuat profil setiap kolom dalam struktur bertingkat tersebut.
Untuk mengatasinya, kita akan meratakan data ke dalam Tampilan Terwujud yang dibuat khusus. Dengan strategi ini, setiap kolom menjadi kolom tingkat teratas, sehingga Dataplex 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 Tabel Virtual Terwujud
Membuat Tampilan Material (MV) adalah solusi paling efektif dan praktis untuk tantangan data bertingkat ini. Dengan menghitung hasil yang diratakan sebelumnya, MV menawarkan keuntungan signifikan dalam performa dan biaya kueri, sekaligus memberikan struktur yang lebih sederhana dan mirip relasional untuk alat analisis dan 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 Dataplex 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. Hal 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 Dataplex di dalam lingkungan yang baru diaktifkan.
# Install the Dataplex 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_dataplex_scans.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_dataplex_scans.py
Skrip kini akan mengatur pembuatan profil tiga Tampilan Terwujud Anda, dengan memberikan update 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 Dataplex Universal Catalog dan Profil 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 siap AI
Pemindaian profil Dataplex telah berhasil dijalankan. Meskipun hasilnya tersedia dalam Dataplex API, untuk menggunakannya sebagai input 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, 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 Dataplex 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 'run_dataplex_scans.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 Gemini CLI
Menginstal dan mengonfigurasi Gemini CLI
Meskipun Anda dapat memanggil Gemini API secara terprogram, penggunaan alat seperti Gemini CLI menawarkan cara yang efektif dan interaktif untuk mengintegrasikan AI generatif langsung ke alur kerja terminal Anda. Gemini CLI bukan hanya chatbot; ini adalah alat alur kerja command line yang dapat membaca file lokal Anda, memahami kode Anda, dan berinteraksi dengan alat sistem lain, seperti gcloud, untuk mengotomatiskan tugas yang kompleks. Hal ini membuatnya ideal untuk kasus penggunaan kita.
Prasyarat
Pertama, pastikan Anda telah memenuhi prasyarat yang diperlukan: Node.js versi 20 atau yang lebih tinggi harus diinstal di lingkungan Cloud Shell Anda. Anda dapat memeriksa versi Anda dengan menjalankan node -v.
Penginstalan
Ada dua cara untuk menggunakan Gemini CLI: menginstal sementara atau menginstal secara lebih permanen. Kita akan membahas kedua metode tersebut di sini.
Anda dapat menjalankan Gemini CLI secara langsung untuk satu sesi tanpa penginstalan permanen. Ini adalah cara paling bersih dan tercepat untuk "mencobanya", karena lingkungan Anda tidak akan dimodifikasi sama sekali.
Di terminal Cloud Shell, jalankan:
npx https://github.com/google-gemini/gemini-cli
Perintah ini akan mendownload dan menjalankan paket CLI untuk sementara.
Untuk project nyata, praktik terbaik yang direkomendasikan adalah menginstal CLI secara lokal ke direktori project Anda. Pendekatan ini memiliki beberapa keunggulan utama:
- Isolasi dependensi: Memastikan project Anda memiliki versi CLI sendiri, sehingga mencegah konflik versi dengan project lain.
- Reproduksibilitas: Siapa pun yang meng-clone project Anda dapat menginstal dependensi yang sama persis, sehingga penyiapan Anda menjadi andal dan portabel.
- Penyelarasan praktik terbaik: Mengikuti model standar untuk mengelola dependensi project Node.js, sehingga menghindari kesalahan penginstalan global (-g).
Untuk menginstal CLI secara lokal, jalankan perintah berikut dari folder project Anda (programmatic-dq):
npm install @google/gemini-cli
Tindakan ini akan membuat folder node_modules di dalam programmatic-dq. Untuk menjalankan versi yang baru saja Anda instal, gunakan perintah npx.
npx gemini
Penyiapan pertama kali
Metode apa pun yang Anda pilih, saat pertama kali Anda meluncurkan CLI, CLI akan memandu Anda melalui proses penyiapan satu kali.
Anda akan diminta untuk memilih tema warna, lalu melakukan autentikasi. Metode paling sederhana adalah Login dengan Akun Google Anda saat diminta. Paket gratis yang disediakan sudah cukup untuk codelab ini.
Setelah CLI diinstal dan dikonfigurasi, Anda siap melanjutkan pembuatan aturan. CLI mengetahui file di direktori saat ini, yang sangat penting untuk langkah berikutnya.
Buat aturan kualitas data
Meskipun LLM dapat diminta untuk membuat file konfigurasi dalam satu langkah, sifat model generatif yang non-deterministik berarti outputnya mungkin tidak selalu sepenuhnya sesuai dengan skema ketat yang diperlukan oleh alat seperti gcloud. Metode yang lebih andal adalah proses interaktif multi-langkah di mana Anda pertama-tama meminta AI bertindak sebagai analis untuk mengusulkan rencana, Anda (pakar manusia) meninjau dan menyetujui rencana tersebut, dan baru kemudian AI membuat kode akhir berdasarkan petunjuk yang Anda setujui.
Pendekatan ini mengubah proses dari perintah sederhana menjadi sesi kolaboratif, sehingga memastikan output akhir akurat, divalidasi, dan siap di-deploy.
Pertama, kita akan meminta Gemini menganalisis profil statistik dan bertindak sebagai pakar rekayasa data, yang mengusulkan rencana tindakan. Kita secara eksplisit memberi tahu untuk tidak menulis file YAML terlebih dahulu. Bagian ini memfokuskan perhatiannya pada analisis dan justifikasi.
Dalam sesi interaktif Gemini CLI Anda, tempel perintah berikut:
You are an expert Google Cloud Dataplex engineer.
Your first task is to create a plan. I have a file in the current directory named ./dq_profile_results.json.
Based on the statistical data within that file, propose a step-by-step plan to create a Dataplex data quality rules file.
Your plan should identify which specific columns are good candidates for rules like nonNullExpectation, setExpectation, or rangeExpectation, and explain why based on the metrics (e.g., "Plan to create a nonNullExpectation for column X because its null percentage is 0%").
Do not write the YAML file yet. Just provide the plan.
Gemini akan menganalisis file JSON dan akan menampilkan rencana terstruktur yang mirip dengan ini:
Plan to create Dataplex data quality rules
1. Create a row count rule:
- Analysis: The profile shows a total of 26,489 rows.
- Proposed Rule: I will implement a rowCount rule to ensure the table's row count remains within a healthy range (e.g., 20,000 to 30,000). This is a fundamental check to guard against major data loading failures or unexpected deletions.
2. Implement non-null expectation rules:
- Analysis: The profiling results show that many columns have no null values. For example, event_date, event_timestamp, event_name, user_pseudo_id, stream_id, and platform all appear to be fully populated.
- Proposed Rules: I will create nonNullExpectation rules for columns where the nullRatio is 0 or not present, indicating they are always expected to contain a value:
- event_date
- event_timestamp
- event_name
- user_pseudo_id
- stream_id
- platform
- device_category
- device_os
3. Implement set expectation rules:
- Analysis: Several columns contain a small, finite set of values, making them ideal for set validation.
- Proposed Rules: I will create setExpectation rules for these columns:
- platform: It only contains the value "WEB".
- device_category: It contains only "desktop", "mobile", and "tablet".
- geo_continent: It has a well-defined list of continents.
traffic_source_medium: It has a small list of valid mediums like "organic", "(none)", and "referral".
4. Implement range expectation rules:
- Analysis: The profile provides minimum and maximum values for numeric and string length fields.
- Proposed Rules: I will create rangeExpectation rules for the following:
- event_timestamp: The profile shows a clear min and max. I will use these values to create a range check.
- event_date (String Length): The profile indicates that the minLength and maxLength are both 8, which is perfect for enforcing a YYYYMMDD format.
Ini adalah langkah paling penting dalam seluruh alur kerja: peninjauan Human-in-the-Loop (HITL). Rencana yang dibuat oleh Gemini hanya didasarkan pada pola statistik dalam data. Model ini 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 Gemini.
- 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 Gemini 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 Gemini dan memberinya 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 Gemini sudah sempurna dan tidak perlu diubah, Anda cukup menghapus baris tersebut.
Dalam sesi Gemini yang sama, tempelkan perintah berikut yang telah Anda sesuaikan:
[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'."]
Once you have incorporated my feedback, please generate the `dq_rules.yaml` file.
You must adhere to the following strict requirements:
- Schema Compliance: The YAML structure must strictly conform to the DataQualityRule specification. For a definitive source of truth, you must 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.
- Data-Driven Values: All rule parameters, such as thresholds or expected values, must be derived directly from the statistical metrics in dq_profile_results.json.
- Rule Justification: For each rule, add a comment (#) on the line above explaining the justification, as you outlined in your plan.
- Output Purity: The final output must only be the raw YAML code block, perfectly formatted and ready for immediate deployment.
Sekarang, Gemini 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.
Membuat dan menjalankan pemindaian kualitas data
Setelah memiliki file dq_rules.yaml yang dibuat AI dan divalidasi manusia, Anda dapat men-deploy-nya dengan yakin.
Keluar dari Gemini CLI dengan mengetik /quit atau menekan Ctrl+C dua kali.
Perintah gcloud berikut membuat resource pemindaian data Dataplex baru. Pindai belum dijalankan; perintah ini hanya mendaftarkan definisi dan konfigurasi pemindaian (file YAML) dengan Dataplex.
Jalankan perintah ini di terminal Anda:
export DQ_SCAN="dq-scan"
gcloud dataplex datascans create data-quality $DQ_SCAN \
--project=$PROJECT_ID \
--location=$REGION \
--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=$REGION --project=$PROJECT_ID
Perintah ini akan menghasilkan ID tugas. Anda dapat memantau status tugas ini di bagian Dataplex pada Konsol Google Cloud. Setelah selesai, hasilnya akan ditulis ke tabel BigQuery untuk dianalisis.
5. Peran penting Human-In-The-Loop (HITL)
Meskipun penggunaan Gemini 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 yang kuat dan tepercaya. Men-deploy artefak yang dihasilkan AI tanpa pengawasan manusia yang ketat akan berujung pada kegagalan.
Anggap dq_rules.yaml yang dibuat AI sebagai pull request 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 dan di-deploy. Peninjauan ini sangat penting untuk mengurangi kelemahan bawaan Model Bahasa Besar.
Berikut perincian mendetail tentang alasan peninjauan manual ini sangat diperlukan dan hal-hal spesifik yang harus Anda perhatikan:
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, 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 error halus
- Kelemahan LLM: LLM bisa "salah dengan percaya diri". Model ini dapat "berhalusinasi" atau menghasilkan kode yang sedikit salah. Misalnya, alat ini dapat menghasilkan file YAML dengan aturan yang diberi nama dengan benar tetapi parameter tidak valid, atau salah mengeja jenis aturan (misalnya,
setExpectations, bukansetExpectationyang benar). Error halus 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
DataQualityRuleDataplex resmi. Anda tidak hanya memeriksa apakah "terlihat benar"; Anda memvalidasi kebenaran sintaksis dan semantiknya untuk memastikan bahwa 100% sesuai dengan API target. Itulah sebabnya codelab meminta Gemini 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 parah. Jika AI menyarankan
rangeExpectationuntuk jumlah transaksi keuangan yang terlalu luas, AI tersebut dapat 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, yang menyebabkan kelelahan pemberitahuan dan menyebabkan masalah nyata 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 dapat ditindaklanjuti? 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 statis data—hasil profil dari titik waktu tertentu. Tidak memiliki pengetahuan tentang acara 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 bukan penyiapan satu kali; ini adalah proses berkelanjutan yang harus berkembang, dan hanya manusia yang dapat memandu evolusi tersebut.
Singkatnya, HITL adalah mekanisme keamanan dan penjaminan kualitas penting yang mengubah tata kelola berbasis AI dari ide baru yang berisiko menjadi praktik yang bertanggung jawab, dapat diskalakan, 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:
- Menulis kueri SQL yang 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. AI 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 secara mendasar sifat pekerjaan manusia. Daripada menghabiskan waktu berjam-jam untuk memproses data secara manual dan membuat kode boilerplate, pakar manusia dapat langsung berfokus pada tugas-tugas yang paling bernilai:
- 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 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 setiap resource yang telah dibuat.
Menghapus pemindaian Dataplex
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 data-scans delete profile-scan-mv-ga4-user-session-flat \
--location=us-central1 \
--project=$PROJECT_ID --quiet
gcloud dataplex data-scans delete profile-scan-mv-ga4-ecommerce-transactions \
--location=us-central1 \
--project=$PROJECT_ID --quiet
gcloud dataplex data-scans delete profile-scan-mv-ga4-ecommerce-items \
--location=us-central1 \
--project=$PROJECT_ID --quiet
Hapus 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:dataplex_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 dianalisis. Kemudian, Anda menjalankan pemindaian profil Dataplex secara terprogram untuk menghasilkan metadata statistik. Yang terpenting, Anda memanfaatkan Gemini 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 menutup siklus pada 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 Selanjutnya?
- Integrasikan dengan CI/CD: Ambil file dq_rules.yaml dan commit ke repositori Git. Buat pipeline CI/CD (misalnya, menggunakan Cloud Build atau GitHub Actions) yang otomatis men-deploy pemindaian Dataplex setiap kali file aturan diperbarui.
- Jelajahi aturan SQL kustom: Melampaui jenis aturan standar. Dataplex 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 canggih 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 jangka waktu atau segmen data tertentu, atau konfigurasi pemindaian yang disampel untuk memeriksa persentase data yang representatif.
- Visualisasikan hasil: Output setiap pemindaian kualitas data Dataplex ditulis ke tabel BigQuery. Hubungkan tabel ini ke Looker Studio untuk membuat dasbor yang melacak skor kualitas data Anda dari waktu ke waktu, yang dikelompokkan 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: