运行 SQL 并读取结果

使用 SQL API 提交一条查询，取得 query_id，读取查询状态中的 statement_id，再获取结果行。创建请求成功不表示查询结果已经可读。

前提条件

• 已按SQL 概览准备认证信息和工作区作用域。

• 已确认目标数据库名称以及当前 MatrixOne 角色具有相应权限。

• 应用可以安全处理 SQL 文本和返回行，不把敏感内容完整写入日志。

export PRODUCT_API_BASE_URL='<Product API Base URL ending in /newmoi>'
export PRODUCT_API_KEY='<your-personal-access-token>'
export WORKSPACE_ID='<workspace-id>'
export DATABASE_NAME='<database-name>'

查询生命周期

POST /query/execute
→ 保存 query_id
→ POST /query/describe
→ 检查 status 并保存 statement_id
→ POST /query/result
→ 读取 columns、result 和 total

query_id 标识本次 Product SQL 请求；statement_id 标识可读取结果和历史详情的 MatrixOne Statement。两者不能互换。

提交查询

curl -X POST "$PRODUCT_API_BASE_URL/query/execute" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"db_name\": \"$DATABASE_NAME\",
    \"query\": \"SELECT 1 AS n\",
    \"offset\": 0,
    \"limit\": 20
  }"

字段	类型	必需	说明
query	string	是	要运行的 SQL。调用方负责正确引用对象名和处理输入。
db_name	string	否	当前查询使用的数据库。涉及未限定表名时应明确提供。
sql_type	string	否	SQL 来源或类型标识。只在调用场景有明确契约值时发送。
offset	integer	否	首次结果窗口的起始位置。示例值不代表固定默认值。
limit	integer	否	首次结果窗口的行数限制。服务端会限制实际返回规模。

SQL 接口当前返回 code: 200 的响应包络，与部分 Product API 页面中的 code: "OK" 不同：

{
  "code": 200,
  "data": {
    "id": "<QUERY_ID>",
    "query_id": "<QUERY_ID>"
  }
}

保存 data.query_id。

读取查询状态

export QUERY_ID='<query-id-from-execute>'

curl -X POST "$PRODUCT_API_BASE_URL/query/describe" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d "{\"query_id\": \"$QUERY_ID\"}"

{
  "code": 200,
  "data": {
    "query_id": "<QUERY_ID>",
    "statement_id": "<STATEMENT_ID>",
    "db_name": "<DATABASE_NAME>",
    "status": "<STATUS>",
    "err_msg": "",
    "rows_affected": 0
  }
}

字段	返回条件	说明
data.query_id	查询存在时	与提交请求返回的查询 ID 对应。
data.statement_id	Statement 已建立时	读取结果、详情和 Profile 时使用。
data.status	查询存在时	查询当前状态。只根据当前返回值决定继续等待、读取结果或处理失败。
data.err_msg	查询存在时	运行错误摘要；空字符串不替代对最终状态的判断。
data.rows_affected	运行产生该信息时	写操作影响的行数。

客户端应设置轮询间隔、总等待时间和最大次数。状态进入失败或完成后停止轮询；不要对同一个查询无限请求。

读取结果

取得 statement_id 后，请求结果窗口：

export STATEMENT_ID='<statement-id-from-describe>'

curl -X POST "$PRODUCT_API_BASE_URL/query/result" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"statement_id\": \"$STATEMENT_ID\",
    \"offset\": 0,
    \"limit\": 20
  }"

{
  "code": 200,
  "data": {
    "query_id": "<QUERY_ID>",
    "statement_id": "<STATEMENT_ID>",
    "status": "<STATUS>",
    "offset": 0,
    "limit": 20,
    "total": 1,
    "columns": [
      {
        "name": "n",
        "type": "BIGINT"
      }
    ],
    "result": [
      [
        {
          "String": "1",
          "Valid": true
        }
      ]
    ]
  }
}

结果行按 columns 的顺序解释。每个单元格包含字符串表示和有效性标记；调用方应结合列类型完成转换，并正确处理空值。结果为空时，响应可能使用 empty_set 说明，不要把空结果当作请求失败。

取消查询

只有仍在运行的查询才有取消意义：

curl -X POST "$PRODUCT_API_BASE_URL/query/kill" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d "{\"query_id\": \"$QUERY_ID\"}"

取消请求返回后，再调用 /query/describe 确认状态。取消不会回滚查询在取消前已经提交的外部副作用或数据库事务结果。

使用 WebSocket

GET /query/ws 提供 SQL 编辑器 WebSocket 入口。使用 PAT 时，握手同时包含：

• X-API-Key: <PAT>；

• X-Workspace-ID: <WORKSPACE_ID>；

• Sec-WebSocket-Protocol: moi-api-key, moi-api-key.<PAT>。

不要把 PAT 放入 URL 查询参数。浏览器或 WebSocket 库应按其 API 分别设置普通 Header 和子协议。

常见问题

现象	先检查	下一步
运行返回权限错误	工作区 ID、有效角色、数据库和对象权限	切换到有权限的角色后重新运行，不只检查工作区管理员身份。
Result 提示找不到结果	是否使用 statement_id、查询是否已到可读状态	重新调用 Describe，取得最新 statement_id 和状态。
结果被截断	total、offset 和 limit	分页读取或使用结果下载接口，不一次加载全部数据。
查询长时间未完成	query_id、状态和 err_msg	停止无界轮询，按需要取消并保存标识用于排查。
WebSocket 握手失败	Header、子协议和 ws/wss 地址	按 HTTP Endpoint 的 Scheme 生成对应 WebSocket 地址，并重新设置子协议。

下一步

• 查看 SQL 历史与 Profile

• 将 SQL 保存为工作簿版本

• 使用 Product SDK 运行 SQL

最后更新于 2026 年 8 月 14 日