QueryData untuk AlloyDB menggunakan Gemini Data Analytics

1. Pengantar

Codelab ini memberikan panduan tentang cara memulai QueryData untuk AlloyDB dan menggunakannya untuk membuat pernyataan SQL yang akurat dan dapat diprediksi dari input bahasa natural dalam aplikasi berbasis agen

Prasyarat

• Pemahaman dasar tentang konsol Google Cloud
• Keterampilan dasar dalam antarmuka command line dan Cloud Shell

Yang akan Anda pelajari

• Cara membuat cluster AlloyDB dan mengimpor data contoh
• Cara mengaktifkan AlloyDB Data Access API
• Cara mengaktifkan QueryData untuk AlloyDB
• Cara membuat template
• Cara menggunakan penelusuran berfaset
• Cara menggunakan QueryData dengan Agen AI

Yang Anda butuhkan

• Akun Google Cloud dan Project Google Cloud
• Browser web seperti Chrome yang mendukung Konsol Google Cloud dan Cloud Shell

2. Penyiapan dan Persyaratan

Penyiapan project

Buat Project Google Cloud

1. Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.
2. Pastikan penagihan diaktifkan untuk project Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project.

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:

Atau, Anda dapat menekan G, lalu S. Urutan ini akan mengaktifkan Cloud Shell jika Anda berada dalam Konsol Google Cloud atau menggunakan link ini.

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.

3. Sebelum memulai

Aktifkan API

Perlu diketahui bahwa beberapa resource yang Anda aktifkan akan dikenai biaya tertentu. Dalam keadaan normal, jika instance AlloyDB dan VM komputasi dihancurkan setelah lab selesai, biaya semua resource tidak akan melebihi $5. Sebaiknya periksa penagihan Anda dan pastikan biaya latihan ini sesuai dengan anggaran Anda.

Untuk menggunakan AlloyDB, Compute Engine, Layanan jaringan, dan Vertex AI, Anda harus mengaktifkan API masing-masing di project Google Cloud Anda.

Di dalam terminal Cloud Shell, pastikan project ID Anda sudah disiapkan:

gcloud config get-value project

Anda akan melihat tID project di output:

student@cloudshell:~ (test-project-001-402417)$ gcloud config get-value project
Your active configuration is: [cloudshell-23188]
test-project-001-402417
student@cloudshell:~ (test-project-001-402417)$

Tetapkan variabel lingkungan PROJECT_ID:

PROJECT_ID=$(gcloud config get-value project)

Aktifkan semua layanan yang diperlukan:

gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       geminidataanalytics.googleapis.com \
                       cloudaicompanion.googleapis.com \
                       aiplatform.googleapis.com

Output yang diharapkan

student@cloudshell:~ (test-project-001-402417)$ gcloud config set project test-project-001-402417
Updated property [core/project].
student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-14650]
student@cloudshell:~ (test-project-001-402417)$ 
student@cloudshell:~ (test-project-001-402417)$ gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       geminidataanalytics.googleapis.com \
                       cloudaicompanion.googleapis.com \
                       aiplatform.googleapis.com
Operation "operations/acat.p2-4470404856-1f44ebd8-894e-4356-bea7-b84165a57442" finished successfully.

4. Men-deploy AlloyDB

Buat cluster dan instance utama AlloyDB. Anda dapat men-deploy-nya menggunakan skrip yang sudah disiapkan yang akan men-deploy semua resource yang diperlukan atau Anda dapat melakukannya langkah demi langkah sendiri dengan mengikuti dokumentasi.

Deploy AlloyDB Menggunakan Skrip Otomatis

Pendekatan ini menggunakan skrip otomatis untuk men-deploy cluster AlloyDB dan memberikan informasi yang diperlukan untuk mulai menggunakan resource yang di-deploy.

Skrip ini dirancang untuk berfungsi dengan jaringan default tempat skrip membuat komponen yang diperlukan untuk IP pribadi AlloyDB. Jika Anda memiliki penyiapan jaringan yang disesuaikan dan berencana menggunakan nama dan alokasi cluster yang berbeda, gunakan panduan dari dokumentasi AlloyDB.

Di terminal Cloud Shell, jalankan perintah untuk meng-clone skrip deployment dari repositori.

