Cortex Analyst REST API

Verwenden Sie diese API, um Fragen zu Ihren Daten mit Abfragen in natürlicher Sprache zu beantworten.

Meldung senden

POST /api/v2/cortex/analyst/message

Erzeugt eine SQL-Abfrage für die gestellte Frage unter Verwendung des in der Anfrage angegebenen semantischen Modells. Sie können Multi-Turn-Konversationen führen, bei denen Sie Folgefragen stellen können, die auf früheren Abfragen aufbauen. Weitere Informationen dazu finden Sie unter Multi-Turn-Konversationen in Cortex Analyst.

Die Anfrage enthält eine Frage des Benutzers und die Antwort enthält die Frage des Benutzers und die Antwort des Analysten. Jede Meldung in einer Antwort kann mehrere Inhaltsblöcke unterschiedlichen Typs enthalten. Drei Werte, die derzeit für das Feld type des Inhaltsobjekts unterstützt werden, sind: text, suggestions und sql.

Header der Anforderung

Header

Beschreibung

Authorization

(Erforderliche) Autorisierungstoken. Weitere Informationen dazu finden Sie unter Authentifizierung am Server.

Content-Type

(Erforderlich) Anwendung/json

Text der Anforderung

Der Body der Anfrage enthält die Rolle des Sprechers, die user sein muss, die Frage des Benutzers und einen Pfad zur Datei des semantischen Modells YAML. Die Frage des Benutzers ist in einem Objekt content enthalten, das zwei Felder hat, type und text. text ist auch der einzige zulässige Wert des Feldes type.

Feld

Beschreibung

messages[].role

(Erforderlich) Die Rolle der Entität, die die Meldung erstellt. Derzeit wird nur user unterstützt.

Typ: string:enum

Beispiel: user

messages[].content[]

(Erforderlich) Das Inhaltsobjekt, das Teil einer Meldung ist.

Typ: Objekt

Beispiel:

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

messages[].content[].type

(Erforderlich) Der Inhaltstyp. Derzeit wird nur text unterstützt.

Typ: string:enum

Beispiel: text

messages[].content[].text

(Erforderlich) Die Frage des Benutzers.

Typ: Zeichenfolge

Beispiel: Which company had the most revenue?

semantic_model_file

Pfad zur Datei des semantischen Modells YAML. Muss eine vollständig qualifizierte Stagingbereich-URL sein, einschließlich der Datenbank und des Schemas. Sie können stattdessen das vollständige semantische Modell YAML in das Feld semantic_model eingeben.

Typ: Zeichenfolge

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

semantic_model

Eine Zeichenfolge, die das gesamte semantische Modell YAML enthält. Sie können stattdessen das semantische Modell YAML als Stagingdatei übergeben, indem Sie dessen URL im Feld semantic_model_file angeben.

Typ: Zeichenfolge

Wichtig

Sie müssen entweder semantic_model_file oder semantic_model im Body der Anfrage angeben.

Beispiel

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

Antwort

Diese Operation kann die unten aufgeführten Antwortcodes zurückgeben. Die Antwort hat immer die folgende Struktur. Derzeit werden drei Inhaltstypen für die Antwort unterstützt: text, suggestion und sql. Die Inhaltstypen suggestion und sql schließen sich gegenseitig aus, d. h. wenn die Antwort einen Inhaltstyp sql enthält, enthält sie keinen Inhaltstyp suggestion. Der Inhaltstyp suggestion ist nur dann in einer Antwort enthalten, wenn die Frage des Benutzers mehrdeutig war und Cortex Analyst keine SQL-Anweisung für diese Abfrage liefern konnte.

Um die Vorwärtskompatibilität zu gewährleisten, stellen Sie sicher, dass Ihre Implementierung den Inhaltstyp berücksichtigt und Typen verarbeitet.

Code

Beschreibung

200

Die Anweisung wurde erfolgreich ausgeführt.

