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)

详细的分步流水线执行信息。仅当 generationOptions.generate_debug_info 为 true 时才会填充。仅用于调试和透明度目的。此对象的结构和内容不保证不变,并且可能随时更改,恕不另行通知。请勿根据此对象中的字段编写生产代码或业务逻辑。

tokenUsage

object (TokenUsage)

请求的总体 token 用量。

授权范围

需要以下 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 等格式。如果值不为 null,则使用此字段。

TokenUsage

请求的总体 token 使用情况跟踪。

JSON 表示法
{
  "inputTokenCount": integer,
  "outputTokenCount": integer
}
字段
inputTokenCount

integer

此请求中使用的输入 token 总数。

outputTokenCount

integer

此请求中使用的输出词元总数。