Method: projects.locations.queryData

Consulta datos a partir de una consulta de usuario en lenguaje natural.

Solicitud HTTP

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

La URL usa la sintaxis de la transcodificación gRPC.

Parámetros de ruta

Parámetros
parent

string

Obligatorio. Es el recurso superior para el que se generará la consulta. Formato: projects/{project}/locations/{location}

Cuerpo de la solicitud

El cuerpo de la solicitud contiene datos con la siguiente estructura:

Representación JSON
{
  "prompt": string,
  "context": {
    object (QueryDataContext)
  },
  "generationOptions": {
    object (GenerationOptions)
  }
}
Campos
prompt

string

Obligatorio. Es la consulta en lenguaje natural para la que se generará la consulta. Por ejemplo: "¿Cuáles son los 5 productos más vendidos este mes?".

context

object (QueryDataContext)

Obligatorio. Es el contexto de la consulta de datos, incluidas las fuentes de datos que se usarán.

generationOptions

object (GenerationOptions)

Es opcional. Son opciones para controlar el comportamiento de la generación y ejecución de consultas.

Cuerpo de la respuesta

Es la respuesta que contiene la consulta generada y la información relacionada.

Si se ejecuta correctamente, el cuerpo de la respuesta contiene datos con la siguiente estructura:

Representación JSON
{
  "generatedQuery": string,
  "intentExplanation": string,
  "queryResult": {
    object (ExecutedQueryResult)
  },
  "naturalLanguageAnswer": string,
  "disambiguationQuestion": [
    string
  ],
  "pipelineDebugInfo": {
    object
  },
  "tokenUsage": {
    object (TokenUsage)
  }
}
Campos
generatedQuery

string

Es la consulta generada para la instrucción del usuario determinada.

intentExplanation

string

Una explicación en lenguaje natural de la consulta generada. Se propaga si options.generate_explanation era verdadero en la solicitud.

queryResult

object (ExecutedQueryResult)

Es el resultado de ejecutar la consulta. Se propaga si options.generate_query_result o options.generate_natural_language_answer era verdadero en la solicitud y la ejecución se realizó correctamente o se intentó.

naturalLanguageAnswer

string

Es una respuesta en lenguaje natural a la consulta, basada en queryResult. Se propaga si options.generate_natural_language_answer era verdadero en la solicitud y la ejecución de la consulta se realizó correctamente según la respuesta de la API de executeSql.

disambiguationQuestion[]

string

Si se detectó ambigüedad en la consulta en lenguaje natural y options.generate_disambiguation_question era verdadero, este campo contiene una pregunta para que el usuario la aclare. El valor que se devuelve representa el mejor esfuerzo del servicio en función de la entrada ambigua.

pipelineDebugInfo

object (Struct format)

Información detallada paso a paso sobre la ejecución de la canalización. Se completa solo si generationOptions.generate_debug_info era verdadero. Se proporciona solo con fines de depuración y transparencia. La estructura y el contenido de este objeto no están garantizados y pueden cambiar en cualquier momento sin previo aviso. No escribas código de producción ni lógica empresarial que dependa de los campos de este objeto.

tokenUsage

object (TokenUsage)

Es el uso general de tokens para la solicitud.

Permisos de autorización

Se necesita uno de los siguientes permisos de OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/geminidataanalytics

Para obtener más información, consulta Authentication Overview.

QueryDataContext

Son referencias a fuentes de datos y contexto que se usarán para la consulta.

Representación JSON
{
  "datasourceReferences": {
    object (DatasourceReferences)
  },
  "parameterizedSecureViewParameters": {
    object (ParameterizedSecureViewParameters)
  }
}
Campos
datasourceReferences

object (DatasourceReferences)

Obligatorio. Son las referencias de la fuente de datos que se usarán para la consulta.

parameterizedSecureViewParameters

object (ParameterizedSecureViewParameters)

Es opcional. Parámetros para las vistas seguras parametrizadas (PSV).

ParameterizedSecureViewParameters

Parámetros para las vistas seguras parametrizadas (PSV). Estos parámetros se usan para aplicar la seguridad a nivel de fila durante la generación de SQL y la ejecución de consultas.

