Membangun Fondasi Data dengan Metadata Dataplex

1. Pengantar

Model AI generatif adalah pendorong yang kuat, tetapi tidak memiliki konteks institusional. Jika seorang eksekutif bertanya kepada agen AI, "Berapa pendapatan Q1 kita?", agen tersebut mungkin menemukan lusinan tabel bernama "pendapatan" di seluruh data lake Anda. Beberapa di antaranya adalah laporan keuangan yang ketat, yang lain adalah perkiraan pemasaran real-time, dan banyak yang kemungkinan merupakan sandbox yang tidak digunakan lagi.

Tanpa perujukan eksplisit, agen AI akan memilih tabel berdasarkan kesamaan nama sederhana, sehingga menghasilkan jawaban "salah yang meyakinkan" yang berasal dari data yang tidak terverifikasi.

Codelab ini adalah bagian dari seri dua bagian yang membahas cara membuat Agen GenAI yang Sadar Tata Kelola.

Di bagian pertama ini, Anda akan membangun fondasi data. Anda akan menyiapkan data lake yang realistis dan "berantakan" di BigQuery, menerapkan tag metadata yang ketat (Aspek Dataplex) untuk membedakan data yang valid dari noise, dan menggunakan Gemini CLI untuk menguji secara lokal apakah LLM mematuhi aturan tata kelola Anda dengan ketat.

(Anda dapat membaca bagian kedua dari seri ini, yang membahas cara men-deploy prototipe lokal ini ke dalam aplikasi web tingkat perusahaan yang aman menggunakan Model Context Protocol (MCP) dan Cloud Run. 👉 Baca Bagian 2)

Prasyarat

• Project Google Cloud yang mengaktifkan penagihan.
• Pemahaman dasar dan keakraban dengan BigQuery, Dataplex Universal Catalog, dan Terraform.
• Akses ke Google Cloud Shell.

Yang akan Anda pelajari

• Men-deploy data lake multi-tingkat yang realistis menggunakan Terraform.
• Desain template metadata yang ketat (Jenis Aspek) di Dataplex untuk membedakan produk data resmi dari tabel sandbox mentah.
• Verifikasi aturan tata kelola secara lokal menggunakan Gemini CLI sebelum menulis kode aplikasi apa pun.

Yang Anda butuhkan

• Akses ke Google Cloud Shell
• Terraform (sudah diinstal di Cloud Shell).
• Gemini CLI (sudah terinstal di Cloud Shell).

Konsep utama

• Dataplex Universal Catalog: Layanan pengelolaan metadata terpadu. Kami menggunakannya untuk memperkaya metadata teknis (skema) dengan konteks bisnis (tata kelola).
• Jenis Aspek: Template metadata terstruktur. Tidak seperti tag teks bebas, Aspek menerapkan pengetikan yang kuat (enum, boolean), sehingga dapat diandalkan untuk dievaluasi oleh mesin.

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.

Lakukan inisialisasi lingkungan

Buka Cloud Shell dan tetapkan variabel project Anda untuk memastikan semua perintah menargetkan infrastruktur yang benar.

export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"

Aktifkan API

Aktifkan layanan Google Cloud yang diperlukan untuk menjalankan petunjuk berikut.

gcloud services enable \
  artifactregistry.googleapis.com \
  bigqueryunified.googleapis.com \
  cloudaicompanion.googleapis.com \
  cloudbuild.googleapis.com \
  cloudresourcemanager.googleapis.com \
  datacatalog.googleapis.com \
  run.googleapis.com

Membuat clone repositori

Dapatkan kode infrastruktur dan skrip otomatisasi dari repositori GitHub. Untuk menghemat ruang disk di Cloud Shell, kita hanya akan mendownload folder tertentu yang diperlukan untuk lab 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/governance-context
cd data-analytics/governance-context

Membangun data lake "berantakan"

Lingkungan data dunia nyata jarang bersih. Untuk menyimulasikan realitas, kita memerlukan gabungan tabel "sandbox" yang tidak tepercaya dan data mart "resmi".

