- [HTTP request](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations/queryData.md.txt#body.HTTP_TEMPLATE)
- [Path parameters](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations/queryData.md.txt#body.PATH_PARAMETERS)
- [Request body](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations/queryData.md.txt#body.request_body)
  - [JSON representation](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations/queryData.md.txt#body.request_body.SCHEMA_REPRESENTATION)
- [Response body](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations/queryData.md.txt#body.response_body)
  - [JSON representation](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations/queryData.md.txt#body.QueryDataResponse.SCHEMA_REPRESENTATION)
- [Authorization scopes](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations/queryData.md.txt#body.aspect)
- [QueryDataContext](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations/queryData.md.txt#QueryDataContext)
  - [JSON representation](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations/queryData.md.txt#QueryDataContext.SCHEMA_REPRESENTATION)
- [ParameterizedSecureViewParameters](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations/queryData.md.txt#ParameterizedSecureViewParameters)
  - [JSON representation](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations/queryData.md.txt#ParameterizedSecureViewParameters.SCHEMA_REPRESENTATION)
- [Parameter](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations/queryData.md.txt#Parameter)
  - [JSON representation](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations/queryData.md.txt#Parameter.SCHEMA_REPRESENTATION)
- [GenerationOptions](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations/queryData.md.txt#GenerationOptions)
  - [JSON representation](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations/queryData.md.txt#GenerationOptions.SCHEMA_REPRESENTATION)
- [ExecutedQueryResult](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations/queryData.md.txt#ExecutedQueryResult)
  - [JSON representation](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations/queryData.md.txt#ExecutedQueryResult.SCHEMA_REPRESENTATION)
- [Column](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations/queryData.md.txt#Column)
  - [JSON representation](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations/queryData.md.txt#Column.SCHEMA_REPRESENTATION)
- [Row](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations/queryData.md.txt#Row)
  - [JSON representation](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations/queryData.md.txt#Row.SCHEMA_REPRESENTATION)
- [Value](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations/queryData.md.txt#Value)
  - [JSON representation](https://docs.cloud.google.com/gemini/data-agents/reference/rest/v1beta/projects.locations/queryData.md.txt#Value.SCHEMA_REPRESENTATION)

Queries data from a natural language user query.

### HTTP request

`POST https://geminidataanalytics.googleapis.com/v1beta/{parent=projects/*/locations/*}:queryData`

The URL uses [gRPC Transcoding](https://google.aip.dev/127) syntax.

### Path parameters

| Parameters ||
|---|---|
| `parent` | `string` 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 (`QueryDataContext`) }, "generationOptions": { object (`GenerationOptions`) } } ``` |

| Fields ||
|---|---|
| `prompt` | `string` Required. The natural language query for which to generate query. Example: "What are the top 5 best selling products this month?" |
| `context` | ``object (`QueryDataContext`)`` Required. The context for the data query, including the data sources to use. |
| `generationOptions` | ``object (`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 (`ExecutedQueryResult`) }, "naturalLanguageAnswer": string, "disambiguationQuestion": [ string ] } ``` |

| Fields ||
|---|---|
| `generatedQuery` | `string` Generated query for the given user prompt. |
| `intentExplanation` | `string` A natural language explanation of the generated query. Populated if options.generate_explanation was true in the request. |
| `queryResult` | ``object (`ExecutedQueryResult`)`` 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` | `string` 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[]` | `string` 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. |

### Authorization scopes

Requires the following OAuth scope:

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

For more information, see the [Authentication Overview](https://docs.cloud.google.com/docs/authentication.md.txt#authorization-gcp).

## QueryDataContext

References to data sources and context to use for the query.

| JSON representation |
|---|
| ``` { "datasourceReferences": { object (`DatasourceReferences`) }, "parameterizedSecureViewParameters": { object (`ParameterizedSecureViewParameters`) } } ``` |

| Fields ||
|---|---|
| `datasourceReferences` | ``object (`DatasourceReferences`)`` Required. The datasource references to use for the query. |
| `parameterizedSecureViewParameters` | ``object (`ParameterizedSecureViewParameters`)`` Optional. Parameters for parameterized secure views. |

## ParameterizedSecureViewParameters

Parameters for parameterized secure views. These parameters are used to enforce row-level security during SQL generation and query execution.

| JSON representation |
|---|
| ``` { "parameters": [ { object (`Parameter`) } ] } ``` |

| Fields ||
|---|---|
| `parameters[]` | ``object (`Parameter`)`` Optional. Named parameters for parameterized secure views. |

## Parameter

Represents a single parameter for parameterized secure views.

| JSON representation |
|---|
| ``` { "key": string, "value": string } ``` |

| Fields ||
|---|---|
| `key` | `string` Required. The parameter key (e.g., `"userId"`). |
| `value` | `string` Required. The parameter value (e.g., `"123"`). |

## GenerationOptions

Options to control query generation, execution, and response format.

| JSON representation |
|---|
| ``` { "generateQueryResult": boolean, "generateNaturalLanguageAnswer": boolean, "generateExplanation": boolean, "generateDisambiguationQuestion": boolean } ``` |

| Fields ||
|---|---|
| `generateQueryResult` | `boolean` Optional. If true, the generated query will be executed, and the result data will be returned in the response. |
| `generateNaturalLanguageAnswer` | `boolean` Optional. If true, a natural language answer based on the query execution result will be generated and returned in the response. |
| `generateExplanation` | `boolean` Optional. If true, an explanation of the generated query will be returned in the response. |
| `generateDisambiguationQuestion` | `boolean` Optional. If true (default to false), the service may return a clarifying_question if the input query is ambiguous. |

## ExecutedQueryResult

The result of a query execution. The design is generic for all dialects.

| JSON representation |
|---|
| ``` { "columns": [ { object (`Column`) } ], "rows": [ { object (`Row`) } ], "totalRowCount": string, "partialResult": boolean, "queryExecutionError": string } ``` |

| Fields ||
|---|---|
| `columns[]` | ``object (`Column`)`` The columns in the result set, in order. |
| `rows[]` | ``object (`Row`)`` The rows returned by the query. |
| `totalRowCount` | `string (int64 format)` The total number of rows in the full result set, if known. This may be an estimate or an exact count. |
| `partialResult` | `boolean` Set to true if the returned rows in `queryResult` are a subset of the full result. This can happen, for example, if the query execution hits a row limit. When true, the `queryResult` does not contain all rows. To retrieve the complete result, consider using the `generatedQuery` in `QueryDataResponse` and executing it in your own environment. |
| `queryExecutionError` | `string` 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` | `string` The name of the column. |
| `type` | `string` The type of the column (e.g., "VARCHAR", "INT64", "TIMESTAMP"). |

## Row

Represents a single row in the result set.

| JSON representation |
|---|
| ``` { "values": [ { object (`Value`) } ] } ``` |

| Fields ||
|---|---|
| `values[]` | ``object (`Value`)`` The values in the row, corresponding positionally to the columns. |

## Value

Represents a single value within a row.

| JSON representation |
|---|
| ``` { "value": string } ``` |

| Fields ||
|---|---|
| `value` | `string` 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. |