查看执行状态¶

查看一条 SQL 查询的当前状态。查询成功后，响应会返回读取或下载结果所需的结果 ID。

POST https://api.moi.matrixorigin.cn/v5/query/describe

调用前准备¶

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。
执行 SQL，记录响应中的查询 ID（query_id）。

请求体¶

将 $AI_STUDIO_API_KEY、$WORKSPACE_ID 和 $QUERY_ID 替换为实际值。

输入示例

curl -X POST "https://api.moi.matrixorigin.cn/v5/query/describe" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d "{\"query_id\": \"$QUERY_ID\"}"

参数说明

参数	类型	是否必填	说明
`query_id`	string	是	执行 SQL 返回的查询 ID。

成功响应¶

查询成功后，记录结果 ID（statement_id）。读取或下载结果时不能用查询 ID 代替结果 ID。

响应示例

{"code": 200, "data": {"query_id": "query_01", "created_at": "2026-08-18T10:00:00Z", "statement_id": "statement_01", "db_name": "sales", "status": "success", "rows_affected": 1}}

字段说明

通用字段

字段	类型	说明
`code`	integer	成功时为 `200`。
`data`	object	查询执行状态。

执行状态

下面表格展开响应示例中的 data 对象；每一行是该对象的一个字段。

字段	类型	说明
`query_id`	string	查询 ID。
`created_at`	string	执行记录的创建时间。
`statement_id`	string	读取或下载结果使用的结果 ID。
`db_name`	string	执行时指定的数据库。
`status`	string	执行状态。
`rows_affected`	integer	受影响行数。

错误响应¶

响应示例

{"code": 404, "message": "SQL 查询不存在"}

字段说明

字段	类型	说明
`code`	integer	错误状态码。
`message`	string	错误信息。

后续操作¶

查询成功后，使用结果 ID 查看执行结果或下载执行结果。查询仍在运行且需要停止时，可取消执行。

最后更新于 2026 年 9 月 8 日