Meldung Der Body der Antwort enthält ein Meldungsobjekt, das die folgenden Felder enthält:

  • message: Meldungen der Konversation zwischen dem Benutzer und dem Analysten.

  • message (Objekt): Stellt eine Meldung innerhalb eines Chats dar.

  • message.role (string:enum): Die Entität, von der die Meldung stammt. Eine der folgenden Optionen: user oder analyst.

  • message.content[] (Objekt): Das Inhaltsobjekt, das Teil einer Meldung ist.

  • message.content[].type (string:enum): Der Inhaltstyp der Meldung. Eine der folgenden Optionen: text, suggestion oder sql.

  • message.content[].text (string): Der Text des Inhalts. Wird nur für den Inhaltstyp text zurückgegeben.

  • message.content[].statement (string): Eine SQL-Anweisung. Wird nur für den Inhaltstyp sql zurückgegeben.

  • message.content[].confidence (Objekt): Enthält vertrauensbezogene Informationen. Wird nur für den Inhaltstyp sql zurückgegeben.

  • message.content[].confidence.verified_query_used (Objekt): Stellt die verifizierte Abfrage aus dem geprüften Abfrage-Repository dar, das bei der Erstellung der SQL-Antwort verwendet wird. Wenn keine verifizierte Abfrage verwendet wird, lautet der Feldwert null.

  • message.content[].confidence.verified_query_used.name (string): Der Name der verwendeten verifizierten Abfrage, die aus dem geprüften Abfrage-Repository entnommen wurde.

  • message.content[].confidence.verified_query_used.question (string): Die Frage, die von der verifizierten Abfrage beantwortet wird, extrahiert aus dem geprüften Abfrage-Repository.

  • message.content[].confidence.verified_query_used.sql (string): Die SQL-Anweisung der verwendeten verifizierten Abfrage, die aus dem geprüften Abfrage-Repository entnommen wurde.

  • message.content[].confidence.verified_query_used.verified_at (Ganzzahl): Die numerische Darstellung des Zeitstempels, wann die Abfrage verifiziert wurde, entnommen aus dem geprüften Abfrage-Repository.

  • message.content[].confidence.verified_query_used.verified_by (string): Die Person, die die Abfrage verifiziert hat, entnommen aus dem geprüften Abfrage-Repository.

  • message.content[].suggestions (string): Wenn SQL nicht generiert werden kann, eine Liste der Fragen, für die das semantische Modell SQL generieren kann. Wird nur für den Inhaltstyp suggestion zurückgegeben.

  • message.content[].warnings: Liste der Warnungen des Analysten bezüglich der Anfrage des Benutzers.

  • message.content[].warnings (Liste): Stellt eine Sammlung von Warnungen zu Benutzeranfragen und semantischen Modellen dar.

  • message.content[].warnings[].message (string): Enthält eine detaillierte Beschreibung einer einzelnen Warnung.

{
    "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

Feedback senden

POST /api/v2/cortex/analyst/feedback

Liefert qualitatives Feedback von Benutzern. Innerhalb von Snowsight wird das Feedback in Semantic Model Admins unter Monitoring angezeigt.

Header der Anforderung

Header

Beschreibung

Authorization

(Erforderliche) Autorisierungstoken. Weitere Informationen dazu finden Sie unter Authentifizierung am Server.

Content-Type

(Erforderlich) Anwendung/json

Text der Anforderung

Feld

Beschreibung

request_id

(Erforderlich) Die ID der Anfrage, die Sie zum Senden einer Meldung gestellt haben. Wird im Feld request_id von /api/v2/cortex/analyst/message zurückgegeben. Weitere Informationen dazu finden Sie unter Antwort.

Typ: Zeichenfolge

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

positive

(Erforderlich) Ob das Feedback positiv oder negativ ist. true für positiv oder „Daumen hoch“, false für negativ oder „Daumen runter“.

Typ: Boolean

Beispiel:

true

feedback_message

(Optional) Die Feedback-Meldung des Benutzers.

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

Antwort

Leerer Antworttext mit Statuscode 200.

Anforderungen an die Zugriffssteuerung

Informationen zu den erforderlichen Berechtigungen finden Sie unter Anforderungen an die Zugriffssteuerung.

Einzelheiten zum Authentifizieren auf API finden Sie unter Authentifizierung von Snowflake REST APIs mit Snowflake.

Sprache: Deutsch