REPO_NAME="codelabs"
REPO_URL="https://github.com/GoogleCloudPlatform/$REPO_NAME"
SOURCE_DIR="alloydb-querydata"

git clone --no-checkout --filter=blob:none --depth=1 $REPO_URL

cd $REPO_NAME
git sparse-checkout set $SOURCE_DIR
git checkout
cd $SOURCE_DIR

Jalankan skrip deployment.

./deploy_alloydb.sh --public-ip

Skrip akan memerlukan waktu beberapa saat untuk dijalankan - biasanya sekitar 5-7 menit dan men-deploy cluster AlloyDB serta instance utama dengan IP publik dan pribadi. IP publik hanya tersedia untuk jaringan yang diizinkan atau dengan menggunakan proxy Auth AlloyDB. Anda dapat membaca lebih lanjut tentang IP publik dalam dokumentasi. Sebagai output, skrip harus memberikan informasi tentang cluster AlloyDB yang di-deploy. Perlu diketahui bahwa sandi Anda akan berbeda - catat sandi tersebut di suatu tempat untuk digunakan pada masa mendatang.

...
<redacted>
...
Creating primary instance: alloydb-aip-01-pr (8 vCPUs for TRIAL cluster)
Operation ID: operation-1765988049916-646282264938a-bddce198-9f248715
Creating instance...done.                                                                                                                                                                                                             
----------------------------------------
Deployment Process Completed
Cluster:  alloydb-aip-01 (TRIAL)
Instance: alloydb-aip-01-pr
Region:   us-central1
Initial Password: JBBoDTgixzYwYpkF (if new cluster)
----------------------------------------
 

Anda juga dapat melihat cluster baru dan instance utama di konsol web

5. Menyiapkan Database

Anda perlu mengaktifkan integrasi Vertex AI untuk menggunakan fungsi dan operator AI, mengaktifkan Data Access API, dan membuat database untuk set data contoh.

Memberikan Izin yang Diperlukan ke AlloyDB

Tambahkan izin Vertex AI ke agen layanan AlloyDB.

Buka tab Cloud Shell lain menggunakan tanda "+" di bagian atas.

Di tab Cloud Shell baru, jalankan:

PROJECT_ID=$(gcloud config get-value project)
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

Output konsol yang diharapkan:

student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-11039]
student@cloudshell:~ (test-project-001-402417)$ gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"
Updated IAM policy for project [test-project-001-402417].
bindings:
- members:
  - serviceAccount:[e-mail]
  role: roles/aiplatform.user
- members:
...
etag: BwYIEbe_Z3U=
version: 1
 

Aktifkan Data Access API

Anda harus mengaktifkan Data Access API di cluster AlloyDB agar dapat menggunakan alat MCP seperti execute_sql.

Di tab terminal yang sama, jalankan.

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
curl -X PATCH \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 https://alloydb.googleapis.com/v1alpha/projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER/instances/$ADBCLUSTER-pr?updateMask=dataApiAccess \
 -d '{
   "dataApiAccess": "ENABLED",
 }'

Aktifkan Autentikasi IAM

Kita akan menggunakan autentikasi IAM untuk alat agentik kita dan hal ini mengharuskan autentikasi IAM diaktifkan pada instance dan menambahkan diri Anda sebagai pengguna database. Sebelum mengaktifkan autentikasi IAM di tingkat instance, tunggu hingga langkah sebelumnya yang mengaktifkan API akses data selesai. Status instance Anda harus berwarna hijau.

Kita mulai dengan mengaktifkan IAM di tingkat instance. Di tab terminal yang sama, jalankan.

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
gcloud beta alloydb instances update $ADBCLUSTER-pr \
   --database-flags password.enforce_complexity=on,alloydb.iam_authentication=on \
   --region=$REGION \
   --cluster=$ADBCLUSTER \
   --project=$PROJECT_ID \
   --update-mode=FORCE_APPLY

Tambahkan diri Anda sebagai pengguna AlloyDB:

REGION=us-central1
ADBCLUSTER=alloydb-aip-01
gcloud alloydb users create $(gcloud config get-value account) \
--cluster=$ADBCLUSTER \
--superuser=true \
--region=$REGION \
--type=IAM_BASED

Tutup tab dengan menjalankan perintah "exit" di tab:

exit

Menghubungkan ke AlloyDB Studio