Kita akan menggunakan Terraform untuk men-deploy lingkungan ini. Konfigurasi ini menangani dua tugas:

• Infrastruktur: Membuat Jenis Aspek Dataplex dan Set Data/Tabel BigQuery.
• Pemuatan Data: Menjalankan tugas INSERT BigQuery untuk mengisi tabel dengan data sampel segera setelah pembuatan.

1. Buka direktori terraform dan lakukan inisialisasi.

cd terraform
terraform init

2. Terapkan konfigurasi. Proses ini mungkin memerlukan waktu hingga satu menit.

terraform apply -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

Checkpoint: Sekarang Anda memiliki data lake yang terisi sepenuhnya, tetapi tidak diatur sama sekali. Bagi AI, setiap tabel terlihat sama persis.

3. Menerapkan tata kelola

Ini adalah langkah engineering yang penting. Saat ini, tabel finance_mart.fin_monthly_closing_internal dan analyst_sandbox.tmp_data_dump_v2_final_real terlihat identik bagi LLM. Objek tersebut hanyalah objek dengan kolom.

Sebagai engineer tata kelola, Anda harus melampirkan Aspek (label metadata bersertifikasi) ke tabel ini untuk membedakannya. Di perusahaan yang sebenarnya, Anda akan mengotomatiskan hal ini melalui pipeline CI/CD. Kita akan menyimulasikan otomatisasi tersebut dengan skrip.

Membuat payload tata kelola

Kunci Aspek Dataplex harus unik secara global (diawali dengan Project ID Anda). Skrip ./generate_payloads.sh akan menghasilkan file metadata YAML secara dinamis.

cd ..
chmod +x ./generate_payloads.sh
./generate_payloads.sh

Output:

Tindakan ini akan membuat folder "./aspect_payloads" yang berisi 4 file YAML, yang menentukan skenario tata kelola (Gold/Internal, Gold/Public, Silver/Realtime, Bronze/Sandbox).

Menerapkan Aspek melalui CLI

Sebelum menjalankan skrip, mari kita lihat apa yang sebenarnya kita terapkan untuk menyederhanakan prosesnya. Jalankan perintah berikut untuk melihat struktur payload keuangan internal:

cat aspect_payloads/fin_internal.yaml

Tab tersebut akan menampilkan konten berikut.

your-project-id.us-central1.official-data-product-spec:
  data:
    product_tier: GOLD_CRITICAL
    data_domain: FINANCE
    usage_scope: INTERNAL_ONLY
    update_frequency: DAILY_BATCH
    is_certified: true

Perhatikan cara YAML ini secara eksplisit menentukan konteks bisnis, seperti menyetel tanda is_certified: true dan menetapkan tingkat GOLD_CRITICAL. Memberi AI aturan yang jelas dan terstruktur untuk dievaluasi, bukan hanya menebak berdasarkan nama tabel.

Sekarang, jalankan skrip aplikasi. Proses ini melakukan iterasi melalui tabel BigQuery dan menjalankan perintah gcloud dataplex entries update untuk melampirkan metadata tetap ini.

chmod +x ./apply_governance.sh
./apply_governance.sh

Verifikasi (Opsional)

Sebelum melanjutkan, pastikan metadata diterapkan dengan benar di konsol.

1. Buka halaman Dataplex Universal Catalog di Konsol Google Cloud. Jika Anda tidak melihat "Dataplex Universal Catalog" di menu navigasi sebelah kiri, gunakan Kotak penelusuran di bagian atas jendela Konsol Google Cloud, ketik Dataplex, lalu pilih hasilnya di bagian "Hasil teratas" atau "Produk & Halaman".
2. Telusuri fin_monthly_closing_internal. Anda akan melihat tabel BigQuery yang tercantum dalam hasil. Klik nama tabel untuk membuka halaman detailnya.

