- HTTP request
- Path parameters
- Request body
- Response body
- Authorization scopes
- QueryDataContext
- ParameterizedSecureViewParameters
- Parameter
- GenerationOptions
- ExecutedQueryResult
- Column
- Row
- Value
- TokenUsage
Queries data from a natural language user query.
HTTP request
POST https://geminidataanalytics.googleapis.com/v1alpha/{parent=projects/*/locations/*}:queryData
The URL uses gRPC Transcoding syntax.
Path parameters
| Parameters | |
|---|---|
parent |
Required. The parent resource to generate the query for. Format: projects/{project}/locations/{location} |
Request body
The request body contains data with the following structure:
| JSON representation |
|---|
{ "prompt": string, "context": { object ( |
| Fields | |
|---|---|
prompt |
Required. The natural language query for which to generate query. Example: "What are the top 5 best selling products this month?" |
context |
Required. The context for the data query, including the data sources to use. |
generationOptions |
Optional. Options to control query generation and execution behavior. |
Response body
Response containing the generated query and related information.
If successful, the response body contains data with the following structure:
| JSON representation |
|---|
{ "generatedQuery": string, "intentExplanation": string, "queryResult": { object ( |
| Fields | |
|---|---|
generatedQuery |
Generated query for the given user prompt. |
intentExplanation |
A natural language explanation of the generated query. Populated if options.generate_explanation was true in the request. |
queryResult |
The result of executing the query. Populated if options.generate_query_result or options.generate_natural_language_answer was true in the request, and execution was successful or attempted. |
naturalLanguageAnswer |
A natural language answer to the query, based on the queryResult. Populated if options.generate_natural_language_answer was true in the request and query execution was successful based in the response from executeSql API. |
disambiguationQuestion[] |
If ambiguity was detected in the natural language query and options.generate_disambiguation_question was true, this field contains a question to the user for clarification. The returned represents the service's best effort based on the ambiguous input. |
pipelineDebugInfo |
Detailed step-by-step pipeline execution information. Populated only if generationOptions.generate_debug_info was true. Provided for debugging and transparency purposes only. The structure and content of this object is not guaranteed and may change at any time without notice. Do not write production code or business logic depending on the fields in this object. |
tokenUsage |
Overall token usage for the request. |
Authorization scopes
Requires one of the following OAuth scopes:
https://www.googleapis.com/auth/cloud-platformhttps://www.googleapis.com/auth/geminidataanalytics
For more information, see the Authentication Overview.
QueryDataContext
References to data sources and context to use for the query.
| JSON representation |
|---|
{ "datasourceReferences": { object ( |
| Fields | |
|---|---|
datasourceReferences |
Required. The datasource references to use for the query. |
parameterizedSecureViewParameters |
Optional. Parameters for Parameterized Secure Views (PSV). |
ParameterizedSecureViewParameters
Parameters for Parameterized Secure Views (PSV). These parameters are used to enforce row-level security during SQL generation and query execution.
| JSON representation |
|---|
{
"parameters": [
{
object ( |
| Fields | |
|---|---|
parameters[] |
Optional. Named parameters for Parameterized Secure Views (PSV). |
Parameter
Represents a single parameter for Parameterized Secure Views.
| JSON representation |
|---|
{ "key": string, "value": string } |
| Fields | |
|---|---|
key |
Required. The parameter key (e.g., |
value |
Required. The parameter value (e.g., |
GenerationOptions
Options to control query generation, execution, and response format.
| JSON representation |
|---|
{ "generateQueryResult": boolean, "generateNaturalLanguageAnswer": boolean, "generateExplanation": boolean, "generateDisambiguationQuestion": boolean, "generateDebugInfo": boolean } |
| Fields | |
|---|---|
generateQueryResult |
Optional. If true, the generated query will be executed, and the result data will be returned in the response. |
generateNaturalLanguageAnswer |
Optional. If true, a natural language answer based on the query execution result will be generated and returned in the response. |
generateExplanation |
Optional. If true, an explanation of the generated query will be returned in the response. |
generateDisambiguationQuestion |
Optional. If true (default to false), the service may return a clarifying_question if the input query is ambiguous. |
generateDebugInfo |
Optional. If true (default to false), returns internal debugging information. |
ExecutedQueryResult
The result of a query execution. The design is generic for all dialects.
| JSON representation |
|---|
{ "columns": [ { object ( |
| Fields | |
|---|---|
columns[] |
The columns in the result set, in order. |
rows[] |
The rows returned by the query. |
totalRowCount |
The total number of rows in the full result set, if known. This may be an estimate or an exact count. Note: if an internal limit (such as LIMIT 1000) was applied during query execution to guard against excessive data transfer, this count reflects the truncated result size rather than the unrestricted table result size. |
partialResult |
Set to true if the returned rows in |
queryExecutionError |
The error message if the query execution failed. |
Column
Describes a single column in the result set.
| JSON representation |
|---|
{ "name": string, "type": string } |
| Fields | |
|---|---|
name |
The name of the column. |
type |
The type of the column (e.g., "VARCHAR", "INT64", "TIMESTAMP"). |
Row
Represents a single row in the result set.
| JSON representation |
|---|
{
"values": [
{
object ( |
| Fields | |
|---|---|
values[] |
The values in the row, corresponding positionally to the columns. |
Value
Represents a single value within a row.
| JSON representation |
|---|
{ "value": string } |
| Fields | |
|---|---|
value |
The cell value, represented in a string format. Timestamps could be formatted, for example, using RFC3339Nano. This field is used if the value is not null. |
TokenUsage
Overall token usage tracking for the request.
| JSON representation |
|---|
{ "inputTokenCount": integer, "outputTokenCount": integer } |
| Fields | |
|---|---|
inputTokenCount |
The total number of input tokens used in this request. |
outputTokenCount |
The total number of output tokens used in this request. |