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. Beachten Sie, dass die API zustandslos ist, sodass nur einfache Konversationen unterstützt werden.

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[].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": {
        "role": "analyst",
        "content": [
            {
                "type": "text",
                "text": "We interpreted your question as ..."
            },
            {
                "type": "sql",
                "statement": "SELECT * FROM table"
            }
        ]
    }
}
Copy
Sprache: Deutsch