Cortex Analyst REST API¶

Header der Anforderung¶

Text der Anforderung¶

Im Anfrage-Body:

• Setzen Sie das letzte Feld messages[].role auf die Rolle des Sprechers, die user sein muss.

• Nehmen Sie die Frage des Benutzers in das Objekt content auf. In diesem Objekt:

  • Setzen Sie type auf text.

  • Stellen Sie text auf die Frage des Benutzers ein.

• Fügen Sie einen der folgenden Punkte ein:

  • Die Spezifikation des semantischen Modells in YAML.

  • Der Pfad zu der YAML-Datei, die die Spezifikation des semantischen Modells enthält. Diese Datei muss sich in einem Stagingbereich befinden.

  • Der Name der semantischen Ansicht.

Die folgende Tabelle beschreibt die Felder, die Sie im Body der Anfrage festlegen können:

{
  /* ... */
  "semantic_view": "MY_DB.MY_SCHEMA.SEMANTIC_VIEW"
  /* ... */
}

{
  /* ... */
  "semantic_view": "\"my-database\".\"my-schema\".\"\"my-semantic-view\"\""
  /* ... */
}

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

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "which company had the most revenue?"
        }
      ]
    }
  ],
  "semantic_view": "MY_DB.MY_SCH.MY_SEMANTIC_VIEW"
}

Antwort ohne Streaming¶

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 und umgekehrt. 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.

Wenn die Anfrage ein semantic_models-Feld enthält, enthält die Antwort ein semantic_model_selection-Feld, das angibt, welches semantische Modell für die Anfrage gewählt wurde.

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

In der Standardeinstellung wird die Antwort auf einmal zurückgegeben, nachdem Cortex Analyst die Frage des Benutzers vollständig bearbeitet hat. Siehe Streaming-Antwort für das Format der Antworten im Streaming-Modus.

{
    "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"
        }
    ],
    "response_metadata": {
        "model_names": [
            "claude-3-5-sonnet"
        ],
        "cortex_search_retrieval": [
            {
                "service": "my_db.my_schema.my_search_service",
                "response_body": {
                    "results": [
                        {
                            "CUST_NAME": "customer1"
                        }
                    ],
                    "request_id": "request1"
                },
                "query": "'customer1'"
            }
        ],
        "question_category": "CLEAR_SQL"
    }
}

Copy

Streaming-Antwort¶

Im Streaming-Modus kann Ihr Client die Antworten empfangen, sobald sie von Cortex Analyst generiert werden, anstatt darauf zu warten, dass die gesamte Antwort generiert wird. Dies verbessert die wahrgenommene Reaktionsfähigkeit Ihrer Anwendung, insbesondere bei lang laufenden Abfragen, da die Benutzer die Ausgabe viel früher sehen. Streaming-Antworten liefern auch Statusinformationen, die Ihnen helfen können, zu verstehen, an welcher Stelle Cortex Analyst bei der Erzeugung einer Antwort steht, sowie Warnungen, die Ihnen helfen können zu verstehen, was schief gelaufen ist, wenn Cortex Analyst nicht wie erwartet funktioniert.

Um eine Streaming-Antwort zu erhalten, setzen Sie das Feld stream im Anfrage-Body auf true. Streaming-Antworten verwenden vom Server gesendete Ereignisse.

Cortex Analyst sendet fünf verschiedene Arten von Ereignissen in einer Streaming-Antwort:

• status: Informiert Sie über den aktuellen Status des SQL-Generierungsprozesses.

• message.content.delta: Enthält einen Teil der Antwort. Dieses Ereignis wird mehrmals gesendet.

• error: Zeigt an, dass Cortex Analyst auf einen Fehler gestoßen ist und die Bearbeitung der Anfrage nicht fortsetzen kann. Es werden keine weiteren message.content.delta-Ereignisse gesendet.

• warnings: Enthält alle während der Verarbeitung aufgetretenen Warnungen. Warnungen stoppen die Verarbeitung nicht.