Di bab-bab berikutnya, semua perintah SQL yang memerlukan koneksi ke database dapat dijalankan di AlloyDB Studio. T

Buka halaman Cluster di AlloyDB untuk Postgres.

Buka antarmuka konsol web untuk cluster AlloyDB Anda dengan mengklik instance utama.

Kemudian, klik AlloyDB Studio di sebelah kiri:

Pilih database postgres dan autentikasi IAM. Kemudian, klik tombol "Autentikasi".

Tindakan ini akan membuka antarmuka AlloyDB Studio. Untuk menjalankan perintah di database, klik tab "Untitled Query" di sebelah kanan.

Tindakan ini akan membuka antarmuka tempat Anda dapat menjalankan perintah SQL

Buat Database

Mulai cepat pembuatan database.

Di Editor AlloyDB Studio, jalankan perintah berikut.

Buat database:

CREATE DATABASE quickstart_db

Output yang diharapkan:

Statement executed successfully

Hubungkan ke quickstart_db

Periksa apakah database Anda dibuat dengan menghubungkannya. Hubungkan kembali ke studio menggunakan tombol untuk mengganti pengguna/database.

Pilih database quickstart_db baru dari daftar dropdown dan gunakan autentikasi IAM yang sama.

Tindakan ini akan membuka koneksi baru tempat Anda dapat bekerja dengan objek dari database quickstart_db. Di sana, Anda dapat memeriksa skema dan data yang diimpor serta menggunakan set konteks QueryData.

6. Data Sampel

Sekarang Anda perlu membuat objek di database dan memuat data. Anda akan menggunakan set data perusahaan pengiriman fiktif Cymbal Shipping. Aplikasi ini memiliki data fiktif tentang barang, truk, permintaan, dan perjalanan truk, beserta pengemudi fiktif.

Membuat Bucket Penyimpanan

Anda akan menggunakan Google SDK (gcloud) untuk mengimpor data dari repositori yang di-clone ke database AlloyDB. Anda harus membuat bucket Cloud Storage untuk itu dan memberikan akses ke akun layanan AlloyDB. Atau, Anda selalu dapat mencoba melakukannya menggunakan konsol web, seperti yang dijelaskan dalam dokumentasi.

Di terminal Google Cloud Shell, jalankan:

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
gcloud storage buckets create gs://$PROJECT_ID-import --project=$PROJECT_ID --location=$REGION
gcloud storage buckets add-iam-policy-binding gs://$PROJECT_ID-import --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" --role=roles/storage.objectViewer

Memuat Data

Langkah selanjutnya adalah memuat data. Dump SQL terkompresi kita berada di folder repositori yang di-clone. Perintah berikut mengasumsikan Anda menggunakan direktori beranda sebagai titik awal saat meng-clone repositori pada langkah sebelumnya saat membuat cluster AlloyDB.

Salin dump SQL yang dikompresi ke bucket penyimpanan baru:

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
cd ~/$REPO_NAME/$SOURCE_DIR
gcloud storage cp ~/$REPO_NAME/$SOURCE_DIR/postgres_dump.sql.gz  gs://$PROJECT_ID-import

Kemudian, muat data ke database quickstart_db:

PROJECT_ID=$(gcloud config get-value project)
CLUSTER_NAME=alloydb-aip-01
REGION=us-central1
gcloud alloydb clusters import $CLUSTER_NAME  --region=us-central1 --database=quickstart_db --gcs-uri=gs://$PROJECT_ID-import/postgres_dump.sql.gz --project=$PROJECT_ID --sql

Perintah ini akan memuat set data sampel ke database quickstart_db. Anda dapat memverifikasi tabel dan data menggunakan AlloyDB Studio.

7. Menggunakan Agen Data

Mari kita mulai dari agen AI contoh yang dibuat menggunakan Google ADK untuk Python dan terhubung ke instance AlloyDB menggunakan MCP Toolbox untuk database.

Menginstal MCP Toolbox for Databases

MCP Toolbox for Databases adalah project open source yang menyediakan dukungan MCP untuk beberapa mesin database, termasuk AlloyDB for PostgreSQL. Anda dapat membaca tentang MCP Toolbox di dokumentasi.

