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），则当输入查询不明确时，服务可能会返回澄清问题。

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 等格式。如果该值不为 null，则使用此字段。