Cortex Analyst REST API¶

Request Headers¶

Request Body¶

The request body contains the role of the speaker which must be user, the user’s question and a path to the semantic model YAML file. The user question is contained in a content object which has two fields, type and text. text is also the only allowed value of the field type.

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

Non-streaming response¶

This operation can return the response codes listed below. The response always has the following structure. Currently, three content types are supported for the response, text, suggestion, and sql. The content types suggestion and sql are mutually exclusive so that if the response contains a sql content type, it won’t contain a suggestion content type, and vice versa. The suggestion content type is only included in a response if the user question was ambiguous and Cortex Analyst could not return a SQL statement for that query.

To ensure forward compatibility, make sure your implementation takes the content type into account and handles types.

By default, the response is returned all at once after Cortex Analyst has fully processed the user’s question. See Streaming response for the format of streaming mode responses.

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

Streaming response¶

Streaming mode lets your client receive responses as they are generated by Cortex Analyst, rather than waiting for the entire response to be generated. This improves the perceived responsiveness of your application, especially for long-running queries, because users begin seeing output much sooner. Streaming responses also provide status information that can help you understand where Cortex Analyst is in the process of generating a response, and warnings that can help understand what went wrong when Cortex Analyst doesn’t work as you expected.

To receive a streaming response, set the stream field in the request body to true. Streaming responses use server-sent events.

Cortex Analyst sends five distinct types of events in a streaming response:

• status: Conveys status updates about the SQL generation process.

• message.content.delta: Contains a piece of the response. This event is sent multiple times.

• error: Indicates that Cortex Analyst has encountered an error and cannot continue processing the request. No further message.content.delta events will be sent.

• warnings: Sent at the end of a response to convey any warnings encountered during processing. Warnings do not stop processing.

• done: Sent to indicate that processing is complete and no further message.content.delta events will be sent.

Of these, the message.content.delta events are the most crucial to understand, because they contain the actual response content. Each delta contains tokens from some field in the complete response. It is possible for each delta event to contain anywhere between a single character to the full response, and they may be of different lengths. You receive these tokens as they are generated; it is up to you to assemble them into the final response.

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

Streaming event schemas¶

The following are the OpenAPI/Swagger schemas of the events sent by Cortex Analyst in a streaming response.

status

message.content.delta

error

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

warnings

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

Request Headers¶

Request Body¶

Response¶

Empty response body with status code 200.