Debug PLAN should be specified at most once - 如何解决此 Elasticsearch 异常 | Easysearch | 分布式搜索引擎

适用版本： 6.8-8.9

1. 错误异常的基本描述 #

Debug PLAN should be specified at most once 是 Elasticsearch SQL 模块在解析 DEBUG 语句时抛出的 ParsingException。当 SQL 文本中多次出现 PLAN 子句时，解析器会在语法分析阶段直接终止并报错。该异常属于语法解析错误，而非执行时错误，因此请求不会进入查询规划或执行阶段。

常见现象 #

使用 Elasticsearch SQL 的 DEBUG 语句时，请求在解析阶段立即失败，返回 ParsingException。
常见于模板引擎拼装 SQL、调试工具自动附加 PLAN 子句、或代码逻辑中多次拼接同一参数，导致最终 SQL 文本中出现重复的 PLAN 关键字。
报错信息中明确包含 PLAN 字样，例如：ParsingException: Debug PLAN should be specified at most once。
该错误通常伴随 DEBUG 语句的 EXPLAIN / PLAN / FORMAT 组合使用场景出现。

典型报错与异常栈 #

ParsingException: Debug PLAN should be specified at most once
    at org.elasticsearch.xpack.sql.parser.SqlParser$StaticPair.parse(SqlParser.java:...)
    at org.elasticsearch.xpack.sql.plugin.RestSqlQueryAction.lambda$prepareRequest$...

在客户端（如 Kibana Console、curl、Java SDK）中，请求会直接返回 400 Bad Request，响应体中包含上述异常信息。

2. 为什么会发生这个错误 #

Elasticsearch SQL 的 DEBUG 语句用于输出查询的执行计划调试信息，其语法结构如下：

DEBUG [PLAN planOption] [FORMAT formatOption] <statement>

其中 PLAN 和 FORMAT 均为可选且最多只能出现一次的修饰子句。解析器在遍历 SQL AST 时，会对 ctx.PLAN() 的出现次数做显式校验：

if (ctx.PLAN().size() > 1) {
    throw new ParsingException(source, "Debug PLAN should be specified at most once");
}

当 ctx.PLAN().size() > 1 时，即判定为非法语法并抛出异常。

常见触发原因包括：

模板拼接重复：使用模板引擎（如 FreeMarker、Velocity）或字符串格式化时，循环或条件分支导致 PLAN 子句被追加多次。
调试工具累积：调试工具在用户手动输入的基础上自动附加 PLAN 子句，而用户原始 SQL 中已包含该子句。
代码逻辑缺陷：SQL 构建器未对 PLAN 选项做去重处理，每次调用 appendPlan() 都直接拼接，最终生成重复文本。
客户端缓存/重试：某些客户端在重试时复用了已拼接完成的 SQL 字符串，导致 PLAN 被再次附加。
多层包装：应用层、中间件层、网关层各自独立拼接 SQL 片段，缺乏对最终语句唯一性的校验。

3. 如何排查和解决这个异常 #

建议按"先定位重复来源、再修复生成逻辑"的顺序处理：

打印最终 SQL 文本：在请求发送前，将完整的 SQL 字符串输出到日志或控制台，确认 PLAN 是否重复出现。
搜索 PLAN 关键字：在 SQL 文本中搜索 PLAN（不区分大小写），检查出现次数是否大于 1。
检查拼接来源：定位 SQL 生成代码，确认哪些模块或方法参与了 PLAN 子句的拼接，是否存在多层调用。
验证模板逻辑：如果使用了模板引擎，检查模板文件及渲染逻辑，确认是否存在循环渲染或条件分支重复追加的问题。
删除重复项后重测：手动去除多余的 PLAN 子句，确认请求能够正常执行，缩小问题范围。
为 SQL 生成器增加唯一性约束：在构建 DEBUG 语句时，对 PLAN 和 FORMAT 等修饰子句做存在性检查，避免重复追加。

排查时需要注意的问题 #

这不是执行计划内容错误，而是语法选项重复，不需要检查索引 mapping 或数据内容。
如果 FORMAT 也在同一条语句中出现多次，解析器同样会抛出类似异常（Debug FORMAT should be specified at most once），建议一并检查。
DEBUG 语句在某些客户端中可能被自动改写，排查时应使用原始请求文本，而非客户端展示的格式化内容。
如果问题出现在生产环境，优先在测试环境复现，避免直接修改生产代码导致二次问题。

4. 如何解决这个错误 #

常用修复思路 #

集中管理 PLAN 生成逻辑：将 PLAN 子句的拼接逻辑收敛到单一方法或配置项中，避免在多个地方分散处理。
结构化生成 SQL：使用对象（如 DebugStatement 类）来表示 DEBUG 语句，在序列化时检查各修饰子句的唯一性，而非直接拼接字符串。
增加去重保护：在拼接前检查目标子句是否已存在，例如：

if (!sql.contains("PLAN") && planOption != null) {
    sql += " PLAN " + planOption;
}

保留最终 SQL 输出：在测试环境或灰度环境中，始终记录最终发送到 Elasticsearch 的 SQL 文本，便于快速复现和定位问题。
使用参数化接口：如果客户端支持，优先使用参数化方式传递 PLAN 和 FORMAT 选项，而非手动拼接到 SQL 字符串中。

后续注意事项与推荐建议 #

DEBUG 语句适合用 AST 或结构化配置生成，避免字符串拼接类错误。
工具侧按钮与 SQL 文本生成逻辑应保持单向映射，即用户操作后只触发一次 SQL 构建，避免多次叠加。
建议在 SQL 构建器中增加单元测试，覆盖 PLAN、FORMAT 的单次和重复拼接场景，提前发现类似问题。
对于需要频繁调试 SQL 的场景，可以将常用的 DEBUG 语句模板固化到配置文件中，减少动态拼接带来的风险。

借助 INFINI 产品提升排障效率 #

INFINI Console 可帮助观察失败的 SQL 请求，查看请求原文、响应状态和异常信息，快速定位是否为语法问题。
INFINI Gateway 可回放问题请求的原始文本，在请求到达 Elasticsearch 之前捕获完整的 SQL 内容，便于确认是否存在重复拼接。
对于需要长期治理 SQL 调试场景的团队，建议将 SQL 请求日志、异常类型和来源信息统一接入监控面板，缩短从"发现问题"到"定位根因"的时间。

5. 小结 #

Debug PLAN should be specified at most once 的解决方式很直接：让 PLAN 只出现一次。关键在于定位重复拼接发生在哪一层——是模板引擎、调试工具、代码逻辑，还是多层包装共同导致。只要把 SQL 生成逻辑收敛到单一入口，并对修饰子句做唯一性校验，这类问题就可以通过代码层面彻底避免。

附：日志上下文 #

下面保留当前页面中的源码片段，便于结合异常调用栈定位问题：

if (ctx.PLAN().size() > 1) {
    throw new ParsingException(source, "Debug PLAN should be specified at most once");
}

标签

Debug PLAN should be specified at most once - 如何解决此 Elasticsearch 异常