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. Vous pouvez avoir des conversations à plusieurs tours où vous pouvez poser des questions de suivi qui s’appuient sur les requêtes précédentes. Pour plus d’informations, voir Conversation à plusieurs tours en Cortex Analyst.

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[].confidence (object) : Contient des informations relatives à la confiance. Renvoyé uniquement pour le type de contenu sql.

  • message.content[].confidence.verified_query_used (object) : Représente la requête vérifiée provenant du dépôt de requêtes vérifiées utilisé dans la génération de la réponse SQL. Si aucune requête vérifiée n’est utilisée, la valeur du champ est null.

  • message.content[].confidence.verified_query_used.name (string) : Le nom de la requête vérifiée utilisée, extrait du dépôt des requêtes vérifiées.

  • message.content[].confidence.verified_query_used.question (string) : La question à laquelle répond la requête vérifiée, extraite du dépôt de requêtes vérifiées.

  • message.content[].confidence.verified_query_used.sql (string) : L’instruction SQL de la requête vérifiée utilisée, extraite du dépôt de requêtes vérifiées.

  • message.content[].confidence.verified_query_used.verified_at (entier) : La représentation numérique de l’horodatage lorsque la requête est vérifiée, extraite du dépôt des requêtes vérifiées.

  • message.content[].confidence.verified_query_used.verified_by (string) : La personne qui a vérifié la requête, extraite du dépôt des requêtes vérifiées.

  • 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.content[].warnings : Liste des avertissements de l’analyste concernant la requête de l’utilisateur.

  • message.content[].warnings (liste) : Représente une collection d’avertissements concernant les requêtes des utilisateurs et les modèles sémantiques.

  • message.content[].warnings[].message (string) : Contient une description détaillée d’un avertissement individuel.

{
    "request_id": "75d343ee-699c-483f-83a1-e314609fb563",
    "message": {
        "role": "analyst",
        "content": [
            {
                "type": "text",
                "text": "We interpreted your question as ..."
            },
            {
                "type": "sql",
                "statement": "SELECT * FROM table",
                "confidence": {
                    "verified_query_used": {
                        "name": "My verified query",
                        "question": "What was the total revenue?",
                        "sql": "SELECT * FROM table2",
                        "verified_at": 1714497970,
                        "verified_by": "Jane Doe"
                    }
                }
            }
        ]
    },
    "warnings": [
        {
            "message": "Table table1 has (30) columns, which exceeds the recommended maximum of 10"
        },
        {
            "message": "Table table2 has (40) columns, which exceeds the recommended maximum of 10"
        }
    ]
}
Copy

Envoyer le feedback

POST /api/v2/cortex/analyst/feedback

Fournit un retour d’information qualitatif à l’utilisateur final. Sur l”Snowsight, le retour d’information est indiqué à l’adresse Semantic Model Admins sous Monitoring.

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

Champ

Description

request_id

(Obligatoire) L’identifiant de la requête que vous avez faite pour envoyer un message. Renvoyé dans le champ request_id de /api/v2/cortex/analyst/message. Pour plus d’informations, voir Réponse.

Type : chaîne

Exemple : 75d343ee-699c-483f-83a1-e314609fb563

positive

(Obligatoire) Indique si le retour d’information est positif ou négatif. true pour un retour d’information positif ou un « pouce vers le haut », false pour un retour d’information négatif ou un « pouce vers le bas ».

Type : booléen

Exemple :

true

feedback_message

(Facultatif) Le message de retour de l’utilisateur.

Exemple : This is the best answer I've ever seen!

Réponse

Corps de réponse vide avec le code de statut 200.

Exigences en matière de contrôle d’accès

Pour obtenir des informations sur les privilèges requis, voir Exigences en matière de contrôle d’accès.

Pour plus d’informations sur l’authentification à l’API, voir Authentification d”Snowflake REST APIs avec Snowflake.

Langage: Français