Anda perlu mendownload software versi terbaru untuk platform Anda. Untuk versi terbaru, periksa halaman rilis. Contoh berikut menunjukkan cara mendownload MCP Toolbox versi 31 ke Cloud Shell.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
cd ~/$REPO_NAME/$SOURCE_DIR
export VERSION=0.31.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

Anda harus menyiapkan file konfigurasi untuk toolbox. Kita memiliki file tools.yaml.example contoh di direktori saat ini dan akan menyiapkan file tools.yaml dengan mengganti dua placeholder dengan project ID dan region.

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
sed -e "s/##PROJECT_ID##/$PROJECT_ID/g" \
    -e "s/##REGION##/$REGION/g" \
    tools.yaml.example > tools.yaml

Mulai MCP Toolbox for Databases

Sekarang Anda dapat memulai toolbox MCP dengan file konfigurasi yang telah disiapkan.

Buka tab baru di Google Cloud Shell dengan menekan tombol "+" di bagian atas antarmuka Google Cloud Shell.

Di tab baru, beralihlah ke direktori dengan file biner toolbox dan file konfigurasi tools.yaml, lalu mulai server MCP.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
cd ~/$REPO_NAME/$SOURCE_DIR
./toolbox --config tools.yaml

Anda akan melihat "Server ready to serve!" di output yang mirip dengan berikut ini.

2026-03-30T10:28:03.614374-04:00 INFO "Initialized 1 sources: cymbal-logistics-sql-source"
2026-03-30T10:28:03.614517-04:00 INFO "Initialized 0 authServices: "
2026-03-30T10:28:03.614531-04:00 INFO "Initialized 0 embeddingModels: "
2026-03-30T10:28:03.614657-04:00 INFO "Initialized 2 tools: execute_sql_tool, list_cymbal_logistics_schemas_tool"
2026-03-30T10:28:03.614711-04:00 INFO "Initialized 1 toolsets: default"
2026-03-30T10:28:03.614723-04:00 INFO "Initialized 0 prompts: "
2026-03-30T10:28:03.614779-04:00 INFO "Initialized 1 promptsets: default"
2026-03-30T10:28:03.616214-04:00 INFO "Server ready to serve!"

Periksa kode sumber Agen

Di tab pertama di folder repositori yang di-clone, tinjau kode agen menggunakan editor Google Cloud Shell.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
edit ~/$REPO_NAME/$SOURCE_DIR/data_agent/agent.py

Anda dapat melihat di agen bahwa kita memiliki bagian untuk server MCP Google Cloud untuk AlloyDB. Kami menyediakan endpoint sebagai MCP_SERVER_URL, autentikasi, ID project, dan menambahkannya ke toolset MCP.

MCP_SERVER_URL = "http://127.0.0.1:5000"
creds, project_id = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
if not creds.valid:
    creds.refresh(GoogleAuthRequest())

print(f"Authenticated as project: {project_id}")

mcp_toolset = ToolboxToolset(
    server_url=MCP_SERVER_URL,
)

Dalam kode agen, rangkaian alat MCP disertakan sebagai parameter tools untuk agen. Selain itu, ada nama cluster dan instance, region, dan database sebagai variabel untuk perintah agen.

MODEL_ID = "gemini-3-flash-preview"
cluster_name="alloydb-aip-01"
instance_name="alloydb-aip-01-pr"
location="us-central1"
database_name="quickstart_db"

# Agent configuration

root_agent = Agent(
    model=MODEL_ID,
    name='root_agent',
    description='A helpful assistant for analyst requests.',
    instruction=f"""
    Answer user questions to the best of your knowledge using provided tools.
    Do not try to generate non-existent data but use the grounded data from the database.
    When you answer questions about Cymbal Logistic activity
    use the toolset to run query in the AlloyDB cluster {cluster_name} instance {instance_name} in the location {location}
    in the project {project_id} in the database {database_name}
    """,
    tools=[mcp_toolset],
)

Setelah memeriksa kode, kembali ke terminal dengan menekan tombol "Open terminal" di kanan atas jendela editor.

Mulai Agen

Sekarang Anda dapat memulai agen dalam mode interaktif menggunakan antarmuka web Google ADK. Antarmuka web ADK menyediakan cara mudah untuk menguji dan memecahkan masalah alur kerja agen.