Representación JSON
{
  "parameters": [
    {
      object (Parameter)
    }
  ]
}
Campos
parameters[]

object (Parameter)

Es opcional. Parámetros con nombre para las vistas seguras parametrizadas (PSV)

Parámetro

Representa un solo parámetro para las vistas seguras parametrizadas.

Representación JSON
{
  "key": string,
  "value": string
}
Campos
key

string

Obligatorio. Es la clave del parámetro (p.ej., "userId").

value

string

Obligatorio. Es el valor del parámetro (p.ej., "123").

GenerationOptions

Opciones para controlar la generación, la ejecución y el formato de respuesta de las consultas.

Representación JSON
{
  "generateQueryResult": boolean,
  "generateNaturalLanguageAnswer": boolean,
  "generateExplanation": boolean,
  "generateDisambiguationQuestion": boolean,
  "generateDebugInfo": boolean
}
Campos
generateQueryResult

boolean

Es opcional. Si es verdadero, se ejecutará la consulta generada y se devolverán los datos del resultado en la respuesta.

generateNaturalLanguageAnswer

boolean

Es opcional. Si es verdadero, se generará una respuesta en lenguaje natural basada en el resultado de la ejecución de la consulta y se devolverá en la respuesta.

generateExplanation

boolean

Es opcional. Si es verdadero, se devolverá una explicación de la consulta generada en la respuesta.

generateDisambiguationQuestion

boolean

Es opcional. Si es verdadero (el valor predeterminado es falso), el servicio puede devolver una clarifying_question si la consulta de entrada es ambigua.

generateDebugInfo

boolean

Es opcional. Si es verdadero (el valor predeterminado es falso), devuelve información de depuración interna.

ExecutedQueryResult

Es el resultado de la ejecución de una consulta. El diseño es genérico para todos los dialectos.

Representación JSON
{
  "columns": [
    {
      object (Column)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "totalRowCount": string,
  "partialResult": boolean,
  "queryExecutionError": string
}
Campos
columns[]

object (Column)

Son las columnas del conjunto de resultados, en orden.

rows[]

object (Row)

Son las filas que devuelve la consulta.

totalRowCount

string (int64 format)

Es la cantidad total de filas en el conjunto de resultados completo, si se conoce. Puede ser una estimación o un recuento exacto. Nota: Si se aplicó un límite interno (como LIMIT 1000) durante la ejecución de la consulta para evitar la transferencia excesiva de datos, este recuento refleja el tamaño del resultado truncado en lugar del tamaño del resultado de la tabla sin restricciones.

partialResult

boolean

Se establece como verdadero si las filas que se muestran en queryResult son un subconjunto del resultado completo. Esto puede suceder, por ejemplo, si la ejecución de la consulta alcanza un límite de filas. Cuando es verdadero, queryResult no contiene todas las filas. Para recuperar el resultado completo, considera usar el generatedQuery en QueryDataResponse y ejecutarlo en tu propio entorno.

queryExecutionError

string

Es el mensaje de error si falla la ejecución de la consulta.

Columna

Describe una sola columna en el conjunto de resultados.

Representación JSON
{
  "name": string,
  "type": string
}
Campos
name

string

Es el nombre de la columna

type

string

Es el tipo de columna (p.ej., "VARCHAR", "INT64", "TIMESTAMP").

Fila

Representa una sola fila en el conjunto de resultados.

Representación JSON
{
  "values": [
    {
      object (Value)
    }
  ]
}
Campos
values[]

object (Value)

Son los valores de la fila, que corresponden posicionalmente a las columnas.

Valor

Representa un solo valor dentro de una fila.

Representación JSON
{
  "value": string
}
Campos
value

string

Es el valor de la celda, representado en un formato de cadena. Las marcas de tiempo se pueden formatear, por ejemplo, con RFC3339Nano. Este campo se usa si el valor no es nulo.

TokenUsage

Es el seguimiento general del uso de tokens para la solicitud.

Representación JSON
{
  "inputTokenCount": integer,
  "outputTokenCount": integer
}
Campos
inputTokenCount

integer

Es la cantidad total de tokens de entrada que se usaron en esta solicitud.

outputTokenCount

integer

Es la cantidad total de tokens de salida que se usaron en esta solicitud.