Pengantar QueryData

QueryData adalah alat bahasa alami ke SQL (NL2SQL) di Conversational Analytics API yang memungkinkan agen dan aplikasi AI Anda mengkueri database operasional menggunakan bahasa alami. Saat aplikasi atau agen mengirimkan pertanyaan menggunakan bahasa alami, QueryData menerjemahkan pertanyaan tersebut menjadi kueri SQL khusus dialek, menjalankan kueri terhadap database Anda, dan menampilkan hasil kueri beserta SQL yang dihasilkan dan penjelasan tentang cara QueryData menafsirkan pertanyaan tersebut.

Untuk mengetahui informasi selengkapnya tentang penggunaan QueryData dengan database Anda, lihat dokumentasi untuk database yang didukung:

Kemampuan utama

QueryData menyediakan kemampuan berikut untuk aplikasi database agentic:

  • Akurasi tinggi: mencapai akurasi hampir 100% pada kueri penting bisnis dengan menggabungkan metadata skema database dengan set konteks yang Anda kelola.
  • Relevansi bisnis: mendasarkan pembuatan SQL pada terminologi domain, definisi metrik, dan logika bisnis organisasi Anda, bukan hanya mengandalkan nama tabel dan kolom mentah.
  • Penjelasan: membuat penjelasan intent yang dapat dibaca manusia bersama dengan kueri SQL yang disintesis dan jawaban bahasa alami sehingga Anda dan pengguna dapat memverifikasi cara QueryData menerjemahkan permintaan.
  • Keamanan data: menerapkan kontrol akses tingkat baris dan melindungi data pengguna dari injeksi perintah menggunakan tampilan aman berparameter di AlloyDB, Cloud SQL untuk MySQL, dan Cloud SQL untuk PostgreSQL.

Kapan harus menggunakan QueryData

QueryData dirancang untuk developer yang membangun aplikasi interaktif dan agen AI yang memerlukan akses cepat, dapat diprediksi, dan akurat ke data database operasional. Misalnya, QueryData ideal untuk kasus penggunaan berikut:

  • Otomatisasi layanan pelanggan: menjawab pertanyaan pengguna dalam jumlah besar seperti "Di mana pesanan saya?" atau "Berapa saldo rekening saya saat ini?"
  • Asisten penelusuran e-commerce dan katalog: membantu pengguna memfilter dan menjelajahi katalog terstruktur dengan pertanyaan multi-kriteria seperti "Tunjukkan laptop ringan dengan RAM minimal 16 GB dan daya tahan baterai lebih dari 10 jam".
  • Operasi lapangan dan alat internal: memungkinkan karyawan mengkueri tingkat inventaris langsung, ketersediaan suku cadang, atau status tiket layanan secara real time.
  • Agentic Workflows multi-agen: mengekspos kueri database terstruktur sebagai alat dalam framework agentic seperti Agent Development Kit (ADK), MCP Toolbox for Databases, atau LangChain.

Cara kerja QueryData

Model bahasa besar (LLM) generik tidak memiliki informasi tentang nilai data pribadi organisasi Anda, nama kolom yang samar, atau aturan bisnis khusus domain. Untuk menjembatani kesenjangan antara cara pengguna mengajukan pertanyaan dan cara database Anda menyimpan data, QueryData menggunakan konteks berlapis berikut:

  • Ontologi skema: deskripsi tabel dan kolom yang diperkaya dalam katalog database atau Knowledge Catalog yang menjelaskan makna bisnis tabel, kolom, kode status, dan hubungan gabungan.
  • Set konteks: koleksi pilihan yang terkait dengan instance database Anda yang menentukan tiga elemen penyusun berikut:
    • Template kueri: pertanyaan bahasa alami representatif yang dipasangkan dengan pernyataan SQL berparameter dan tervalidasi serta penjelasan intent.
    • Facet kueri: predikat SQL modular dan fragmen filter yang digabungkan secara dinamis oleh QueryData dengan template kueri untuk mendukung penelusuran faset tanpa memerlukan template terpisah untuk setiap kombinasi filter.
    • Penelusuran nilai: kueri penelusuran vektor semantik, trigram fuzzy, atau persis yang menautkan frasa informal, sinonim, atau istilah yang salah eja dari pengguna ke nilai dan kolom yang sebenarnya dalam database Anda.