3. Di halaman detail tabel, cari bagian "Tag dan aspek opsional" yang berada di bagian bawah.
4. Anda akan menemukan aspek official-data-product-spec. Konfirmasi bahwa nilai cocok dengan skenario "Gold Internal" yang kami terapkan.

Sekarang Anda telah mengonfirmasi bahwa tabel BigQuery yang identik secara teknis (fin_monthly_closing_internal dan tmp_data_dump_v2_final_real) dibedakan secara logis oleh metadata yang dapat dibaca mesin.

4. Mengonfigurasi dan membuat prototipe agen

Sebelum membuat aplikasi web (yang akan kita lakukan di Bagian 2), kita akan memverifikasi logika tata kelola kita secara lokal. Kita perlu menginstal Ekstensi Dataplex dan mengonfigurasi perintah sistem.

Menginstal ekstensi

Di Cloud Shell, instal Ekstensi Dataplex. Anda akan diminta untuk mengonfirmasi dan memberikan detail penyiapan Anda.

export DATAPLEX_PROJECT="${PROJECT_ID}"

gemini extensions install https://github.com/gemini-cli-extensions/dataplex

(Ketik Y untuk menyetujui penginstalan, dan masukkan Project ID Anda saat diminta).

Tentukan file kebijakan

File GEMINI.md berisi logika yang menerjemahkan aturan abstrak manusia (misalnya, "Saya perlu data yang aman") menjadi pencarian teknis yang ketat.

File ini saat ini bersifat umum. Agen perlu mengetahui secara persis project Google Cloud mana yang harus ditelusuri untuk mencegahnya berhalusinasi tabel dari internet publik atau konteks lainnya.

1. Suntikkan PROJECT_ID ke dalam file kebijakan.

envsubst < GEMINI.md > GEMINI.md.tmp && mv GEMINI.md.tmp GEMINI.md

2. Periksa file untuk memahami algoritma yang kita ajarkan kepada AI.

cat GEMINI.md

Perhatikan dua hal dalam file ini:

1. Cakupan Project: Periksa Tahap 2. Pastikan projectid:${PROJECT_ID} telah diganti dengan Project ID Anda yang sebenarnya (e.g., projectid:my-lab-project). Jika variabel ini tidak diganti, agen akan menelusuri setiap project yang dapat Anda akses, sehingga menghasilkan jawaban yang salah.
2. Algoritma: Perhatikan logika Tahap 1 / Tahap 2. Kita secara eksplisit menginstruksikan model untuk TIDAK menebak SQL. Pertama-tama, harus menelusuri definisi tag yang benar (Fase 1), lalu menelusuri data (Fase 2).

Mulai agen dan uji skenario

Mulai sesi Gemini CLI, kali ini dengan memuat kebijakan tata kelola Anda sebagai konteks sistem.

gemini

Catatan: Anda mungkin melihat beberapa file konteks dimuat (misalnya, GEMINI.md dan lainnya). Hal ini wajar. CLI memuat GEMINI.md lokal untuk aturan khusus project ini, serta petunjuk default untuk Ekstensi Dataplex itu sendiri.

Memverifikasi penginstalan

Ketik /mcp desc untuk mengonfirmasi bahwa Ekstensi Dataplex aktif. Anda akan melihat dataplex tercantum sebagai server MCP yang dikonfigurasi dengan alat yang tersedia.

Skenario pengujian (Pembuatan prototipe)

Tempelkan perintah berikut ke sesi agen yang sedang berjalan satu per satu untuk memverifikasi bahwa agen mematuhi aturan Anda.

💡 Tips: Jika diminta, pilih "2. Izinkan alat untuk sesi ini" guna mengaktifkan pengujian yang lancar.

• Skenario A (Mengesahkan data CFO):

"We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?"

Diharapkan: Kueri fin_monthly_closing_internal karena secara semantik cocok dengan GOLD_CRITICAL (akurat) dan INTERNAL_ONLY (rapat dewan) dalam Aspeknya.

• Skenario B (Pengungkapan publik):

