SQL API

SQL Product API 对应 AI Studio SQL 编辑器：管理工作簿、读取 MatrixOne 元数据、启动 查询、获取结果与 Profile，并查询执行历史。AI Studio 工作区权限只控制产品入口； SQL 是否允许执行，仍由 MatrixOne 数据库角色决定。

工作簿与版本

方法与路径	用途
POST /newmoi/workbook/create	创建工作簿
POST /newmoi/workbook/list	列出工作簿
POST /newmoi/workbook/detail	读取工作簿详情
POST /newmoi/workbook/update	更新工作簿元数据
POST /newmoi/workbook/delete	删除工作簿
POST /newmoi/workbook/version/list	列出工作簿版本
POST /newmoi/workbook/version/create	创建版本
POST /newmoi/workbook/version/update	更新版本
POST /newmoi/workbook/version/save	保存版本

工作簿保存编辑器状态；创建或保存工作簿不会执行 SQL。应保存服务端返回的 workbook ID 与 version ID。覆盖协作内容前，先读取最新版本并处理冲突，不能假设内存中的副本仍是 最新状态。

数据库元数据

/newmoi/meta 下的接口覆盖数据库列表与树、表、表详情、字段、字段统计和 DDL。应从 服务端返回内容中选择已有数据库和表，并用这些名称生成编辑器辅助信息。

/newmoi/meta/db/drop、/newmoi/meta/table/drop 和 /newmoi/meta/view/drop 是破坏性 SQL 操作。提交前，应向调用者展示完整限定对象名、 当前工作区 / 数据库连接与已知依赖。Product API 返回成功并不提供恢复能力；备份与 恢复仍属于数据库职责。

执行并跟踪查询

通过以下接口启动查询：

POST /newmoi/query/execute

后续操作必须使用启动接口返回的 ID：

路径	用途
/newmoi/query/describe	读取 Query 或 Statement 状态
/newmoi/query/result	读取分页或受限结果
/newmoi/query/result/download	下载查询结果
/newmoi/query/profile	查看执行 Profile
/newmoi/query/detail	读取查询详情
/newmoi/query/kill	请求取消
GET /newmoi/query/ws	启用时取得查询 WebSocket 入口

查询可能在首个 HTTP 请求结束后继续运行。应轮询 Query / Statement 状态，或按文档 使用 WebSocket，直到终态。取消请求只有在状态确认后才算完成。交互式结果应设置明确的 行数上限，大结果使用下载接口。

SQL 文本与返回行可能包含敏感数据，不应完整写入应用日志。参数化方式由部署环境的 execute Schema 定义；不要用不安全的字符串拼接模拟参数。

查询历史

POST /newmoi/query/history 列出查询记录， POST /newmoi/query/history/overview 返回汇总。History 属于工作区产品上下文， SQL 执行授权仍在数据库层。与数据库日志关联时，应保留服务端时间戳与 ID。

失败时应提供 Query / Statement ID、状态、数据库、服务端 request ID 和脱敏错误。 只重试临时的传输或服务故障；语法错误、权限拒绝、对象不存在和可稳定复现的数据错误 需要修正请求。

Catalog 资产操作见数据、文件与连接器。

最后更新于 2026 年 8 月 8 日