查询执行状态

读取当前身份已执行 SQL 的状态和结果 ID（statement_id）。只有状态为 success 时，才能使用该结果 ID 读取或下载结果。

POST https://moi.matrixorigin.cn/newmoi/query/describe

调用前准备

准备个人访问令牌、工作区 ID，以及执行 SQL响应中的查询 ID。

下方示例使用：

• $AI_STUDIO_API_KEY：实际个人访问令牌，通过 X-API-Key Header 传递。

• $WORKSPACE_ID：查询所在的工作区 ID，通过 X-Workspace-ID Header 传递。

• $QUERY_ID：执行 SQL 响应中的 data.query_id。

请求体

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

请求示例

curl -X POST "https://moi.matrixorigin.cn/newmoi/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\"}"

成功响应

statement_id 用于读取或下载结果，不能用 query_id 替代。状态为 success 时，可使用 Statement 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.query_id	string	查询 ID。
data.created_at	string	执行记录的创建时间。
data.statement_id	string	结果 ID；读取或下载本次 SQL 的结果时使用。
data.db_name	string	执行时指定的数据库。
data.status	string	执行状态。
data.err_msg	string	执行错误信息；仅在有错误信息时返回。
data.rows_affected	integer	受影响行数。

错误响应

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

常见 HTTP 错误

HTTP 状态码	常见原因	建议操作
400	请求体不是有效 JSON，或缺少 query_id。	检查请求体和查询 ID。
401	凭据缺失或无效。	检查访问令牌。
403	当前身份没有读取该查询记录的权限。	使用创建该查询的身份，或联系管理员授权。
404	查询 ID 不存在，或不属于当前身份。	检查 query_id，并确认使用相同身份调用。
500	服务端无法读取查询记录。	记录错误信息后重试。

后续操作

状态表示已成功时，用返回的结果标识查询执行结果或下载执行结果。仍在执行且需要中止时取消执行。

最后更新于 2026 年 8 月 22 日