- HTTP 请求
- 路径参数
- 请求正文
- 响应正文
- 授权范围
- QueryDataContext
- ParameterizedSecureViewParameters
- 参数
- GenerationOptions
- ExecutedQueryResult
- 列
- 行
- 值
- 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 |
详细的分步流水线执行信息。仅当 generationOptions.generate_debug_info 为 true 时才会填充。仅用于调试和透明度目的。此对象的结构和内容不保证不变,并且可能随时更改,恕不另行通知。请勿根据此对象中的字段编写生产代码或业务逻辑。 |
tokenUsage |
请求的总体 token 用量。 |
授权范围
需要以下 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 等格式。如果值不为 null,则使用此字段。 |
TokenUsage
请求的总体 token 使用情况跟踪。
| JSON 表示法 |
|---|
{ "inputTokenCount": integer, "outputTokenCount": integer } |
| 字段 | |
|---|---|
inputTokenCount |
此请求中使用的输入 token 总数。 |
outputTokenCount |
此请求中使用的输出词元总数。 |