查看 SQL 执行计划¶

查看一条 SQL 的执行计划（Profile），用于分析 SQL 的执行步骤和资源使用情况。默认只查看当前身份执行的记录；具备相应权限时，可以查看工作区范围的记录。

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

调用前准备¶

准备有当前工作区访问权限的个人访问令牌和当前工作区 ID。先查看 SQL 执行记录，选择需要分析的记录并记下其语句 ID 和执行时间。

请求示例¶

以下示例读取指定语句在一分钟时间窗口内的执行计划。

curl -X POST "https://moi.matrixorigin.cn/newmoi/query/profile" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "statement_id": "'"$STATEMENT_ID"'",
    "start": "2026-08-26 09:44:00",
    "end": "2026-08-26 09:46:00"
  }'

请求体¶

参数	类型	是否必填	说明
statement_id	string	是	所选 SQL 执行记录的语句 ID。
start	string	是	查询开始时间，格式为 YYYY-MM-DD HH:MM:SS。
end	string	是	查询结束时间，格式为 YYYY-MM-DD HH:MM:SS。
scope	string	否	查看当前身份或当前工作区的记录。

查看范围¶

scope 值	可查看的记录	权限条件
self	当前身份的记录。	默认范围。
workspace	工作区范围的记录。	需要工作区审计读取权限。

指定查询时间范围¶

开始和结束时间必须同时填写，并覆盖所选记录的执行时间。当前接口使用不含时区的“年-月-日时:分:秒”格式；列表显示的时间包含时区，填写前需转换为上述格式。例如，列表显示 2026-08-26T09:45:35Z 时，可使用覆盖该时刻的 2026-08-26 09:44:00 至 2026-08-26 09:46:00 时间范围。

使用所选执行记录¶

将所选记录的语句 ID 填入语句 ID 字段，并使用覆盖该记录执行时间的时间范围填写开始和结束时间字段。

成功响应¶

成功时返回 HTTP 200 和执行计划。没有保存的执行计划时，仍会成功响应并说明没有可用计划。

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "statement_id": "5c6f22fb-ef0e-4f46-b06f-c31e1a7afb48",
    "profile": {
      "code": 200,
      "message": "NO ExecPlan",
      "success": false
    }
  }
}

响应字段如下。

字段	类型	说明
code	string	成功时为 OK。
msg	string	成功时为 OK。
data.statement_id	string	请求中的语句 ID。
data.profile	object	执行计划结果。
data.profile.code	integer	执行计划状态码。
data.profile.message	string	执行计划说明。没有保存的计划时为 NO ExecPlan。
data.profile.success	boolean	是否取得可用的执行计划。
data.profile.uuid	string	执行计划标识。
data.profile.steps	object（对象数组）	执行计划的步骤列表。
data.profile.steps[].step	integer	步骤序号。
data.profile.steps[].description	string	步骤说明。
data.profile.steps[].state	string	步骤状态。
data.profile.steps[].graphData	object	步骤的执行计划图。
data.profile.steps[].graphData.nodes	object（对象数组）	执行计划图中的执行节点及其资源统计。
data.profile.steps[].graphData.edges	object（对象数组）	执行节点之间的数据流关系。
data.profile.steps[].graphData.labels	object（对象数组）	执行计划图中的标注信息。
data.profile.steps[].graphData.global	object	步骤的汇总资源统计。

执行计划的步骤和图数据仅在有可用计划时返回。

错误响应¶

错误响应使用 code、msg 和 data 包络，data 为 null。msg 为服务端返回的本地化公共错误信息，不应依赖其文本进行程序判断。

{
  "code": "ErrParamInvalid",
  "msg": "请求参数无效",
  "data": null
}

常见 HTTP 错误¶

HTTP 状态码	错误代码	常见原因	建议操作
400	ErrParamInvalid	请求体不是合法 JSON；缺少 statement_id、start 或 end；或 scope 不是 self 或 workspace。	补齐必填字段，并确认 scope 后重新提交。
403	ErrForbidden	当前身份没有读取所选范围 SQL 执行记录的权限。	使用具有所需工作区读取权限的凭据，或改为默认的 self 范围。
500	ErrServer	时间范围不是 YYYY-MM-DD HH:MM:SS 格式，或服务无法完成执行计划查询。	将 start 和 end 改为 YYYY-MM-DD HH:MM:SS 后重试；持续出现时联系支持人员。

后续操作¶

没有可用执行计划时，可使用相同的语句 ID 和时间范围查看 SQL 执行详情，核对 SQL 文本和执行状态。

最后更新于 2026 年 9 月 1 日