Method: projects.locations.queryData

Queries data from a natural language user query.

HTTP request


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

The URLs use gRPC Transcoding 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.

QueryDataContext

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

JSON representation 
{
  "datasourceReferences": {
    object (DatasourceReferences)
  }
}
Fields
datasourceReferences

object (DatasourceReferences)

Required. The datasource references to use for the query.

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.