# 查看 SQL 执行计划

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

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

## 调用前准备

准备有当前工作区访问权限的[个人访问令牌](../../../../guides/genesis/api-keys.md#创建和管理个人访问令牌)和[当前工作区 ID](../../../../guides/ai-studio/resource-center/workspace.md#复制工作区-id)。先[查看 SQL 执行记录](list-sql-execution-records.md#选择-sql-执行记录)，选择需要分析的记录并记下其语句 ID 和执行时间。

## 请求示例

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

```bash
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 和执行计划。没有保存的执行计划时，仍会成功响应并说明没有可用计划。

```json
{
  "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 为服务端返回的本地化公共错误信息，不应依赖其文本进行程序判断。

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

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - 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 执行详情](get-sql-execution-details.md#调用前准备)，核对 SQL 文本和执行状态。