Method: projects.locations.queryData

根據自然語言使用者查詢,查詢資料。

HTTP 要求

POST https://geminidataanalytics.googleapis.com/v1beta/{parent=projects/*/locations/*}:queryData

這個網址使用 gRPC 轉碼語法。

路徑參數

參數
parent

string

這是必要旗標,要生成查詢的父項資源。格式:projects/{project}/locations/{location}

要求主體

要求主體包含下列結構的資料:

JSON 表示法
{
  "prompt": string,
  "context": {
    object (QueryDataContext)
  },
  "generationOptions": {
    object (GenerationOptions)
  }
}
欄位
prompt

string

這是必要旗標,要生成查詢的自然語言查詢。例如:「本月最暢銷的 5 大產品是哪些?」

context

object (QueryDataContext)

這是必要旗標,資料查詢的背景資訊,包括要使用的資料來源。

generationOptions

object (GenerationOptions)

選用。控制查詢生成和執行行為的選項。

回應主體

回覆內容包含生成的查詢和相關資訊。

如果成功,回應主體會含有以下結構的資料:

JSON 表示法
{
  "generatedQuery": string,
  "intentExplanation": string,
  "queryResult": {
    object (ExecutedQueryResult)
  },
  "naturalLanguageAnswer": string,
  "disambiguationQuestion": [
    string
  ],
  "pipelineDebugInfo": {
    object
  },
  "tokenUsage": {
    object (TokenUsage)
  }
}
欄位
generatedQuery

string

根據指定使用者提示詞生成的查詢。

intentExplanation

string

以自然語言說明生成的查詢。如果要求中的 options.generate_explanation 為 true,則會填入這個欄位。

queryResult

object (ExecutedQueryResult)

執行查詢的結果。如果要求中的 options.generate_query_result 或 options.generate_natural_language_answer 為 true,且執行成功或已嘗試執行,則會填入這個欄位。

naturalLanguageAnswer

string

根據 queryResult,以自然語言回答查詢。如果要求中的 options.generate_natural_language_answer 為 true,且根據 executeSql API 的回應,查詢執行成功,則會填入這個欄位。

disambiguationQuestion[]

string

如果自然語言查詢中偵測到模糊不清,且 options.generate_disambiguation_question 為 true,這個欄位會包含向使用者提出的問題,以便釐清。傳回的結果代表服務根據模糊輸入內容盡力提供的結果。

pipelineDebugInfo

object (Struct format)

逐步執行的詳細 pipeline 資訊。只有在 generationOptions.generate_debug_info 為 true 時,系統才會填入資料。僅供偵錯和資訊公開用途。我們不保證這個物件的結構和內容,且隨時可能變更,恕不另行通知。請勿根據這個物件中的欄位編寫正式版程式碼或商業邏輯。

tokenUsage

object (TokenUsage)

要求的整體詞元用量。

授權範圍

需要下列其中一種 OAuth 範圍:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/geminidataanalytics

詳情請參閱Authentication Overview。

QueryDataContext

查詢時要使用的資料來源和背景資訊參照。

JSON 表示法
{
  "datasourceReferences": {
    object (DatasourceReferences)
  },
  "parameterizedSecureViewParameters": {
    object (ParameterizedSecureViewParameters)
  }
}
欄位
datasourceReferences

object (DatasourceReferences)

這是必要旗標,查詢要使用的資料來源參照。

parameterizedSecureViewParameters

object (ParameterizedSecureViewParameters)

選用。參數化安全檢視 (PSV) 的參數。

ParameterizedSecureViewParameters

參數化安全檢視 (PSV) 的參數。這些參數用於在 SQL 生成和查詢執行期間,強制執行資料列層級安全性。

JSON 表示法
{
  "parameters": [
    {
      object (Parameter)
    }
  ]
}
欄位
parameters[]

object (Parameter)

選用。參數化安全檢視 (PSV) 的具名參數。

參數

代表參數化安全檢視的單一參數。

JSON 表示法
{
  "key": string,
  "value": string
}
欄位
key

string

這是必要旗標,參數鍵 (例如 "userId")。

value

string

這是必要旗標,參數值 (例如 "123")。

GenerationOptions

控制查詢生成、執行和回應格式的選項。

JSON 表示法
{
  "generateQueryResult": boolean,
  "generateNaturalLanguageAnswer": boolean,
  "generateExplanation": boolean,
  "generateDisambiguationQuestion": boolean,
  "generateDebugInfo": boolean
}
欄位
generateQueryResult

boolean

選用。如果設為 true,系統會執行生成的查詢,並在回覆中傳回結果資料。

generateNaturalLanguageAnswer

boolean

選用。如果設為 true,系統會根據查詢執行結果生成自然語言答案,並在回應中傳回。

generateExplanation

boolean

選用。如果設為 true,系統會在回應中傳回生成查詢的說明。

generateDisambiguationQuestion

boolean

選用。如果設為 true (預設為 false),當輸入查詢不明確時,服務可能會傳回 clarifying_question。

generateDebugInfo

boolean

選用。如果設為 true (預設為 false),則會傳回內部偵錯資訊。

ExecutedQueryResult

查詢執行結果。這項設計適用於所有方言。

JSON 表示法
{
  "columns": [
    {
      object (Column)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "totalRowCount": string,
  "partialResult": boolean,
  "queryExecutionError": string
}
欄位
columns[]

object (Column)

結果集中的資料欄,依序排列。

rows[]

object (Row)

查詢傳回的資料列。

totalRowCount

string (int64 format)

完整結果集中的資料列總數 (如已知)。這可能是預估值或精確值。注意:如果在執行查詢時套用內部限制 (例如 LIMIT 1000),防止資料移轉量過多,這個計數會反映截斷的結果大小,而非不受限制的資料表結果大小。

partialResult

boolean

如果 queryResult 中傳回的資料列是完整結果的子集,請設為 true。舉例來說,如果查詢執行達到資料列上限,就可能發生這種情況。如果為 true,則 queryResult 不會包含所有資料列。如要擷取完整結果,建議您使用 QueryDataResponse 中的 generatedQuery,並在自己的環境中執行。

queryExecutionError

string

查詢執行失敗時顯示的錯誤訊息。

欄

說明結果集中的單一資料欄。

JSON 表示法
{
  "name": string,
  "type": string
}
欄位
name

string

資料欄的名稱。

type

string

資料欄類型 (例如「VARCHAR」、「INT64」、「TIMESTAMP」)。

列

代表結果集中的單一資料列。

JSON 表示法
{
  "values": [
    {
      object (Value)
    }
  ]
}
欄位
values[]

object (Value)

資料列中的值,位置與資料欄相對應。

值

代表資料列中的單一值。

JSON 表示法
{
  "value": string
}
欄位
value

string

儲存格值,以字串格式表示。時間戳記可以設定格式,例如使用 RFC3339Nano。如果值不為空值,系統就會使用這個欄位。

TokenUsage

追蹤要求的整體詞元用量。

JSON 表示法
{
  "inputTokenCount": integer,
  "outputTokenCount": integer
}
欄位
inputTokenCount

integer

這項要求使用的輸入詞元總數。

outputTokenCount

integer

這項要求使用的輸出詞元總數。