- Requête HTTP
- Paramètres de chemin d'accès
- Corps de la requête
- Corps de la réponse
- Niveaux d'accès des autorisations
- QueryDataContext
- ParameterizedSecureViewParameters
- Paramètre
- GenerationOptions
- ExecutedQueryResult
- Colonne
- Ligne
- Valeur
- TokenUsage
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 |
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 ( |
| Champs | |
|---|---|
prompt |
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 |
Obligatoire. Contexte de la requête de données, y compris les sources de données à utiliser. |
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 ( |
| Champs | |
|---|---|
generatedQuery |
Requête générée pour la requête utilisateur donnée. |
intentExplanation |
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 |
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 |
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[] |
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 |
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 |
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-platformhttps://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 ( |
| Champs | |
|---|---|
datasourceReferences |
Obligatoire. Références de sources de données à utiliser pour la requête. |
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 ( |
| Champs | |
|---|---|
parameters[] |
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 |
Obligatoire. La clé du paramètre (par exemple, |
value |
Obligatoire. La valeur du paramètre (par exemple, |
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 |
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 |
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 |
Facultatif. Si la valeur est "true", une explication de la requête générée sera renvoyée dans la réponse. |
generateDisambiguationQuestion |
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 |
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 ( |
| Champs | |
|---|---|
columns[] |
Colonnes de l'ensemble de résultats, dans l'ordre. |
rows[] |
Lignes renvoyées par la requête. |
totalRowCount |
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 |
Définissez cette option sur "true" si les lignes renvoyées dans |
queryExecutionError |
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 |
Nom de la colonne. |
type |
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 ( |
| Champs | |
|---|---|
values[] |
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 |
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 |
Nombre total de jetons d'entrée utilisés dans cette requête. |
outputTokenCount |
Nombre total de jetons de sortie utilisés dans cette requête. |