Method: projects.locations.queryData

Interroge les données à partir d'une requête utilisateur en langage naturel.

Requête HTTP

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

L'URL utilise la syntaxe de transcodage gRPC.

Paramètres de chemin d'accès

Paramètres
parent

string

Obligatoire. Ressource parente pour laquelle générer la requête. Format : projects/{project}/locations/{location}

Corps de la requête

Le corps de la requête contient des données présentant la structure suivante :

Représentation JSON
{
  "prompt": string,
  "context": {
    object (QueryDataContext)
  },
  "generationOptions": {
    object (GenerationOptions)
  }
}
Champs
prompt

string

Obligatoire. Requête en langage naturel pour laquelle générer une requête. Exemple : "Quels sont les cinq produits les plus vendus ce mois-ci ?"

context

object (QueryDataContext)

Obligatoire. Contexte de la requête de données, y compris les sources de données à utiliser.

generationOptions

object (GenerationOptions)

Facultatif. Options permettant de contrôler le comportement de génération et d'exécution des requêtes.

Corps de la réponse

Réponse contenant la requête générée et les informations associées.

Si la requête aboutit, le corps de la réponse contient des données qui ont la structure suivante :

Représentation JSON
{
  "generatedQuery": string,
  "intentExplanation": string,
  "queryResult": {
    object (ExecutedQueryResult)
  },
  "naturalLanguageAnswer": string,
  "disambiguationQuestion": [
    string
  ],
  "pipelineDebugInfo": {
    object
  },
  "tokenUsage": {
    object (TokenUsage)
  }
}
Champs
generatedQuery

string

Requête générée pour la requête utilisateur donnée.

intentExplanation

string

Explication en langage naturel de la requête générée. Renseigné si options.generate_explanation était défini sur "true" dans la requête.

queryResult

object (ExecutedQueryResult)

Résultat de l'exécution de la requête. Renseigné si options.generate_query_result ou options.generate_natural_language_answer était défini sur "true" dans la requête, et si l'exécution a réussi ou a été tentée.

naturalLanguageAnswer

string

Réponse en langage naturel à la requête, basée sur queryResult. Renseigné si options.generate_natural_language_answer était défini sur "true" dans la requête et que l'exécution de la requête a réussi en fonction de la réponse de l'API executeSql.

disambiguationQuestion[]

string

Si une ambiguïté a été détectée dans la requête en langage naturel et que options.generate_disambiguation_question était défini sur "true", ce champ contient une question à l'utilisateur pour clarification. La valeur renvoyée représente la meilleure estimation du service en fonction de l'entrée ambiguë.

pipelineDebugInfo

object (Struct format)

Informations détaillées sur l'exécution du pipeline, étape par étape. Renseigné uniquement si generationOptions.generate_debug_info était défini sur "true". Fourni uniquement à des fins de débogage et de transparence. La structure et le contenu de cet objet ne sont pas garantis et peuvent changer à tout moment sans préavis. N'écrivez pas de code de production ni de logique métier en fonction des champs de cet objet.

tokenUsage

object (TokenUsage)

Utilisation globale des jetons pour la requête.

Niveaux d'accès des autorisations

Nécessite l'un des niveaux d'accès OAuth suivants :

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

Pour plus d'informations, consultez la Authentication Overview.

QueryDataContext

Références aux sources de données et au contexte à utiliser pour la requête.

Représentation JSON
{
  "datasourceReferences": {
    object (DatasourceReferences)
  },
  "parameterizedSecureViewParameters": {
    object (ParameterizedSecureViewParameters)
  }
}
Champs
datasourceReferences

object (DatasourceReferences)

Obligatoire. Références de sources de données à utiliser pour la requête.

parameterizedSecureViewParameters

object (ParameterizedSecureViewParameters)

Facultatif. Paramètres des vues sécurisées paramétrées (PSV).

ParameterizedSecureViewParameters

Paramètres des vues sécurisées paramétrées (PSV). Ces paramètres sont utilisés pour appliquer la sécurité au niveau des lignes lors de la génération de SQL et de l'exécution des requêtes.

Représentation JSON
{
  "parameters": [
    {
      object (Parameter)
    }
  ]
}
Champs
parameters[]

object (Parameter)

