- Solicitação HTTP
- Parâmetros de caminho
- Corpo da solicitação
- Corpo da resposta
- Escopos de autorização
- QueryDataContext
- ParameterizedSecureViewParameters
- Parâmetro
- GenerationOptions
- ExecutedQueryResult
- Coluna
- Linha
- Valor
- TokenUsage
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 |
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 ( |
| Campos | |
|---|---|
prompt |
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 |
Obrigatório. O contexto da consulta de dados, incluindo as fontes de dados a serem usadas. |
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 ( |
| Campos | |
|---|---|
generatedQuery |
Consulta gerada para o comando do usuário. |
intentExplanation |
Uma explicação em linguagem natural da consulta gerada. Preenchido se options.generate_explanation for verdadeiro na solicitação. |
queryResult |
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 |
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[] |
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 |
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 |
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-platformhttps://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 ( |
| Campos | |
|---|---|
datasourceReferences |
Obrigatório. As referências de fonte de dados que serão usadas na consulta. |
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 ( |
| Campos | |
|---|---|
parameters[] |
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 |
Obrigatório. A chave de parâmetro (por exemplo, |
value |
Obrigatório. O valor de parâmetro (por exemplo, |
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 |
Opcional. Se for verdadeiro, a consulta gerada será executada, e os dados resultantes serão retornados na resposta. |
generateNaturalLanguageAnswer |
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 |
Opcional. Se for verdadeiro, uma explicação da consulta gerada será retornada na resposta. |
generateDisambiguationQuestion |
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 |
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 ( |
| Campos | |
|---|---|
columns[] |
As colunas no conjunto de resultados, em ordem. |
rows[] |
As linhas retornadas pela consulta. |
totalRowCount |
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 |
Defina como verdadeiro se as linhas retornadas em |
queryExecutionError |
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 |
O nome da coluna. |
type |
O tipo da coluna (por exemplo, "VARCHAR", "INT64", "TIMESTAMP"). |
Linha
Representa uma única linha no conjunto de resultados.
| Representação JSON |
|---|
{
"values": [
{
object ( |
| Campos | |
|---|---|
values[] |
Os valores na linha, que correspondem posicionalmente às colunas. |
Valor
Representa um único valor em uma linha.
| Representação JSON |
|---|
{ "value": string } |
| Campos | |
|---|---|
value |
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 |
O número total de tokens de entrada usados nesta solicitação. |
outputTokenCount |
O número total de tokens de saída usados nesta solicitação. |