Method: projects.locations.queryData

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

string

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 (QueryDataContext)
  },
  "generationOptions": {
    object (GenerationOptions)
  }
}
Kolom
prompt

string

Wajib. Kueri bahasa alami yang akan digunakan untuk membuat kueri. Contoh: "Apa saja 5 produk terlaris bulan ini?"

context

object (QueryDataContext)

Wajib. Konteks untuk kueri data, termasuk sumber data yang akan digunakan.

generationOptions

object (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 (ExecutedQueryResult)
  },
  "naturalLanguageAnswer": string,
  "disambiguationQuestion": [
    string
  ],
  "pipelineDebugInfo": {
    object
  },
  "tokenUsage": {
    object (TokenUsage)
  }
}
Kolom
generatedQuery

string

Kueri yang dihasilkan untuk perintah pengguna yang diberikan.

intentExplanation

string

Penjelasan bahasa alami tentang kueri yang dihasilkan. Diisi jika options.generate_explanation bernilai benar dalam permintaan.

queryResult

object (ExecutedQueryResult)

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

string

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[]

string

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

object (Struct format)

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

object (TokenUsage)

Penggunaan token secara keseluruhan untuk permintaan.

Cakupan otorisasi

Memerlukan salah satu cakupan OAuth berikut:

  • https://www.googleapis.com/auth/cloud-platform
  • https://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 (DatasourceReferences)
  },
  "parameterizedSecureViewParameters": {
    object (ParameterizedSecureViewParameters)
  }
}
Kolom
datasourceReferences

object (DatasourceReferences)

Wajib. Referensi sumber data yang akan digunakan untuk kueri.

parameterizedSecureViewParameters

object (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 (Parameter)
    }
  ]
}
Kolom
parameters[]

object (Parameter)

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

string

Wajib. Kunci parameter (misalnya, "userId").

value

string

Wajib. Nilai parameter (misalnya, "123").

GenerationOptions

Opsi untuk mengontrol pembuatan kueri, eksekusi, dan format respons.

Representasi JSON
{
  "generateQueryResult": boolean,
  "generateNaturalLanguageAnswer": boolean,
  "generateExplanation": boolean,
  "generateDisambiguationQuestion": boolean,
  "generateDebugInfo": boolean
}
Kolom
generateQueryResult

boolean

Opsional. Jika true, kueri yang dihasilkan akan dieksekusi, dan data hasil akan ditampilkan dalam respons.

generateNaturalLanguageAnswer

boolean

Opsional. Jika true, jawaban bahasa alami berdasarkan hasil eksekusi kueri akan dibuat dan ditampilkan dalam respons.

generateExplanation

boolean

Opsional. Jika true (benar), penjelasan kueri yang dihasilkan akan ditampilkan dalam respons.

generateDisambiguationQuestion

boolean

Opsional. Jika benar (default ke salah), layanan dapat menampilkan clarifying_question jika kueri input ambigu.

generateDebugInfo

boolean

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 (Column)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "totalRowCount": string,
  "partialResult": boolean,
  "queryExecutionError": string
}
Kolom
columns[]

object (Column)

Kolom dalam kumpulan hasil, secara berurutan.

rows[]

object (Row)

Baris yang ditampilkan oleh kueri.

totalRowCount

string (int64 format)

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

boolean

Setel ke true jika baris yang ditampilkan di queryResult adalah subset dari hasil lengkap. Hal ini dapat terjadi, misalnya, jika eksekusi kueri mencapai batas baris. Jika benar, queryResult tidak berisi semua baris. Untuk mengambil hasil lengkap, pertimbangkan untuk menggunakan generatedQuery di QueryDataResponse dan menjalankannya di lingkungan Anda sendiri.

queryExecutionError

string

Pesan error jika eksekusi kueri gagal.

Kolom

Menjelaskan satu kolom dalam kumpulan hasil.

Representasi JSON
{
  "name": string,
  "type": string
}
Kolom
name

string

Nama kolom.

type

string

Jenis kolom (misalnya, "VARCHAR", "INT64", "TIMESTAMP").

Baris

Menampilkan satu baris dalam kumpulan hasil.

Representasi JSON
{
  "values": [
    {
      object (Value)
    }
  ]
}
Kolom
values[]

object (Value)

Nilai dalam baris, yang sesuai secara posisi dengan kolom.

Nilai

Merepresentasikan satu nilai dalam satu baris.

Representasi JSON
{
  "value": string
}
Kolom
value

string

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

integer

Jumlah total token input yang digunakan dalam permintaan ini.

outputTokenCount

integer

Jumlah total token output yang digunakan dalam permintaan ini.