Facultatif. Paramètres nommés pour les vues sécurisées paramétrées (PSV).

Paramètre

Représente un seul paramètre pour les vues sécurisées paramétrées.

Représentation JSON
{
  "key": string,
  "value": string
}
Champs
key

string

Obligatoire. La clé du paramètre (par exemple, "userId").

value

string

Obligatoire. La valeur du paramètre (par exemple, "123").

GenerationOptions

Options permettant de contrôler la génération, l'exécution et le format de réponse des requêtes.

Représentation JSON
{
  "generateQueryResult": boolean,
  "generateNaturalLanguageAnswer": boolean,
  "generateExplanation": boolean,
  "generateDisambiguationQuestion": boolean,
  "generateDebugInfo": boolean
}
Champs
generateQueryResult

boolean

Facultatif. Si la valeur est "true", la requête générée sera exécutée et les données de résultat seront renvoyées dans la réponse.

generateNaturalLanguageAnswer

boolean

Facultatif. Si la valeur est "true", une réponse en langage naturel basée sur le résultat de l'exécution de la requête sera générée et renvoyée dans la réponse.

generateExplanation

boolean

Facultatif. Si la valeur est "true", une explication de la requête générée sera renvoyée dans la réponse.

generateDisambiguationQuestion

boolean

Facultatif. Si la valeur est "true" (la valeur par défaut est "false"), le service peut renvoyer une question de clarification (clarifying_question) si la requête d'entrée est ambiguë.

generateDebugInfo

boolean

Facultatif. Si la valeur est "true" (valeur par défaut : "false"), renvoie les informations de débogage internes.

ExecutedQueryResult

Résultat de l'exécution d'une requête. La conception est générique pour tous les dialectes.

Représentation JSON
{
  "columns": [
    {
      object (Column)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "totalRowCount": string,
  "partialResult": boolean,
  "queryExecutionError": string
}
Champs
columns[]

object (Column)

Colonnes de l'ensemble de résultats, dans l'ordre.

rows[]

object (Row)

Lignes renvoyées par la requête.

totalRowCount

string (int64 format)

Nombre total de lignes dans l'ensemble de résultats complet, s'il est connu. Il peut s'agir d'une estimation ou d'un nombre exact. Remarque : Si une limite interne (par exemple, LIMIT 1000) a été appliquée lors de l'exécution de la requête pour éviter un transfert de données excessif, ce nombre reflète la taille du résultat tronqué plutôt que celle du résultat de la table sans restriction.

partialResult

boolean

Définissez cette option sur "true" si les lignes renvoyées dans queryResult sont un sous-ensemble du résultat complet. Cela peut se produire, par exemple, si l'exécution de la requête atteint une limite de lignes. Si la valeur est "true", queryResult ne contient pas toutes les lignes. Pour récupérer le résultat complet, vous pouvez utiliser le generatedQuery dans QueryDataResponse et l'exécuter dans votre propre environnement.

queryExecutionError

string

Message d'erreur si l'exécution de la requête a échoué.

Colonne

Décrit une seule colonne de l'ensemble de résultats.

Représentation JSON
{
  "name": string,
  "type": string
}
Champs
name

string

Nom de la colonne.

type

string

Type de la colonne (par exemple, "VARCHAR", "INT64", "TIMESTAMP").

Ligne

Représente une seule ligne dans l'ensemble de résultats.

Représentation JSON
{
  "values": [
    {
      object (Value)
    }
  ]
}
Champs
values[]

object (Value)

Valeurs de la ligne, correspondant à la position des colonnes.

Valeur

Représente une valeur unique dans une ligne.

Représentation JSON
{
  "value": string
}
Champs
value

string

Valeur de la cellule, représentée sous forme de chaîne. Les codes temporels peuvent être formatés, par exemple, à l'aide de RFC3339Nano. Ce champ est utilisé si la valeur n'est pas nulle.

TokenUsage

Suivi de l'utilisation globale des jetons pour la requête.

Représentation JSON
{
  "inputTokenCount": integer,
  "outputTokenCount": integer
}
Champs
inputTokenCount

integer

Nombre total de jetons d'entrée utilisés dans cette requête.

outputTokenCount

integer

Nombre total de jetons de sortie utilisés dans cette requête.