查询 SQL 执行计划

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

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

调用前准备

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

请求体

将示例中的 $AI_STUDIO_API_KEY、$WORKSPACE_ID、$STATEMENT_ID 替换为实际值。

curl -X POST "https://api.moi.matrixorigin.cn/v5/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-26T09:44:00Z",
    "end": "2026-08-26T09:46:00Z"
  }'

字段

类型

是否必填

说明

scope

string 或 null

否

查看当前身份或当前工作区的记录。取值：空字符串、self、workspace。

statement_id

string

是

所选 SQL 执行记录的语句 ID。不能为空。

start

string

是

查询开始时间，使用带时区的 RFC 3339 格式。

end

string

是

查询结束时间，使用带时区的 RFC 3339 格式。

起止时间使用带时区的 RFC 3339 字符串，例如 2026-08-21T07:00:00Z。详情和计划查询保留输入的本地时间及微秒精度，并将范围前后各扩展 1 秒。列表和概览则转为 UTC 整秒。

查看范围

scope 值

可查看的记录

权限条件。

self

当前身份的记录。

默认范围。

workspace

工作区范围的记录。

需要工作区审计读取权限。

指定查询时间范围

开始和结束时间必须同时填写，并覆盖所选记录的执行时间。例如，列表显示 2026-08-26T09:45:35Z 时，可使用 2026-08-26T09:44:00Z 至 2026-08-26T09:46:00Z 的时间范围。

使用所选执行记录

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

成功响应

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

字段

类型

说明

data.statement_id

string

请求中的语句 ID。

data.profile

object

执行计划结果。

data.profile.steps

object（对象数组）

执行计划的步骤列表。

data.profile.steps[].graphData

object

步骤的执行计划图。

data.profile.steps[].graphData.nodes

object（对象数组）

执行计划图中的执行节点及其资源统计。

data.profile.steps[].graphData.nodes[].id

string

标识。

data.profile.steps[].graphData.nodes[].name

string

名称。

data.profile.steps[].graphData.nodes[].title

string

标题。

data.profile.steps[].graphData.nodes[].labels

object（对象数组）

标签映射。

data.profile.steps[].graphData.nodes[].labels[].name

string

名称。

data.profile.steps[].graphData.nodes[].labels[].value

string

值。

data.profile.steps[].graphData.nodes[].statistics

object

运行指标。

data.profile.steps[].graphData.nodes[].statistics.memory

object（对象数组） 或 null

内存指标。

data.profile.steps[].graphData.nodes[].statistics.memory[].name

string

名称。

data.profile.steps[].graphData.nodes[].statistics.memory[].value

integer

值。

data.profile.steps[].graphData.nodes[].statistics.memory[].unit

string

单位。

data.profile.steps[].graphData.nodes[].statistics.throughput

object（对象数组） 或 null

吞吐指标。

data.profile.steps[].graphData.nodes[].statistics.throughput[].name

string

名称。

data.profile.steps[].graphData.nodes[].statistics.throughput[].value

integer

值。

data.profile.steps[].graphData.nodes[].statistics.throughput[].unit

string

单位。

data.profile.steps[].graphData.nodes[].statistics.io

object（对象数组） 或 null

IO指标。

data.profile.steps[].graphData.nodes[].statistics.io[].name

string

名称。

data.profile.steps[].graphData.nodes[].statistics.io[].value

integer

值。

data.profile.steps[].graphData.nodes[].statistics.io[].unit

string

单位。

data.profile.steps[].graphData.nodes[].statistics.network

object（对象数组） 或 null

网络指标。

data.profile.steps[].graphData.nodes[].statistics.network[].name

string

名称。

data.profile.steps[].graphData.nodes[].statistics.network[].value

integer

值。

data.profile.steps[].graphData.nodes[].statistics.network[].unit

string

单位。

data.profile.steps[].graphData.nodes[].cost

object

估计成本。

data.profile.steps[].graphData.nodes[].cost.start

number

开始时间。

data.profile.steps[].graphData.nodes[].cost.total

number

符合当前查询条件的记录数。

data.profile.steps[].graphData.nodes[].cost.card

number

估计基数。

data.profile.steps[].graphData.nodes[].cost.ndv

number

不同值数量。

data.profile.steps[].graphData.nodes[].cost.rowsize

number

估计行大小。

data.profile.steps[].graphData.nodes[].totalStats

object

总运行指标。

data.profile.steps[].graphData.nodes[].totalStats.name

string

名称。

data.profile.steps[].graphData.nodes[].totalStats.value

integer

值。

data.profile.steps[].graphData.nodes[].totalStats.unit

string

单位。

data.profile.steps[].graphData.edges

object（对象数组）

执行节点之间的数据流关系。

data.profile.steps[].graphData.edges[].id

string

标识。

data.profile.steps[].graphData.edges[].src

string

源节点。

data.profile.steps[].graphData.edges[].dst

string

目标节点。

data.profile.steps[].graphData.edges[].output

integer

输出。

data.profile.steps[].graphData.edges[].unit

string

单位。

data.profile.steps[].graphData.labels

object（对象数组）

执行计划图中的标注信息。

data.profile.steps[].graphData.labels[].name

string

名称。

data.profile.steps[].graphData.labels[].value

string

值。

data.profile.steps[].graphData.global

object

步骤的汇总资源统计。

data.profile.steps[].graphData.global.statistics

object

运行指标。

data.profile.steps[].graphData.global.statistics.memory

object（对象数组） 或 null

内存指标。

data.profile.steps[].graphData.global.statistics.memory[].name

string

名称。

data.profile.steps[].graphData.global.statistics.memory[].value

integer

值。

data.profile.steps[].graphData.global.statistics.memory[].unit

string

单位。

data.profile.steps[].graphData.global.statistics.throughput

object（对象数组） 或 null

吞吐指标。

data.profile.steps[].graphData.global.statistics.throughput[].name

string

名称。

data.profile.steps[].graphData.global.statistics.throughput[].value

integer

值。

data.profile.steps[].graphData.global.statistics.throughput[].unit

string

单位。

data.profile.steps[].graphData.global.statistics.io

object（对象数组） 或 null

IO指标。

data.profile.steps[].graphData.global.statistics.io[].name

string

名称。

data.profile.steps[].graphData.global.statistics.io[].value

integer

值。

data.profile.steps[].graphData.global.statistics.io[].unit

string

单位。

data.profile.steps[].graphData.global.statistics.network

object（对象数组） 或 null

网络指标。

data.profile.steps[].graphData.global.statistics.network[].name

string

名称。

data.profile.steps[].graphData.global.statistics.network[].value

integer

值。

data.profile.steps[].graphData.global.statistics.network[].unit

string

单位。

data.profile.steps[].graphData.global.totalStats

object

总运行指标。

data.profile.steps[].graphData.global.totalStats.name

string

名称。

data.profile.steps[].graphData.global.totalStats.value

integer

值。

data.profile.steps[].graphData.global.totalStats.unit

string

单位。

data.profile.steps[].step

integer

步骤序号。

data.profile.steps[].description

string

步骤说明。

data.profile.steps[].state

string

步骤状态。

data.profile.code

integer

执行计划状态码。不小于 0。不大于 65535。

data.profile.message

string

执行计划说明。没有保存的计划时为 NO ExecPlan。

data.profile.success

boolean

是否取得可用的执行计划。

data.profile.uuid

string

执行计划标识。

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

错误响应

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

字段

类型

说明

code

string

错误代码。

msg

string

错误信息。
最后更新于