Cortex Analyst REST API

Utilisez cette API pour répondre aux questions sur vos données avec des requêtes en langage naturel.

Envoyer un message

POST /api/v2/cortex/analyst/message

Génère une requête SQL pour la question donnée en utilisant le modèle sémantique fourni dans la demande. Notez que l’API est sans état, donc seules les conversations à tour unique sont prises en charge.

La demande comprend une question de l’utilisateur et la réponse comprend la question de l’utilisateur et la réponse de l’analyste. Chaque message d’une réponse peut avoir plusieurs blocs de contenu de types différents. Trois valeurs actuellement prises en charge pour le champ type de l’objet de contenu sont : text, suggestions, et sql.

En-têtes de requête

En-tête

Description

Authorization

(Obligatoire) Jeton d’autorisation. Pour plus d’informations, voir Authentification auprès du serveur.

Content-Type

(Obligatoire) application/json

Corps de la requête

Le corps de la requête contient le rôle du locuteur qui doit être user, la question de l’utilisateur et un chemin vers le fichier YAML du modèle sémantique. La question de l’utilisateur est contenue dans un objet content qui a deux champs, type et text. text est également la seule valeur autorisée du champ type.

Champ

Description

messages[].role

(Obligatoire) Le rôle de l’entité qui crée le message. Actuellement, seulement user est pris en charge.

Type : string:enum

Exemple : user

messages[].content[]

(Obligatoire) L’objet de contenu qui fait partie d’un message.

Type : objet

Exemple :

{
  "type": "text",
  "text":  "Which company had the most revenue?"
}
Copy

messages[].content[].type

(Obligatoire) Le type de contenu. Actuellement, seulement text est pris en charge.

Type : string:enum

Exemple : text

messages[].content[].text

(Obligatoire) La question de l’utilisateur.

Type : chaîne

Exemple : Which company had the most revenue?

semantic_model_file

Chemin vers le fichier YAML du modèle sémantique. Doit être une URL de zone de préparation entièrement qualifiée, y compris la base de données et le schéma. Vous pouvez plutôt fournir le modèle sémantique YAML complet dans le champ semantic_model.

Type : chaîne

Exemple : @my_db.my_schema.my_stage/my_semantic_model.yaml

semantic_model

Une chaîne contenant l’intégralité du modèle sémantique YAML. Vous pouvez plutôt transmettre le modèle sémantique YAML en tant que fichier en zone de préparation en fournissant son URL dans le champ semantic_model_file.

Type : chaîne

Important

Vous devez fournir soit semantic_model_file ou semantic_model dans le corps de la requête.

Exemple

{
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "which company had the most revenue?"
                }
            ]
        },
    ],
    "semantic_model_file": "@my_stage/my_semantic_model.yaml"
}
Copy

Réponse

Cette opération peut renvoyer les codes de réponse énumérés ci-dessous. La réponse a toujours la structure suivante. Actuellement, trois types de contenu sont pris en charge pour la réponse, text, suggestion, et sql. Les types de contenu suggestion et sql sont mutuellement exclusifs de sorte que si la réponse contient un type de contenu sql, elle ne contiendra pas de type de contenu suggestion. Le type de contenu suggestion n’est inclus dans une réponse que si la question de l’utilisateur était ambiguë et Cortex Analyst ne pouvait pas retourner une instruction SQL pour cette requête.

Pour garantir la compatibilité ascendante, assurez-vous que votre implémentation prend en compte le type de contenu et gère les types.

Code

Description

200

L’instruction a été exécutée avec succès.

Le corps de la réponse contient un objet message qui contient les champs suivants :

  • message : Messages de la conversation entre l’utilisateur et l’analyste.

  • message (objet) : Représente un message dans un Chat.

  • message.role (string:enum) : L’entité qui a produit le message. L’un des rôles suivants : user ou analyst.

  • message.content[] (objet) : L’objet de contenu qui fait partie d’un message.

  • message.content[].type (string:enum) : Le type de contenu du message. L’un des rôles suivants : text, suggestion ou sql.

  • message.content[].text (string) : Le texte du contenu. Renvoyé uniquement pour le type de contenu text.

  • message.content[].statement (string) : Une instruction SQL. Renvoyé uniquement pour le type de contenu sql.

  • message.content[].suggestions (string) : Si le SQL ne peut pas être généré, une liste pour lesquelles le modèle sémantique peut générer du SQL. Renvoyé uniquement pour le type de contenu suggestion.

{
    "message": {
        "role": "analyst",
        "content": [
            {
                "type": "text",
                "text": "We interpreted your question as ..."
            },
            {
                "type": "sql",
                "statement": "SELECT * FROM table"
            }
        ]
    }
}
Copy
Langage: Français