Pertama, mari kita instal semua paket yang diperlukan untuk Python menggunakan pengelola paket uv.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
cd ~/$REPO_NAME/$SOURCE_DIR
uv sync

Setelah semua paket diinstal, Anda perlu menambahkan file .env ke direktori agen untuk mengarahkannya agar menggunakan Vertex AI untuk semua komunikasi dengan model AI.

echo "GOOGLE_GENAI_USE_VERTEXAI=true" > data_agent/.env
echo "GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project -q)" >> data_agent/.env
echo "GOOGLE_CLOUD_LOCATION=global" >> data_agent/.env

Kemudian, Anda dapat memulai agen

uv run adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'

Anda akan melihat output seperti berikut dengan endpoint seperti http://127.0.0.1:8000 .

Anda dapat mengklik URL tersebut di cloud shell dan URL akan membuka jendela pratinjau di tab browser terpisah tempat Anda memilih data_agent dari daftar drop-down di sebelah kiri.

Di antarmuka web ADK, Anda dapat memposting pertanyaan di kanan bawah dan melihat alur eksekusi lengkap termasuk rekaman aktivitas untuk setiap langkah di sisi kanan.

8. Menguji NL2SQL tanpa QueryData untuk AlloyDB

Agen memungkinkan Anda mengajukan pertanyaan dalam bentuk bebas menggunakan bahasa alami dan agen akan menggunakan toolbox MCP untuk database sebagai alat untuk menjawab pertanyaan. Pertanyaan diposting di kanan bawah dan jawaban dengan semua panggilan ke alat akan muncul di bagian atas.

Anda sedang bekerja dengan data operasional untuk perusahaan pengiriman yang memiliki informasi tentang permintaan pengiriman, truk, pengemudi, dan perjalanan yang dilakukan oleh pengemudi. Pertanyaan pertama adalah tentang jumlah perjalanan yang dilakukan pada Februari 2026.

Di kolom input di kanan bawah, ketik berikut ini, lalu tekan enter.

Hello, can you tell me how many trips we've done in February?

Agen akan menjalankan beberapa panggilan alat untuk mengidentifikasi tabel yang tepat dalam skema menggunakan list_cymbal_logistics_schemas_tool dan execute_sql_tool yang menjalankan beberapa pernyataan SQL untuk mendapatkan data yang tepat.

Pada akhirnya, hasil yang benar akan ditampilkan setelah membuat kueri yang tepat dan menjalankannya di database.

Kami menyelesaikan 108 perjalanan pada Februari 2026. Catatan kami menunjukkan bahwa tidak ada perjalanan yang dijadwalkan atau diselesaikan pada Februari 2025.

Anda dapat melihat fungsi setiap panggilan alat dengan mengklik eksekusi alat. Misalnya, berikut kueri yang dijalankan untuk mendapatkan hasil.

Coba permintaan sederhana lainnya menggunakan antarmuka web ADK dan lihat cara ADK menjalankan kueri yang berbeda untuk mendapatkan hasil.

Hentikan agen dengan menekan ctrl+c di terminal. Anda dapat menutup tab browser dengan antarmuka web ADK.

Anda juga dapat menghentikan MCP Toolbox di tab kedua dengan menekan pintasan tombol ctrl+c yang sama dan menutup tab kedua.

Pada langkah berikutnya, kita akan membuat konteks QueryData untuk meningkatkan respons dan performa NL2SQL.

9. Membangun QueryData ContextSet

Pada langkah sebelumnya, Anda dapat melihat bahwa model AI melakukan beberapa panggilan ke skema informasi database untuk mengetahui tabel dan kolom yang harus digunakan untuk membuat kueri SQL. Untuk meningkatkan performa, akurasi, dan membuat hasil lebih dapat diprediksi, kami akan menambahkan konteks QueryData yang menentukan kueri mana yang harus dijalankan sebagai respons terhadap permintaan tertentu.

Membuat Template Bertarget

QueryData ContextSet adalah file JSON dengan template kueri dan aspek yang memberikan data dan petunjuk yang diperlukan kepada model AI untuk menggunakan kueri SQL atau bagian kueri SQL yang benar untuk mencapai tujuan yang diminta berdasarkan pola kueri dan struktur data.

Anda mulai dari template yang ditargetkan. Buat file menggunakan editor Cloud Shell. Di terminal Cloud Shell, jalankan.

