- Solicitud HTTP
- Parámetros de ruta
- Cuerpo de la solicitud
- Cuerpo de la respuesta
- Permisos de autorización
- QueryDataContext
- ParameterizedSecureViewParameters
- Parámetro
- GenerationOptions
- ExecutedQueryResult
- Columna
- Fila
- Valor
- TokenUsage
Consulta datos a partir de una consulta de usuario en lenguaje natural.
Solicitud HTTP
POST https://geminidataanalytics.googleapis.com/v1beta/{parent=projects/*/locations/*}:queryData
La URL usa la sintaxis de la transcodificación gRPC.
Parámetros de ruta
| Parámetros | |
|---|---|
parent |
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 ( |
| Campos | |
|---|---|
prompt |
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 |
Obligatorio. Es el contexto de la consulta de datos, incluidas las fuentes de datos que se usarán. |
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 ( |
| Campos | |
|---|---|
generatedQuery |
Es la consulta generada para la instrucción del usuario determinada. |
intentExplanation |
Una explicación en lenguaje natural de la consulta generada. Se propaga si options.generate_explanation era verdadero en la solicitud. |
queryResult |
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 |
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[] |
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 |
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 |
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-platformhttps://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 ( |
| Campos | |
|---|---|
datasourceReferences |
Obligatorio. Son las referencias de la fuente de datos que se usarán para la consulta. |
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 ( |
| Campos | |
|---|---|
parameters[] |
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 |
Obligatorio. Es la clave del parámetro (p.ej., |
value |
Obligatorio. Es el valor del parámetro (p.ej., |
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 |
Es opcional. Si es verdadero, se ejecutará la consulta generada y se devolverán los datos del resultado en la respuesta. |
generateNaturalLanguageAnswer |
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 |
Es opcional. Si es verdadero, se devolverá una explicación de la consulta generada en la respuesta. |
generateDisambiguationQuestion |
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 |
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 ( |
| Campos | |
|---|---|
columns[] |
Son las columnas del conjunto de resultados, en orden. |
rows[] |
Son las filas que devuelve la consulta. |
totalRowCount |
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 |
Se establece como verdadero si las filas que se muestran en |
queryExecutionError |
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 |
Es el nombre de la columna |
type |
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 ( |
| Campos | |
|---|---|
values[] |
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 |
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 |
Es la cantidad total de tokens de entrada que se usaron en esta solicitud. |
outputTokenCount |
Es la cantidad total de tokens de salida que se usaron en esta solicitud. |