- HTTP 要求
- 路徑參數
- 要求主體
- 回應主體
- 授權範圍
- QueryDataContext
- ParameterizedSecureViewParameters
- 參數
- GenerationOptions
- ExecutedQueryResult
- Column
- Row
- 值
- TokenUsage
根據自然語言使用者查詢,查詢資料。
HTTP 要求
POST https://geminidataanalytics.googleapis.com/v1alpha/{parent=projects/*/locations/*}:queryData
這個網址使用 gRPC 轉碼語法。
路徑參數
| 參數 | |
|---|---|
parent |
這是必要旗標,要生成查詢的父項資源。格式:projects/{project}/locations/{location} |
要求主體
要求主體包含下列結構的資料:
| JSON 表示法 |
|---|
{ "prompt": string, "context": { object ( |
| 欄位 | |
|---|---|
prompt |
這是必要旗標,要生成查詢的自然語言查詢。例如:「本月最暢銷的 5 大產品是哪些?」 |
context |
這是必要旗標,資料查詢的背景資訊,包括要使用的資料來源。 |
generationOptions |
選用。控制查詢生成和執行行為的選項。 |
回應主體
回覆內容包含生成的查詢和相關資訊。
如果成功,回應主體會含有以下結構的資料:
| JSON 表示法 |
|---|
{ "generatedQuery": string, "intentExplanation": string, "queryResult": { object ( |
| 欄位 | |
|---|---|
generatedQuery |
根據指定使用者提示詞生成的查詢。 |
intentExplanation |
以自然語言說明生成的查詢。如果要求中的 options.generate_explanation 為 true,則會填入這個欄位。 |
queryResult |
執行查詢的結果。如果要求中的 options.generate_query_result 或 options.generate_natural_language_answer 為 true,且執行成功或已嘗試執行,則會填入這個欄位。 |
naturalLanguageAnswer |
根據 queryResult,以自然語言回答查詢。如果要求中的 options.generate_natural_language_answer 為 true,且根據 executeSql API 的回應,查詢執行成功,則會填入這個欄位。 |
disambiguationQuestion[] |
如果自然語言查詢中偵測到模糊不清,且 options.generate_disambiguation_question 為 true,這個欄位會包含向使用者提出的問題,以便釐清。傳回的結果代表服務根據模糊輸入內容盡力提供的結果。 |
pipelineDebugInfo |
逐步執行的詳細 pipeline 資訊。只有在 generationOptions.generate_debug_info 為 true 時,系統才會填入資料。僅供偵錯和資訊公開用途。我們不保證這個物件的結構和內容,且隨時可能變更,恕不另行通知。請勿根據這個物件中的欄位編寫正式版程式碼或商業邏輯。 |
tokenUsage |
要求的整體詞元用量。 |
授權範圍
需要下列其中一種 OAuth 範圍:
https://www.googleapis.com/auth/cloud-platformhttps://www.googleapis.com/auth/geminidataanalytics
詳情請參閱Authentication Overview。
QueryDataContext
查詢時要使用的資料來源和背景資訊參照。
| JSON 表示法 |
|---|
{ "datasourceReferences": { object ( |
| 欄位 | |
|---|---|
datasourceReferences |
這是必要旗標,查詢要使用的資料來源參照。 |
parameterizedSecureViewParameters |
選用。參數化安全檢視 (PSV) 的參數。 |
ParameterizedSecureViewParameters
參數化安全檢視 (PSV) 的參數。這些參數用於在 SQL 生成和查詢執行期間,強制執行資料列層級安全性。
| JSON 表示法 |
|---|
{
"parameters": [
{
object ( |
| 欄位 | |
|---|---|
parameters[] |
選用。參數化安全檢視 (PSV) 的具名參數。 |
參數
代表參數化安全檢視的單一參數。
| JSON 表示法 |
|---|
{ "key": string, "value": string } |
| 欄位 | |
|---|---|
key |
這是必要旗標,參數鍵 (例如 |
value |
這是必要旗標,參數值 (例如 |
GenerationOptions
控制查詢生成、執行和回應格式的選項。
| JSON 表示法 |
|---|
{ "generateQueryResult": boolean, "generateNaturalLanguageAnswer": boolean, "generateExplanation": boolean, "generateDisambiguationQuestion": boolean, "generateDebugInfo": boolean } |
| 欄位 | |
|---|---|
generateQueryResult |
選用。如果設為 true,系統會執行生成的查詢,並在回覆中傳回結果資料。 |
generateNaturalLanguageAnswer |
選用。如果設為 true,系統會根據查詢執行結果生成自然語言答案,並在回應中傳回。 |
generateExplanation |
選用。如果設為 true,系統會在回應中傳回生成查詢的說明。 |
generateDisambiguationQuestion |
選用。如果設為 true (預設為 false),當輸入查詢不明確時,服務可能會傳回 clarifying_question。 |
generateDebugInfo |
選用。如果設為 true (預設為 false),則會傳回內部偵錯資訊。 |
ExecutedQueryResult
查詢執行結果。這項設計適用於所有方言。
| JSON 表示法 |
|---|
{ "columns": [ { object ( |
| 欄位 | |
|---|---|
columns[] |
結果集中的資料欄,依序排列。 |
rows[] |
查詢傳回的資料列。 |
totalRowCount |
完整結果集中的資料列總數 (如已知)。這可能是預估值或精確值。注意:如果在執行查詢時套用內部限制 (例如 LIMIT 1000),防止資料移轉量過多,這個計數會反映截斷的結果大小,而非不受限制的資料表結果大小。 |
partialResult |
如果 |
queryExecutionError |
查詢執行失敗時顯示的錯誤訊息。 |
欄
說明結果集中的單一資料欄。
| JSON 表示法 |
|---|
{ "name": string, "type": string } |
| 欄位 | |
|---|---|
name |
資料欄的名稱。 |
type |
資料欄類型 (例如「VARCHAR」、「INT64」、「TIMESTAMP」)。 |
列
代表結果集中的單一資料列。
| JSON 表示法 |
|---|
{
"values": [
{
object ( |
| 欄位 | |
|---|---|
values[] |
資料列中的值,位置與資料欄相對應。 |
值
代表資料列中的單一值。
| JSON 表示法 |
|---|
{ "value": string } |
| 欄位 | |
|---|---|
value |
儲存格值,以字串格式表示。時間戳記可以設定格式,例如使用 RFC3339Nano。如果值不為空值,系統就會使用這個欄位。 |
TokenUsage
追蹤要求的整體詞元用量。
| JSON 表示法 |
|---|
{ "inputTokenCount": integer, "outputTokenCount": integer } |
| 欄位 | |
|---|---|
inputTokenCount |
這項要求使用的輸入詞元總數。 |
outputTokenCount |
這項要求使用的輸出詞元總數。 |