- Permintaan HTTP
- Parameter jalur
- Isi permintaan
- Isi respons
- Cakupan otorisasi
- QueryDataContext
- ParameterizedSecureViewParameters
- Parameter
- GenerationOptions
- ExecutedQueryResult
- Kolom
- Baris
- Nilai
- TokenUsage
Membuat kueri data dari kueri pengguna bahasa alami.
Permintaan HTTP
POST https://geminidataanalytics.googleapis.com/v1alpha/{parent=projects/*/locations/*}:queryData
URL menggunakan sintaks gRPC Transcoding.
Parameter jalur
| Parameter | |
|---|---|
parent |
Wajib. Resource induk yang akan dibuatkan kueri. Format: projects/{project}/locations/{location} |
Isi permintaan
Isi permintaan memuat data dengan struktur berikut:
| Representasi JSON |
|---|
{ "prompt": string, "context": { object ( |
| Kolom | |
|---|---|
prompt |
Wajib. Kueri bahasa alami yang akan digunakan untuk membuat kueri. Contoh: "Apa saja 5 produk terlaris bulan ini?" |
context |
Wajib. Konteks untuk kueri data, termasuk sumber data yang akan digunakan. |
generationOptions |
Opsional. Opsi untuk mengontrol perilaku pembuatan dan eksekusi kueri. |
Isi respons
Respons yang berisi kueri yang dihasilkan dan informasi terkait.
Jika berhasil, isi respons memuat data dengan struktur berikut:
| Representasi JSON |
|---|
{ "generatedQuery": string, "intentExplanation": string, "queryResult": { object ( |
| Kolom | |
|---|---|
generatedQuery |
Kueri yang dihasilkan untuk perintah pengguna yang diberikan. |
intentExplanation |
Penjelasan bahasa alami tentang kueri yang dihasilkan. Diisi jika options.generate_explanation bernilai benar dalam permintaan. |
queryResult |
Hasil dari eksekusi kueri. Diisi jika options.generate_query_result atau options.generate_natural_language_answer bernilai benar dalam permintaan, dan eksekusi berhasil atau dicoba. |
naturalLanguageAnswer |
Jawaban bahasa alami untuk kueri, berdasarkan queryResult. Diisi jika options.generate_natural_language_answer bernilai true dalam permintaan dan eksekusi kueri berhasil berdasarkan respons dari executeSql API. |
disambiguationQuestion[] |
Jika ambiguitas terdeteksi dalam kueri bahasa alami dan options.generate_disambiguation_question bernilai benar (true), kolom ini berisi pertanyaan kepada pengguna untuk klarifikasi. Hasil yang ditampilkan mewakili upaya terbaik layanan berdasarkan input yang ambigu. |
pipelineDebugInfo |
Informasi eksekusi pipeline langkah demi langkah yang mendetail. Hanya diisi jika generationOptions.generate_debug_info bernilai benar (true). Hanya disediakan untuk tujuan proses debug dan transparansi. Struktur dan konten objek ini tidak dijamin dan dapat berubah sewaktu-waktu tanpa pemberitahuan. Jangan menulis kode produksi atau logika bisnis yang bergantung pada kolom dalam objek ini. |
tokenUsage |
Penggunaan token secara keseluruhan untuk permintaan. |
Cakupan otorisasi
Memerlukan salah satu cakupan OAuth berikut:
https://www.googleapis.com/auth/cloud-platformhttps://www.googleapis.com/auth/geminidataanalytics
Untuk mengetahui informasi selengkapnya, lihat Authentication Overview.
QueryDataContext
Referensi ke sumber data dan konteks yang akan digunakan untuk kueri.
| Representasi JSON |
|---|
{ "datasourceReferences": { object ( |
| Kolom | |
|---|---|
datasourceReferences |
Wajib. Referensi sumber data yang akan digunakan untuk kueri. |
parameterizedSecureViewParameters |
Opsional. Parameter untuk Parameterized Secure Views (PSV). |
ParameterizedSecureViewParameters
Parameter untuk Parameterized Secure Views (PSV). Parameter ini digunakan untuk menerapkan keamanan tingkat baris selama pembuatan SQL dan eksekusi kueri.
| Representasi JSON |
|---|
{
"parameters": [
{
object ( |
| Kolom | |
|---|---|
parameters[] |
Opsional. Parameter bernama untuk Tampilan Aman Berparameter (PSV). |
Parameter
Merepresentasikan satu parameter untuk Tampilan Aman yang Diberi Parameter.
| Representasi JSON |
|---|
{ "key": string, "value": string } |
| Kolom | |
|---|---|
key |
Wajib. Kunci parameter (misalnya, |
value |
Wajib. Nilai parameter (misalnya, |
GenerationOptions
Opsi untuk mengontrol pembuatan kueri, eksekusi, dan format respons.
| Representasi JSON |
|---|
{ "generateQueryResult": boolean, "generateNaturalLanguageAnswer": boolean, "generateExplanation": boolean, "generateDisambiguationQuestion": boolean, "generateDebugInfo": boolean } |
| Kolom | |
|---|---|
generateQueryResult |
Opsional. Jika true, kueri yang dihasilkan akan dieksekusi, dan data hasil akan ditampilkan dalam respons. |
generateNaturalLanguageAnswer |
Opsional. Jika true, jawaban bahasa alami berdasarkan hasil eksekusi kueri akan dibuat dan ditampilkan dalam respons. |
generateExplanation |
Opsional. Jika true (benar), penjelasan kueri yang dihasilkan akan ditampilkan dalam respons. |
generateDisambiguationQuestion |
Opsional. Jika benar (default ke salah), layanan dapat menampilkan clarifying_question jika kueri input ambigu. |
generateDebugInfo |
Opsional. Jika benar (default ke salah), menampilkan informasi proses debug internal. |
ExecutedQueryResult
Hasil eksekusi kueri. Desainnya bersifat umum untuk semua dialek.
| Representasi JSON |
|---|
{ "columns": [ { object ( |
| Kolom | |
|---|---|
columns[] |
Kolom dalam kumpulan hasil, secara berurutan. |
rows[] |
Baris yang ditampilkan oleh kueri. |
totalRowCount |
Jumlah total baris dalam kumpulan hasil lengkap, jika diketahui. Jumlah ini mungkin merupakan estimasi atau jumlah pasti. Catatan: jika batas internal (seperti LIMIT 1000) diterapkan selama eksekusi kueri untuk mencegah transfer data yang berlebihan, jumlah ini mencerminkan ukuran hasil yang dipotong, bukan ukuran hasil tabel yang tidak dibatasi. |
partialResult |
Setel ke true jika baris yang ditampilkan di |
queryExecutionError |
Pesan error jika eksekusi kueri gagal. |
Kolom
Menjelaskan satu kolom dalam kumpulan hasil.
| Representasi JSON |
|---|
{ "name": string, "type": string } |
| Kolom | |
|---|---|
name |
Nama kolom. |
type |
Jenis kolom (misalnya, "VARCHAR", "INT64", "TIMESTAMP"). |
Baris
Menampilkan satu baris dalam kumpulan hasil.
| Representasi JSON |
|---|
{
"values": [
{
object ( |
| Kolom | |
|---|---|
values[] |
Nilai dalam baris, yang sesuai secara posisi dengan kolom. |
Nilai
Merepresentasikan satu nilai dalam satu baris.
| Representasi JSON |
|---|
{ "value": string } |
| Kolom | |
|---|---|
value |
Nilai sel, yang direpresentasikan dalam format string. Stempel waktu dapat diformat, misalnya, menggunakan RFC3339Nano. Kolom ini digunakan jika nilainya bukan null. |
TokenUsage
Pelacakan penggunaan token secara keseluruhan untuk permintaan.
| Representasi JSON |
|---|
{ "inputTokenCount": integer, "outputTokenCount": integer } |
| Kolom | |
|---|---|
inputTokenCount |
Jumlah total token input yang digunakan dalam permintaan ini. |
outputTokenCount |
Jumlah total token output yang digunakan dalam permintaan ini. |