• response_metadata: Wird am Ende einer Antwort gesendet, um Daten zur Verarbeitung der Anfrage anzuzeigen.

• done: Wird gesendet, um anzuzeigen, dass die Verarbeitung abgeschlossen ist und keine weiteren message.content.delta-Ereignisse gesendet werden.

Von diesen sind die message.content.delta-Ereignisse am wichtigsten zu verstehen, da sie den eigentlichen Inhalt der Antwort enthalten. Jedes delta enthält Token aus einem Feld der vollständigen Antwort. Es ist möglich, dass jedes delta-Ereignis alles zwischen einem einzelnen Zeichen und der gesamten Antwort enthält und dass sie unterschiedlich lang sein können. Sie erhalten diese Token, sobald sie generiert werden. Es liegt an Ihnen, sie zu der endgültigen Antwort zusammenzusetzen.

{
    "message": {
        "role": "analyst",
        "content": [
            {
                "type": "text",
                "text": "This is how we interpreted your question and this is how the sql is generated"
            },
            {
                "type": "sql",
                "statement": "SELECT * FROM table"
            }
        ]
    }
}

event: status
data: { status: "interpreting_question" }

event: message.content.delta
data: {
  index: 0,
  type: "text",
  text_delta: "This is how we interpreted your question"
}

event: status
data: { status: "generating_sql" }

event: status
data: { status: "validating_sql" }

event: message.content.delta
data: {
  index: 0,
  type: "text",
  text_delta: " and this is how the sql is generated"
}

event: message.content.delta
data: {
  index: 1,
  type: "sql",
  statement_delta: "SELECT * FROM table"
}

event: status
data: { status: "done" }

{
    "message": {
        "role": "analyst",
        "content": [
            {
                "type": "text",
                "text": "Your question is ambigous, here are some alternatives:"
            },
            {
                "type": "suggestions",
                "suggestions": [
                    "which company had the most revenue?",
                    "which company placed the most orders?"
                ]
            }
        ]
    }
}

event: status
data: { status: "interpreting_question" }

event: message.content.delta
data: {
  index: 0,
  type: "text",
  text_delta: "Your question is ambigous,"
}

event: status
data: { status: "generating_suggestions" }

event: message.content.delta
data: {
  index: 0,
  type: "text",
  text_delta: " here are some alternatives:"
}

event: message.content.delta
data: {
  index: 1,
  type: "suggestions",
  suggestions_delta: {
    index: 0,
    suggestion_delta: "which company had",
  }
}

event: message.content.delta
data: {
  index: 1,
  type: "suggestions",
  suggestions_delta: {
    index: 0,
    suggestion_delta: " the most revenue?",
  }
}

event: message.content.delta
data: {
  index: 1,
  type: "suggestions",
  suggestions_delta: {
    index: 1,
    suggestion_delta: "which company placed",
  }
}

event: message.content.delta
data: {
  index: 1,
  type: "suggestions",
  suggestions_delta: {
    index: 1,
    suggestion_delta: " the most orders?",
  }
}

event: status
data: { status: "done" }

Schemata für Streaming-Ereignisse¶

Im Folgenden finden Sie die OpenAPI/Swagger-Schemata der Ereignisse, die von Cortex Analyst in einer Streaming-Antwort gesendet werden.

Status

message.content.delta

Fehler

StreamingError:
type: object
properties:
  message:
    type: string
    description: A description of the error
  code:
    type: string
    description: The Snowflake error code categorizing the error
  request_id:
    type: string
    description: Unique request ID

Copy

Warnungen

Warnings:
type: object
description: Warnings found while processing the request
properties:
  warnings:
    type: array
    items:
      $ref: "#/components/schemas/Warning"
Warning:
type: object
title: The warning object
description: Represents a warning within a chat.
properties:
  message:
    type: string
    description: A human-readable message describing the warning

Copy

response_metadata

ResponseMetadata:
type: object
description: Details about request processing

Copy

Header der Anforderung¶

Text der Anforderung¶

Antwort¶

Leerer Antworttext mit Statuscode 200.