Method: projects.locations.queryData

Consulta dados de uma consulta de usuário em linguagem natural.

Solicitação HTTP

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

O URL usa a sintaxe de transcodificação gRPC.

Parâmetros de caminho

Parâmetros
parent

string

Obrigatório. O recurso pai para o qual a consulta será gerada. Formato: projects/{project}/locations/{location}

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Representação JSON
{
  "prompt": string,
  "context": {
    object (QueryDataContext)
  },
  "generationOptions": {
    object (GenerationOptions)
  }
}
Campos
prompt

string

Obrigatório. A consulta em linguagem natural para a qual a consulta será gerada. Exemplo: "Quais são os 5 produtos mais vendidos este mês?"

context

object (QueryDataContext)

Obrigatório. O contexto da consulta de dados, incluindo as fontes de dados a serem usadas.

generationOptions

object (GenerationOptions)

Opcional. Opções para controlar o comportamento de geração e execução de consultas.

Corpo da resposta

Resposta que contém a consulta gerada e as informações relacionadas.

Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:

Representação JSON
{
  "generatedQuery": string,
  "intentExplanation": string,
  "queryResult": {
    object (ExecutedQueryResult)
  },
  "naturalLanguageAnswer": string,
  "disambiguationQuestion": [
    string
  ],
  "pipelineDebugInfo": {
    object
  },
  "tokenUsage": {
    object (TokenUsage)
  }
}
Campos
generatedQuery

string

Consulta gerada para o comando do usuário.

intentExplanation

string

Uma explicação em linguagem natural da consulta gerada. Preenchido se options.generate_explanation for verdadeiro na solicitação.

queryResult

object (ExecutedQueryResult)

O resultado da execução da consulta. Preenchido se options.generate_query_result ou options.generate_natural_language_answer for verdadeiro na solicitação e a execução for bem-sucedida ou tentada.

naturalLanguageAnswer

string

Uma resposta em linguagem natural para a consulta, com base no queryResult. Preenchido se options.generate_natural_language_answer for verdadeiro na solicitação e a execução da consulta for bem-sucedida com base na resposta da API executeSql.

disambiguationQuestion[]

string

Se uma ambiguidade foi detectada na consulta em linguagem natural e options.generate_disambiguation_question era verdadeiro, este campo contém uma pergunta ao usuário para esclarecimento. O retorno representa o melhor esforço do serviço com base na entrada ambígua.

pipelineDebugInfo

object (Struct format)

Informações detalhadas sobre a execução do pipeline. Preenchido apenas se generationOptions.generate_debug_info for verdadeiro. Fornecido apenas para fins de depuração e transparência. A estrutura e o conteúdo desse objeto não são garantidos e podem mudar a qualquer momento sem aviso prévio. Não escreva código de produção ou lógica de negócios dependendo dos campos desse objeto.

tokenUsage

object (TokenUsage)

Uso geral de tokens para a solicitação.

Escopos de autorização

Requer um dos seguintes escopos do OAuth:

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

Para mais informações, consulte Authentication Overview.

QueryDataContext

Referências a fontes de dados e contexto para usar na consulta.

Representação JSON
{
  "datasourceReferences": {
    object (DatasourceReferences)
  },
  "parameterizedSecureViewParameters": {
    object (ParameterizedSecureViewParameters)
  }
}
Campos
datasourceReferences

object (DatasourceReferences)

Obrigatório. As referências de fonte de dados que serão usadas na consulta.

parameterizedSecureViewParameters

object (ParameterizedSecureViewParameters)

Opcional. Parâmetros para visualizações seguras parametrizadas (PSV).

ParameterizedSecureViewParameters

Parâmetros para visualizações seguras parametrizadas (PSV). Esses parâmetros são usados para aplicar a segurança no nível da linha durante a geração de SQL e a execução de consultas.

Representação JSON
{
  "parameters": [
    {
      object (Parameter)
    }
  ]
}
Campos
parameters[]

