适用版本： 6.8-8.9
1. 错误异常的基本描述 #
在 Elasticsearch SQL 的 EXPLAIN 语句里，FORMAT 只能出现一次。解析器会统计 ctx.FORMAT().size()，只要大于 1，就直接抛出这条 ParsingException。
常见现象 #
- 执行 SQL
EXPLAIN语句时报错，而不是搜索执行阶段失败。 - 报错通常是即时返回
400。 - 常见于手工拼 SQL、模板重复追加
FORMAT，或可视化工具二次加工查询语句。
典型报错与异常栈 #
ParsingException: Explain FORMAT should be specified at most once
2. 为什么会发生这个错误 #
EXPLAIN 允许指定输出格式，但语法上只允许一个 FORMAT 子句。如果同一条语句里写了两个 FORMAT，解析器无法判断应该采用哪一个，因此会在语法分析阶段拒绝执行。
3. 如何排查和解决这个异常和解决这个异常 #
- 打印最终发送到 Elasticsearch 的 SQL 文本。
- 搜索其中是否重复出现
FORMAT。 - 如果 SQL 来自模板拼接，检查是否存在公共后缀和局部后缀都追加
FORMAT的情况。 - 保留一个合法
FORMAT，删除其余重复项。 - 重新执行
EXPLAIN验证。
排查时需要注意的问题 #
- 这属于 SQL 语法层问题，不是 mapping、索引或执行计划本身的问题。
- 有些中间层会自动追加
FORMAT txt/json，要确认最终文本而不是只看原始模板。
4. 如何解决这个错误 #
常用修复思路 #
- 删除重复的
FORMAT子句。 - 统一 SQL 生成器，确保
EXPLAIN后缀只由一个模块负责。 - 对提交前的 SQL 做简单语法检查。
后续注意事项与推荐建议 #
EXPLAIN、DEBUG等语句建议走独立模板，不要和普通 SQL 查询共用拼接逻辑。- 在调试工具里显示最终 SQL，方便定位重复参数。
借助 INFINI 产品提升排障效率 #
- INFINI Console 可协助查看失败 SQL 请求。
- INFINI Gateway 可记录最终下发的 SQL 语句。
5. 小结 #
Explain FORMAT should be specified at most once 本质是重复声明同一个语法选项。定位重点是最终 SQL 文本，而不是执行计划内容。
相关错误 #
- explain-type-should-be-specified-at-most-once-how-to-solve-this-elasticsearch-exception
- explain-verify-should-be-specified-at-most-once-how-to-solve-this-elasticsearch-exception
- debug-format-should-be-specified-at-most-once-how-to-solve-this-elasticsearch-exception
附：日志上下文 #
if (ctx.FORMAT().size() > 1) {
throw new ParsingException(source(ctx), "Explain FORMAT should be specified at most once");
}
