Cortex Analyst REST API¶

使用此 API 通过自然语言查询来回答有关数据的问题。

发送消息

POST /api/v2/cortex/analyst/message

Generates a SQL query for the given question using a semantic model or semantic view provided in the request. One or more models can be specified; when multiple models are specified, Cortex Analyst chooses the most appropriate one. You can have multi-turn conversations where you can ask follow-up questions that build upon previous queries. For more information, see Multi-turn conversation in Cortex Analyst.

The request includes a user question; 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.

响应可以在处理完成后立即发送，也可以在生成响应时逐步发送。

请求标头

请求正文

在请求正文中：

• Set the last messages[].role field to the role of the speaker, which must be user.

• Include the user’s question in the content object. In this object:

  • Set type to text.
  • Set text to the user’s question.

• 包含以下项之一：

  • The YAML specification for a semantic view.
  • 包含语义视图规范的 YAML 文件路径。此文件必须处于暂存区中。
  • 语义视图的名称。

下表描述了可在请求正文中设置的字段：

{
  /* ... */
  "semantic_models": [
    {"semantic_view": "my_db.my_sch.my_sem_view_1" },
    {"semantic_view": "my_db.my_sch.my_sem_view_2" }
  ]
  /* ... */
}

{
  /* ... */
  "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"
}

非流式传输响应

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.

When the request contains a semantic_models field, the response includes a semantic_model_selection field that indicates which semantic model was chosen for the request.

为确保向前兼容性，请确保实施考虑了内容类型并可处理类型。

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

Copy codeExpand code block

{
    "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-sonnet-4-5"
        ],
        "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"
    }
}

Show lessSee more

Scroll to top

流式传输响应

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 (https://developer.mozilla.org/en-US/docs/Web/API/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: Contains any warnings encountered during processing. Warnings do not stop processing.
• response_metadata: Sent at the end of a response to display data about request 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" }

Use the index field in the message.content.delta respnoses to determine which field in the full response the event is part of. For example, here the first two delta events use index 0, which means they are part of the first field (element 0) in the content array of the non-streaming response. Similarly, the delta event that contains the SQL response uses index 1.

带建议的示例

此示例包含针对模糊问题的建议问题。以下是非流式传输响应：

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

In this example, the content field of the non-streaming response is an array. One of the elements of content is the suggestions array. So the meaning of index fields for text and suggestions delta events refer to the location of elements in these two different arrays. You will need to keep track of these indexes separately when assembling the full response.

其他示例

You can find a Streamlit streaming client for Cortex Analyst in the Cortex Analyst GitHub repo (https://github.com/Snowflake-Labs/sfguide-getting-started-with-cortex-analyst/blob/main/cortex_analyst_streaming_demo.py). This demo must be run locally; SiS does not currently support streaming.

请参阅 AI/ML Studio 中（在 Snowsight 中）的 Cortex Analyst Playground，了解流式传输响应的交互式演示。

流式传输事件架构

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

status

message.content.delta

error

Copy codeExpand code block

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

Show lessSee more

Scroll to top

warnings

Copy codeExpand code block

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

Show lessSee more

Scroll to top

response_metadata

Copy codeExpand code block

ResponseMetadata:
type: object
description: Details about request processing

Show lessSee more

Scroll to top

发送反馈

POST /api/v2/cortex/analyst/feedback

Provides qualitative end-user feedback. Within Snowsight, the feedback is shown in Snowsight → AI & ML → Cortex Analyst → Select Semantic View → Monitoring tab.

请求标头

请求正文

响应

空响应正文，状态代码 200。

访问控制要求

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

For details about authenticating to the API, see Authenticating Snowflake REST APIs with Snowflake.