edit ~/$REPO_NAME/$SOURCE_DIR/data_agent/querydata_cymbal_contextset.json

Lalu, masukkan template untuk kueri natural language yang telah kita gunakan di bab sebelumnya - "Berapa banyak perjalanan yang telah kita lakukan pada bulan Februari?"

{
  "templates": [
    {
      "nl_query": "How many trips we've done in February?",
      "sql": "SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE('February 2026', 'Month YYYY') AND departure_time < TO_DATE('February 2026', 'Month YYYY') + INTERVAL '1 month'",
      "intent": "Count trips done in a given month like February 2026",
      "manifest": "How many trips we've done in a given month",
      "parameterized": {
        "parameterized_intent": "How many trips we've done in $1",
        "parameterized_sql": "SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE($1, 'Month YYYY') AND departure_time < TO_DATE($1, 'Month YYYY') + INTERVAL '1 month'"
      }
    }
  ]
}

Kemudian, download template ke komputer Anda dari Cloud Shell menggunakan tombol download.

Memuat Set Konteks QueryData

Untuk menggunakan set konteks QueryData, kita perlu menguploadnya ke database.

Buka AlloyDB Studio. Di panel kiri di bagian bawah, Anda akan melihat QueryData Context dan tiga titik.

Klik tiga titik tersebut, lalu pilih Buat Konteks. Tindakan ini akan membuka dialog tempat Anda memasukkan

• Nama: cymbal_context_set
• Deskripsi: Cymbal Logistic Query Data
• Upload file konteks: klik tombol "Browse" dan pilih file JSON Anda dengan QueryData ContextSet

Saat Anda menekan tombol simpan, mungkin perlu waktu beberapa saat untuk melakukan inisialisasi penyimpanan konteks jika Anda melakukannya untuk pertama kalinya.

Anda akan dapat melihat konteks yang didownload dan jika Anda mengklik tiga tombol vertikal di sebelah kanan, Anda akan melihat tindakan yang tersedia. Di bab berikutnya, kita akan mulai dari tindakan "Test context".

10. Menguji Set Konteks QueryData

Template pengujian

Gunakan tindakan "Test context" untuk menguji konteks kita di AlloyDB Studio. Saat Anda mengklik "Test context", jendela editor AlloyDB Studio baru akan terbuka dengan judul "cymbal_context_set" dan undangan pembuatan SQL Gemini berjudul "Generate SQL using QueryData context: cymbal_context_set ". Klik pembuatan SQL dan ketik

Hello, can you tell me how many trips we've done in February?

Kemudian, saat SQL yang dihasilkan mendorong tombol "Insert".

Anda akan melihat kueri yang sama persis dengan yang kita masukkan ke template konteks sebelumnya.

-- How many trips we've done in February?
SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE('February 2026', 'Month YYYY') AND departure_time < TO_DATE('February 2026', 'Month YYYY') + INTERVAL '1 month'

Coba ganti bulan dengan "Januari" dan periksa pernyataan SQL yang dihasilkan. Parameter ini akan menggunakan bulan sebagai parameter untuk maksud berparameter dan menyesuaikan pernyataan SQL secara otomatis.

Membangun Facet QueryData

Kami mencoba template untuk kueri dan template tersebut berfungsi saat kami mengetahui jenis permintaan pengguna yang kami harapkan. Namun, terkadang kita perlu memandu hanya sebagian kueri seperti kondisi atau filter saat kita lebih memilih urutan tertentu atau klausa tertentu untuk digunakan dalam maksud yang didefinisikan ulang.

Misalnya, jika kita meminta untuk menampilkan data "bulan lalu", kita ingin mendapatkan laporan untuk bulan kalender terakhir dari tanggal 1 hingga hari terakhir bulan tersebut, bukan untuk 30 hari terakhir.

Kita dapat menambahkan aspek tersebut sebagai cuplikan SQL ke konfigurasi ContextSet bersama dengan template yang sebelumnya kita tambahkan. Buka querydata_cymbal_contextset.json.

edit ~/$REPO_NAME/$SOURCE_DIR/data_agent/querydata_cymbal_contextset.json

Lalu, tambahkan aspek setelah template yang sudah ada. Konten yang dihasilkan dalam file harus berupa berikut ini

