Cortex Analyst REST API

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

发送消息

POST /api/v2/cortex/analyst/message

使用请求中提供的语义模型为给定的问题生成 SQL 查询。您可以进行多轮对话，在对话中可以基于之前问题提出后续问题。有关更多信息，请参阅 Cortex Analyst 中的多轮对话。

请求包括用户问题，而响应包括用户问题和分析师的回复。响应中的每条消息可以有多个不同类型的内容块。内容对象的 type 字段目前支持的三个值是：text、suggestions 和 sql。

请求标头

标头

描述

Authorization

（必需）授权令牌。有关更多信息，请参阅 对服务器进行身份验证。

Content-Type

（必需）应用程序/json

请求正文

请求正文包含说话者的角色（必须是 user）、用户的问题和语义模型 YAML 文件的路径。用户问题包含在一个 content 对象中，该对象具有两个字段，分别为 type 和 text。text 也是字段 type 的唯一允许值。

字段

描述

messages[].role

（必需）用于创建消息的实体的角色。目前仅支持 user。

类型：string:enum

示例：user

messages[].content[]

（必需）作为消息一部分的内容对象。

类型：对象

示例：

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

messages[].content[].type

（必填）内容类型。目前仅支持 text。

类型：string:enum

示例：text

messages[].content[].text

（必填）用户的问题。

类型：字符串

示例：Which company had the most revenue?

semantic_model_file

语义模型 YAML 文件的路径。必须是一个包括数据库和架构的完全限定的暂存区 URL。您可以在 semantic_model 字段中提供完整的语义模型 YAML。

类型：字符串

示例：@my_db.my_schema.my_stage/my_semantic_model.yaml

semantic_model

包含整个语义模型 YAML 的字符串。您可以通过在 semantic_model_file 字段中提供其 URL 将语义模型 YAML 作为暂存文件进行传递。

类型：字符串

重要

您必须在请求正文中提供 semantic_model_file 或 semantic_model。

示例

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

响应

此操作可以返回下面列出的响应代码。响应始终具有以下结构。目前，响应支持三种内容类型：text、suggestion 和 sql。由于内容类型 suggestion 和 sql 是互斥的，因此，如果响应包含 sql 内容类型，则不会包含 suggestion 内容类型。suggestion 内容类型仅在用户问题不明确且 Cortex Analyst 无法为查询返回 SQL 语句时才会包含在响应中。

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

代码

描述

200

语句已成功执行。

响应正文包含一个消息对象，该对象包含以下字段：

  • message：用户和分析师之间的对话消息。

  • :code:`message`（对象）：代表聊天中的消息。

  • message.role (string:enum)：生成消息的实体。user 或 analyst 之一。

  • :code:`message.content[]`（对象）：作为消息一部分的内容对象。

  • message.content[].type (string:enum)：消息的内容类型。text、suggestion 或 sql 中的一个。

  • message.content[].text`（字符串）：内容的文本。仅针对内容类型 ``text` 返回。

  • message.content[].statement`（字符串）：一条 SQL 语句。仅针对内容类型 ``sql` 返回。

  • message.content[].confidence`（对象）：包含与置信度相关的信息。仅对 ``sql` 内容类型返回。

  • message.content[].confidence.verified_query_used`（对象）：表示用于 SQL 响应生成的验证查询库中的验证查询。如果没有使用验证查询，则字段值为 ``null`。

  • :code:`message.content[].confidence.verified_query_used.name`（字符串）：从验证查询库中提取的验证查询的名称。

  • :code:`message.content[].confidence.verified_query_used.question`（字符串）：从验证查询库中提取的，验证查询回答的问题。

  • :code:`message.content[].confidence.verified_query_used.sql`（字符串）：从验证查询库中提取的，所用验证查询的 SQL 语句。

  • :code:`message.content[].confidence.verified_query_used.verified_at`（整型）：从验证查询库中提取的，验证查询时的时间戳数字表示。

  • :code:`message.content[].confidence.verified_query_used.verified_by`（字符串）：从验证查询库中提取的，验证查询的人。

  • message.content[].suggestions`（字符串）：如果无法生成 SQL，则语义模型可以为其生成 SQL 的问题列表。仅针对内容类型 ``suggestion` 返回。

  • message.content[].warnings：分析师关于用户请求的警告列表。

  • :code:`message.content[].warnings`（列表）：表示有关用户请求和语义模型的警告集合。

  • :code:`message.content[].warnings[].message`（字符串）：包含一个单独警告的详细描述。

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

发送反馈

POST /api/v2/cortex/analyst/feedback

提供定性最终用户反馈。在 Snowsight 中，反馈显示在 Monitoring 下方的 Semantic Model Admins 中。

请求标头

标头

描述

Authorization

（必需）授权令牌。有关更多信息，请参阅 对服务器进行身份验证。

Content-Type

（必需）应用程序/json

请求正文

字段

描述

request_id

（必填）您发送消息的请求 ID。在 /api/v2/cortex/analyst/message 的 request_id 字段中返回。有关更多信息，请参阅 响应。

类型：字符串

示例：75d343ee-699c-483f-83a1-e314609fb563

positive

（必填）反馈是积极的还是消极的。积极的或“点赞”为 true，消极的或“点踩”为 false。

类型：布尔

示例：

true

feedback_message

（可选）用户的反馈消息。

示例：This is the best answer I've ever seen!

响应

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

访问控制要求

有关所需权限的信息，请参阅 访问控制要求。

有关如何对 API 进行身份验证的详细信息，请参阅 使用 Snowflake 对 Snowflake REST APIs 进行身份验证。

语言: 中文