Saat aplikasi Anda memanggil metode projects.locations.queryData di Conversational Analytics API, QueryData akan melakukan langkah-langkah berikut:

  1. Resolusi nilai: menjalankan kueri penelusuran nilai terhadap database Anda untuk memetakan frasa entity dalam perintah (seperti nama kota, kategori produk, atau kode) ke nilai kolom database yang tepat.
  2. Pencocokan intent dan disambiguasi: mencocokkan pertanyaan pengguna dengan template kueri dan faset dalam set konteks Anda, serta dengan ontologi skema Anda. Jika pertanyaan ambigu atau tidak memiliki parameter yang diperlukan, QueryData dapat menampilkan pertanyaan disambiguasi untuk memperjelas maksud pengguna.
  3. Sintesis kueri: menyintesis kueri SQL khusus dialek dengan menggabungkan struktur template yang cocok, faset yang berlaku, dan nilai literal yang di-resolve, atau dengan membuat SQL dari ontologi skema Anda jika tidak ada template yang cocok.
  4. Eksekusi dan respons kueri: mengeksekusi SQL yang dihasilkan terhadap database target dan menampilkan set hasil tabulasi, kueri SQL yang dihasilkan, penjelasan intent, dan ringkasan bahasa alami opsional.

Strategi untuk mencapai akurasi text-to-SQL yang hampir 100%

Mencapai akurasi hampir 100% untuk text-to-SQL adalah proses rekayasa berulang yang dikenal sebagai hill-climbing. Daripada mencoba mengantisipasi setiap kemungkinan pertanyaan pengguna di awal, Anda memulai dengan deskripsi skema dasar, mengevaluasi agen Anda terhadap tolok ukur representatif kueri SQL emas menggunakan EvalBench, lalu menyelesaikan kesenjangan akurasi.

Untuk mengetahui informasi selengkapnya tentang strategi (atau resep) yang direkomendasikan untuk mengatasi kesenjangan akurasi, termasuk diagram arsitektur, contoh SQL, dan tolok ukur evaluasi, lihat Enam resep untuk mencapai akurasi text-to-SQL yang hampir 100% dan coba codelab pendamping untuk mempelajari cara menerapkan resep akurasi text-to-SQL ini.

Singkatnya, keenam resep tersebut adalah sebagai berikut:

  • Resep 0: menginisialisasi set konteks dan menghubungkan aplikasi Anda. Mulailah dengan komentar tabel dan kolom deskriptif dalam skema Anda, lalu hubungkan aplikasi Anda ke QueryData menggunakan library klien Conversational Analytics API atau alat cloud-gemini-data-analytics-query di MCP Toolbox for Databases.
  • Resep 1: memasukkan interpretasi dengan template kueri. Berikan contoh kueri SQL yang divalidasi untuk pertanyaan bisnis yang paling penting, dan generalisasikan ke dalam template SQL berparameter, penjelasan intent berparameter, dan manifes yang menangkap varian pertanyaan yang setara secara semantik.
  • Resep 2: gunakan template faset. Gabungkan template kueri dasar dengan faset kueri modular (kondisi SQL yang dapat digunakan kembali dengan manifes dan intent-nya sendiri) sehingga QueryData dapat menyusun kueri multi-filter secara dinamis tanpa memerlukan template terpisah untuk setiap kombinasi kondisi.
  • Resep 3: memperjelas dengan penelusuran nilai. Tentukan kueri penelusuran nilai untuk menautkan frasa nilai dalam pertanyaan bahasa alami—termasuk terminologi pribadi, sinonim, dan salah eja—ke kolom dan nilai database aktual, dan biarkan QueryData meminta klarifikasi saat sebuah istilah cocok dengan beberapa jenis entitas.
  • Resep 4: mengintegrasikan penelusuran semantik dan operator AI. Gabungkan template dan faset SQL terstruktur dengan penelusuran vektor dan operator AI dalam database (seperti AI.IF dan AI.RANK di AlloyDB) untuk memfilter dan memberi peringkat teks tidak terstruktur atau data multimodal menggunakan kriteria semantik.
  • Resep 5: gunakan tampilan aman berparameter. Terapkan keamanan tingkat baris yang ketat dan lindungi data pengguna dari injeksi perintah dengan mengikat parameter pengguna yang diautentikasi dalam tampilan aman berparameter untuk AlloyDB, Cloud SQL untuk MySQL, dan Cloud SQL untuk PostgreSQL.

Anda dapat menerapkan resep ini secara manual atau mengotomatiskan alur kerja hill-climbing—memperluas set evaluasi, menjalankan evaluasi EvalBench, menganalisis kesenjangan akurasi, dan mengusulkan template, faset, dan penelusuran nilai baru—dengan menggunakan agen rekayasa konteks open source.

Langkah berikutnya