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
  ]
}
欄位
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，這個欄位會包含供使用者釐清問題的內容。傳回的結果是服務根據模糊輸入內容盡力提供的最佳結果。

授權範圍

需要下列 OAuth 範圍：

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

詳情請參閱Authentication Overview。

QueryDataContext

查詢時要使用的資料來源和情境參考資料。

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

object (DatasourceReferences)

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

GenerationOptions

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

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

boolean

選用。如果為 true，系統會執行產生的查詢，並在回應中傳回結果資料。
generateNaturalLanguageAnswer

boolean

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

boolean

選用。如果為 true，系統會在回應中傳回所產生查詢的說明。
generateDisambiguationQuestion

boolean

選用。如果設為 true (預設為 false)，當輸入查詢內容模稜兩可時，服務可能會傳回 clarifying_question。

ExecutedQueryResult

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

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

object (Column)

結果集中的欄 (依序排列)。
rows[]

object (Row)

查詢傳回的資料列。
totalRowCount

string (int64 format)

完整結果集中的資料列總數 (如已知)。這可能是預估值或確切計數。
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 等格式。如果值不是空值，系統就會使用這個欄位。