{
  "templates": [
    {
      "nl_query": "How many trips we've done in February?",
      "sql": "SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE('February 2026', 'Month YYYY') AND departure_time < TO_DATE('February 2026', 'Month YYYY') + INTERVAL '1 month'",
      "intent": "Count trips done in a certain month like February 2026",
      "manifest": "How many trips we've done in a given month",
      "parameterized": {
        "parameterized_intent": "How many trips we've done in $1",
        "parameterized_sql": "SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE($1, 'Month YYYY') AND departure_time < TO_DATE($1, 'Month YYYY') + INTERVAL '1 month'"
      }
    }
  ],
  "facets": [
    {
      "sql_snippet": "departure_time >=date_trunc('month', current_date - interval '1 month') AND departure_time < date_trunc('month', current_date)",
      "intent": "last month",
      "manifest": "Records for the previous calendar month",
      "parameterized": {
        "parameterized_intent": "previous calendar month",
        "parameterized_sql_snippet": "departure_time >=date_trunc('month', current_date - interval '1 month') AND departure_time < date_trunc('month', current_date)"
      }
    }
  ]
}

Simpan file dan upload ke komputer Anda.

Kemudian, gunakan tindakan Query context "Edit context" dan upload file yang telah diubah untuk menggantikan set konteks lama dengan yang baru.

Sekarang coba gunakan konteks pengujian lagi dan buat pernyataan SQL menggunakan maksud "bulan lalu". Misalnya, jika Anda membuat SQL untuk frasa "show trucks trips for the last month" it will be using the condition we provided as a facet in our cymbal_context.json file.

Anda akan mendapatkan sesuatu seperti berikut:

-- show trucks trips for the last month
SELECT COUNT(*) FROM truck_trips WHERE departure_time >=date_trunc('month', current_date - interval '1 month') AND departure_time < date_trunc('month', current_date)

Sekarang, bagaimana cara menggunakannya dengan Agen AI? Di bab berikutnya, kita akan membuat konteks Query Data tersedia untuk Agen AI.

11. QueryData dengan Agen AI

Anda akan menggunakan Agen Data yang sama, tetapi sekarang toolbox MCP akan dikonfigurasi untuk menggunakan QueryData ContextSet.

Menyiapkan dan memulai MCP Toolbox for Databases

Kita memerlukan file konfigurasi baru untuk MCP Toolbox yang akan menggunakan Gemini Data Analytics API dan AlloyDB sebagai sumber database.

Jalankan di terminal:

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
sed -e "s/##PROJECT_ID##/$PROJECT_ID/g" \
    -e "s/##REGION##/$REGION/g" \
    querydata.yaml.example > querydata.yaml

Beralih ke editor dan temukan file querydata.yaml. File konfigurasi querydata.yaml akan terlihat seperti berikut, kecuali project ID dan region yang akan mencerminkan lingkungan Anda. Namun, Anda tetap perlu memperbarui nilai contextSetId dan mengganti placeholder "<add-context-set-id>" dengan nilai dari konsol.

kind: sources
name: gda-api-source
type: cloud-gemini-data-analytics
projectId: test-project-001-402417
---
kind: tools
name: cloud_gda_query_tool
type: cloud-gemini-data-analytics-query
source: gda-api-source
location: "us-central1"
description: Use this tool to send natural language queries to the Gemini Data Analytics API and receive SQL, natural language answers, and explanations.
context:
  datasourceReferences:
    alloydb:
      databaseReference:
        projectId: "test-project-001-402417"
        region: "us-central1"
        clusterId: "alloydb-aip-01"
        instanceId: "alloydb-aip-01-pr"
        databaseId: "quickstart_db"
      agentContextReference:
        contextSetId: "<add-context-set-id>"
generationOptions:
  generateQueryResult: true
  generateNaturalLanguageAnswer: true
  generateExplanation: true
  generateDisambiguationQuestion: true

Untuk menemukan ID ContextSet, klik tombol edit untuk set konteks Anda seperti yang ditunjukkan pada gambar.

Anda akan melihat ID set konteks di bagian atas di tab baru di sebelah kanan.

Jalur lengkap tersebut harus dimasukkan untuk menggantikan placeholder "<add-context-set-id>" dalam file querydata.yaml.

Beralih kembali ke terminal.

