MySQL EXPLAIN FORMAT JSON 怎样保存执行计划

如果你想把 MySQL 的 JSON 执行计划留给脚本或排障记录，MySQL 8.4 可以直接使用 EXPLAIN FORMAT=JSON INTO @plan，把计划保存到当前会话的用户变量；随后再用 JSON_EXTRACT 读取关键节点。它保存的是优化器生成的计划描述，不是已经发生过的真实耗时报告。

本文按 MySQL 8.4 参考手册说明语法，官方地址：https://dev.mysql.com/doc/refman/8.4/en/。示例只讨论 JSON 计划的保存与读取，代码中的表名和数据是假设的业务结构。

• 保存：EXPLAIN FORMAT=JSON INTO @plan。
• 读取：用 JSON 路径提取 table_name、access_type、key 等节点。
• 留档：把变量内容转换后写入 JSON 列，避免只依赖一次会话输出。

先明确要保存的对象

EXPLAIN FORMAT=JSON 返回的是 JSON 格式的优化器计划。与表格格式相比，它会用嵌套对象表达查询块、表访问、成本信息和条件等结构，更适合被脚本读取。INTO 保存到的是当前连接里的用户变量；连接结束后变量不会自动成为历史记录。

下面的查询假设 orders 有客户编号、订单编号和创建时间。EXPLAIN 只描述优化器会怎样处理语句，不会因为这次查看而把查询结果写入业务表。

用 INTO 保存一份 JSON 执行计划

在同一个 MySQL 会话中，先清空变量再保存计划，便于区分本次结果和旧值。MySQL 8.4 参考手册列出了 EXPLAIN FORMAT=JSON INTO @变量 的写法；SELECT、INSERT、UPDATE、DELETE、REPLACE 和 TABLE 等可解释语句都可以按相同思路处理。

-- 清掉旧值，避免后续排查误把上一条语句的计划当成当前结果。
SET @plan = NULL;

-- 把优化器生成的 JSON 计划保存到当前会话的用户变量。
EXPLAIN FORMAT=JSON INTO @plan
SELECT order_id, customer_id
FROM orders
WHERE customer_id = 1001
  AND created_at >= '2026-01-01';

-- 需要查看完整 JSON 时直接读取变量；长结果可由客户端另行导出。
SELECT @plan AS execution_plan\G

如果 @plan 为空，先检查语句是否被当前版本接受、会话是否仍是同一个连接，以及 EXPLAIN 本身是否返回错误。不要在另一个连接里读取它：用户变量的作用域是当前会话。

从变量中提取关键节点

保存成变量后，不必每次人工翻完整 JSON。对上面的单表计划，可以用 JSON 路径提取访问对象、访问类型、选择的索引和预计扫描行数。这里的路径是示例计划结构；遇到连接、派生表或更深层的 nested_loop 时，应先按实际层级调整路径。

-- 单表计划的常见路径；JSON_UNQUOTE 让字符串结果更适合日志或报表。
SELECT
    JSON_UNQUOTE(JSON_EXTRACT(@plan, '$.query_block.table.table_name')) AS table_name,
    JSON_UNQUOTE(JSON_EXTRACT(@plan, '$.query_block.table.access_type')) AS access_type,
    JSON_UNQUOTE(JSON_EXTRACT(@plan, '$.query_block.table.key')) AS chosen_key,
    JSON_UNQUOTE(JSON_EXTRACT(@plan, '$.query_block.table.rows_examined_per_scan')) AS rows_examined;

-- 只取优化器成本节点，缺失路径时会得到 NULL，不应当伪造默认值。
SELECT JSON_EXTRACT(@plan, '$.query_block.cost_info') AS cost_info;

读取结果时把“路径不存在”和“值本身为 null”分开处理。单表查询可以从 query_block.table 开始；多表查询常见的是 nested_loop 数组，不能机械复用单表路径。JSON_EXTRACT 返回 JSON 值，展示为普通文本时再使用 JSON_UNQUOTE。

需要留档时写入 JSON 列

用户变量适合当前排障会话，想跨会话比较计划就要落到自己的记录表。下面建立一个最小留档表，把完整计划保存到 JSON 列；业务上还可以增加 SQL 指纹、分支名或采集人等字段。

-- 用 JSON 列保存完整计划，采集时间由数据库默认填入。
CREATE TABLE IF NOT EXISTS query_plan_archive (
    id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
    query_name VARCHAR(64) NOT NULL,
    captured_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    plan_json JSON NOT NULL
);

-- 将当前会话变量转换为 JSON 文档后留档；先确认 @plan 不是 NULL。
INSERT INTO query_plan_archive (query_name, plan_json)
VALUES ('orders-by-customer', CAST(@plan AS JSON));

-- 后续按 JSON 路径读取留档计划中的访问类型。
SELECT
    query_name,
    JSON_UNQUOTE(JSON_EXTRACT(plan_json, '$.query_block.table.access_type')) AS access_type
FROM query_plan_archive
WHERE query_name = 'orders-by-customer'
ORDER BY captured_at DESC;

留档表记录的是计划快照，不等于已经验证了 SQL 的真实耗时。若要对比优化前后，应同时保存采集时间、SQL 版本或参数边界，并在读者自己的测试环境中分别执行测量；本文不虚构运行结果。

常见误区与轻量验收

第一，不能把用户变量当成持久化存储；需要跨连接读取就写入 JSON 列或由客户端保存。第二，不能把单表路径套到所有计划；连接和子查询会改变树形结构。第三，rows_examined_per_scan 等字段是计划里的估算信息，不能替代真实执行统计。第四，EXPLAIN FORMAT=JSON 的输出对象要按版本文档理解，升级版本后应重新核对路径。

验收可以保持简单：当前会话中的 @plan 非空；提取出的 table_name 与目标表一致；key 为空时如实记录；写入 JSON 列后能按相同路径读取。做到这四点，就完成了“保存并读取 JSON 执行计划”的范围。

能不能在另一个连接中读取 @plan？

不能。用户变量属于当前会话，换连接后需要重新生成，或者读取已经写入留档表的 JSON。

为什么 JSON_EXTRACT 读不到 table_name？

通常是计划层级不同。单表示例从 query_block.table 读取，连接查询可能需要先进入 nested_loop 数组；应以当前计划结构为准修改路径。

保存计划就等于保存性能证据吗？

不等于。计划描述优化器的选择和估算，实际耗时、锁等待与数据分布仍要在自己的环境中测量。