Cortex Analyst REST API

Use this API to answer questions about your data with natural language queries.

Send message

POST /api/v2/cortex/analyst/message

Generates a SQL query for the given question using the semantic model provided in the request. Note that the API is stateless, so only single-turn conversations are supported.

The request includes a user question and the response includes the user question and the analyst response. Each message in a response can have multiple content blocks of different types. Three values that are currently supported for the type field of the content object are: text, suggestions, and sql.

Request Headers

Header

Description

Authorization

(Required) Authorization token. For more information, see Authenticating to the server.

Content-Type

(Required) application/json

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.

Field

Description

messages[].role

(Required) The role of the entity that is creating the message. Currently only supports user.

Type: string:enum

Example: user

messages[].content[]

(Required) The content object that is part of a message.

Type: object

Example:

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

messages[].content[].type

(Required) The content type. Currently only text is supported.

Type: string:enum

Example: text

messages[].content[].text

(Required) The user’s question.

Type: string

Example: Which company had the most revenue?

semantic_model_file

Path to the semantic model YAML file. Must be a fully qualified stage URL including the database and schema. You can instead provide the complete semantic model YAML in the semantic_model field.

Type: string

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

semantic_model

A string containing the entire semantic model YAML. You can instead pass the semantic model YAML as a staged file by providing its URL in the semantic_model_file field.

Type: string

Important

You must provide either semantic_model_file or semantic_model in the request body.

Example

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

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

Code

Description

200

The statement was executed successfully.

The body of the response contains a message object that contains the following fields:

  • message: Messages of the conversation between the user and analyst.

  • message (object): Represents a message within a chat.

  • message.role (string:enum): The entity that produced the message. One of user or analyst.

  • message.content[] (object): The content object that is part of a message.

  • message.content[].type (string:enum): The content type of the message. One of text, suggestion, or sql.

  • message.content[].text (string): The text of the content. Only returned for content type text.

  • message.content[].statement (string): A SQL statement. Only returned for content type sql.

  • message.content[].confidence (object): Contains confidence-related information. Only returned for the sql content type.

  • message.content[].confidence.verified_query_used (object): Represents the verified query from Verified Query Repository used in SQL response generation. If no verified query used, the field value is null.

  • message.content[].confidence.verified_query_used.name (string): The name of the verified query used, extracted from the Verified Query Repository.

  • message.content[].confidence.verified_query_used.question (string): The question that is answered by the verified query, extracted from the Verified Query Repository.

  • message.content[].confidence.verified_query_used.sql (string): The SQL statement of the verified query used, extracted from the Verified Query Repository.

  • message.content[].confidence.verified_query_used.verified_at (integer): The numeric representation of the timestamp when the query is verified, extracted from the Verified Query Repository.

  • message.content[].confidence.verified_query_used.verified_by (string): The person who verified the query, extracted from the Verified Query Repository.

  • message.content[].suggestions (string): If SQL cannot be generated, a list of questions the semantic model can generate SQL for. Only returned for content type suggestion.

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

Access control requirements

For information on the required privileges, see Access control requirements.

For details on how to authenticate to the API, see Authenticating Snowflake REST APIs with Snowflake.

Language: English