Buka tab baru di Google Cloud Shell dengan menekan tombol "+" di bagian atas antarmuka Google Cloud Shell.

Di tab baru, beralihlah ke direktori dengan file biner toolbox dan file konfigurasi tools.yaml, lalu mulai server MCP.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
cd ~/$REPO_NAME/$SOURCE_DIR
./toolbox --config querydata.yaml

Menjalankan agen ADK

Di tab Cloud Shell pertama, mulai agen.

uv run adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'

Saat dimulai, klik lagi link http://127.0.0.1:8000 .

Anda akan melihat antarmuka agen pratinjau web ADK yang sudah dikenal. Kirimkan kueri yang sama persis seperti terakhir kali.

Hello, can you tell me how many trips we've done in February?

Dan lihat alur kerja agen. Jika semuanya dikonfigurasi dengan benar, Anda akan melihat sesuatu seperti berikut.

Permintaan yang memerlukan beberapa giliran terakhir kali telah diubah menjadi satu panggilan ke alat MCP dan dieksekusi menggunakan pernyataan SQL yang dapat diprediksi.

Anda dapat menguji aspek yang dikonfigurasi menggunakan permintaan seperti

how trucks trips for the last month

Di output, jika Anda mengklik tindakan alat, Anda dapat melihat bahwa alat tersebut menggunakan alat yang sama dan menerapkan aspek untuk mendapatkan hasil.

Dengan demikian, lab ini telah selesai. Semoga Anda dapat mempelajari semua contoh dan mempelajari cara menggunakan QueryData untuk AlloyDB. Teknologi yang disediakan membantu membuat beban kerja agentic dan pembuatan SQL Anda dapat diprediksi dan andal.

12. Membersihkan lingkungan

Untuk mencegah biaya yang tidak terduga, sebaiknya bersihkan resource sementara. Cara yang paling andal adalah menghapus project tempat Anda menguji alur kerja. Namun, Anda dapat membatasi diri dengan menghapus setiap resource, seperti AlloyDB.

Hancurkan instance dan cluster AlloyDB setelah Anda selesai mengerjakan lab.

Hapus cluster AlloyDB dan semua instance

Jika Anda telah menggunakan versi uji coba AlloyDB. Jangan hapus cluster uji coba jika Anda berencana menguji lab dan resource lain menggunakan cluster uji coba. Anda tidak akan dapat membuat cluster uji coba lain dalam project yang sama.

Cluster tersebut dihancurkan dengan opsi paksa yang juga akan menghapus semua instance milik cluster tersebut.

Di Cloud Shell, tentukan variabel project dan lingkungan jika koneksi Anda terputus dan semua setelan sebelumnya hilang:

gcloud config set project <your project id>

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
export PROJECT_ID=$(gcloud config get-value project)

Hapus cluster:

gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force

Catatan: Dibutuhkan waktu 3-5 menit untuk menjalankan perintah

Output konsol yang diharapkan:

student@cloudshell:~ (test-project-001-402417)$ gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force
All of the cluster data will be lost when the cluster is deleted.

Do you want to continue (Y/n)?  Y

Operation ID: operation-1697820178429-6082890a0b570-4a72f7e4-4c5df36f
Deleting cluster...done.   

Hapus Cadangan AlloyDB

Hapus semua cadangan AlloyDB untuk cluster:

Catatan: Perintah ini akan menghancurkan semua cadangan data untuk cluster dengan nama yang ditentukan dalam variabel lingkungan

for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done

Output konsol yang diharapkan:

student@cloudshell:~ (test-project-001-402417)$ for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done
Operation ID: operation-1697826266108-60829fb7b5258-7f99dc0b-99f3c35f
Deleting backup...done.                                                                                                                                                                                                                                                            

13. Selamat

Selamat, Anda telah menyelesaikan codelab.

Yang telah kita bahas

• Cara membuat cluster AlloyDB dan mengimpor data contoh
• Cara mengaktifkan AlloyDB Data Access API
• Cara mengaktifkan QueryData untuk AlloyDB
• Cara membuat template
• Cara menggunakan penelusuran berfaset
• Cara menggunakan QueryData dengan Agen AI

14. Survei

Output:

Bagaimana Anda akan menggunakan tutorial ini?

Hanya membacanya Membaca dan menyelesaikan latihannya