"I need to share our quarterly financial summary with an external consulting firm. It is critical that we do not leak any raw or internal metrics. Which dataset is officially scrubbed and explicitly approved for external sharing?"

Diharapkan: Agen harus melewati tabel internal bulanan dan hanya memilih fin_quarterly_public_report karena merupakan satu-satunya aset yang diberi tag EXTERNAL_READY.

• Skenario C (Kebutuhan operasional):

"My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?"

Harapan: Agen memilih mkt_realtime_campaign_performance karena mengidentifikasi frekuensi pembaruan REALTIME_STREAMING, yang diprioritaskan daripada tingkat GOLD_CRITICAL data keuangan.

• Skenario D (Eksperimen sandbox):

"I'm just playing around with some new ML models and need a lot of raw data. It doesn't need to be perfect, just a sandbox environment."

Harapan: Agen memilih tmp_data_dump_v2_final_real karena secara semantik cocok dengan BRONZE_ADHOC (data mentah) dan is_certified: false (lingkungan sandbox) dalam Aspeknya.

(Untuk keluar dari sesi Gemini, ketik /quit)

⚠️ Catatan: Rilis Beta (Per Februari 2026)

Ekstensi Dataplex untuk Gemini CLI dan MCP Toolbox yang mendasarinya saat ini dalam versi Beta (pra-v1.0).

Karena ini adalah project open source yang terus berkembang, Anda mungkin sesekali mengalami perilaku yang tidak terduga, waktu tunggu diam (seperti menampilkan null), atau perubahan yang merusak. Google belum menjamin stabilitasnya sepenuhnya untuk penggunaan produksi.

Jika Anda mengalami masalah yang tidak dibahas dalam codelab ini, lihat repositori GitHub resmi untuk memeriksa update terbaru, masalah yang belum terselesaikan, atau untuk memberikan masukan.

5. Selamat! Apa langkah selanjutnya?

Anda telah berhasil membangun fondasi data yang diatur dan membuktikan bahwa AI dapat mengikuti aturan metadata Anda secara ketat menggunakan prototipe CLI lokal.

Sekarang, Anda telah mencapai titik pemeriksaan. Pilih langkah Anda berikutnya:

Opsi A: Saya ingin melanjutkan ke Bagian 2 sekarang!

Jika Anda siap mengubah prototipe lokal ini menjadi aplikasi web tingkat produksi yang aman menggunakan Model Context Protocol (MCP) dan Cloud Run:

👉 Link ke Codelab Bagian 2

⚠️ HENTIKAN: Jangan jalankan langkah-langkah Pembersihan di bawah. Anda memerlukan data dan setelan Dataplex saat ini untuk Bagian 2.

Opsi B: Saya akan mengerjakan Bagian 2 nanti atau saya hanya ingin menyelesaikan Bagian 1.

Jika Anda ingin berhenti untuk hari ini dan menghindari biaya cloud, Anda harus membersihkan resource.

Jangan khawatir! Di Bagian 2, kami akan memberikan "Skrip Jalur Cepat" yang akan membangun kembali lingkungan Bagian 1 ini sepenuhnya untuk Anda hanya dalam 2 menit, sehingga Anda dapat melanjutkan tepat di bagian yang terakhir Anda buka.

👉 Lanjutkan ke bagian Pembersihan.

6. Membersihkan (Hanya untuk opsi B)

Jika Anda berhenti di sini, hapus resource untuk menghindari timbulnya biaya.

Menghancurkan Datalake (Terraform)

Jika saat ini Anda berada di lingkungan Gemini CLI, keluar dari sesi dengan menekan Ctrl+C dua kali atau mengetik /quit. Kemudian, jalankan perintah berikut:

cd ~/devrel-demos/data-analytics/governance-context/terraform
terraform destroy -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

Meng-uninstal ekstensi Gemini CLI dan menghapus file lokal

gemini extensions uninstall dataplex
cd ~
rm -rf ~/devrel-demos