object (Parameter)

Opcional. Parâmetros nomeados para visualizações seguras parametrizadas (PSV).

Parâmetro

Representa um único parâmetro para visualizações seguras parametrizadas.

Representação JSON
{
  "key": string,
  "value": string
}
Campos
key

string

Obrigatório. A chave de parâmetro (por exemplo, "userId").

value

string

Obrigatório. O valor de parâmetro (por exemplo, "123").

GenerationOptions

Opções para controlar a geração, a execução e o formato de resposta da consulta.

Representação JSON
{
  "generateQueryResult": boolean,
  "generateNaturalLanguageAnswer": boolean,
  "generateExplanation": boolean,
  "generateDisambiguationQuestion": boolean,
  "generateDebugInfo": boolean
}
Campos
generateQueryResult

boolean

Opcional. Se for verdadeiro, a consulta gerada será executada, e os dados resultantes serão retornados na resposta.

generateNaturalLanguageAnswer

boolean

Opcional. Se for verdadeiro, uma resposta em linguagem natural com base no resultado da execução da consulta será gerada e retornada na resposta.

generateExplanation

boolean

Opcional. Se for verdadeiro, uma explicação da consulta gerada será retornada na resposta.

generateDisambiguationQuestion

boolean

Opcional. Se for verdadeiro (o padrão é falso), o serviço poderá retornar uma clarifying_question se a consulta de entrada for ambígua.

generateDebugInfo

boolean

Opcional. Se for verdadeiro (o padrão é falso), retorna informações de depuração interna.

ExecutedQueryResult

O resultado da execução de uma consulta. O design é genérico para todos os dialetos.

Representação JSON
{
  "columns": [
    {
      object (Column)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "totalRowCount": string,
  "partialResult": boolean,
  "queryExecutionError": string
}
Campos
columns[]

object (Column)

As colunas no conjunto de resultados, em ordem.

rows[]

object (Row)

As linhas retornadas pela consulta.

totalRowCount

string (int64 format)

O número total de linhas no conjunto de resultados completo, se conhecido. Pode ser uma estimativa ou uma contagem exata. Observação: se um limite interno (como LIMIT 1000) foi aplicado durante a execução da consulta para evitar a transferência excessiva de dados, essa contagem reflete o tamanho do resultado truncado, e não o tamanho do resultado da tabela sem restrições.

partialResult

boolean

Defina como verdadeiro se as linhas retornadas em queryResult forem um subconjunto do resultado completo. Isso pode acontecer, por exemplo, se a execução da consulta atingir um limite de linhas. Quando verdadeiro, o queryResult não contém todas as linhas. Para recuperar o resultado completo, use o generatedQuery em QueryDataResponse e execute-o no seu próprio ambiente.

queryExecutionError

string

A mensagem de erro se a execução da consulta falhar.

Coluna

Descreve uma única coluna no conjunto de resultados.

Representação JSON
{
  "name": string,
  "type": string
}
Campos
name

string

O nome da coluna.

type

string

O tipo da coluna (por exemplo, "VARCHAR", "INT64", "TIMESTAMP").

Linha

Representa uma única linha no conjunto de resultados.

Representação JSON
{
  "values": [
    {
      object (Value)
    }
  ]
}
Campos
values[]

object (Value)

Os valores na linha, que correspondem posicionalmente às colunas.

Valor

Representa um único valor em uma linha.

Representação JSON
{
  "value": string
}
Campos
value

string

O valor da célula, representado em um formato de string. Os carimbos de data/hora podem ser formatados, por exemplo, usando RFC3339Nano. Esse campo será usado se o valor não for nulo.

TokenUsage

Monitoramento geral do uso de tokens para a solicitação.

Representação JSON
{
  "inputTokenCount": integer,
  "outputTokenCount": integer
}
Campos
inputTokenCount

integer

O número total de tokens de entrada usados nesta solicitação.

outputTokenCount

integer

O número total de tokens de saída usados nesta solicitação.