适用版本： 6.8-7.5
1. 错误异常的基本描述 #
在使用 Elasticsearch 的 significant_terms 聚合时，如果为启发式（significance heuristic）配置了不被当前启发式类型支持的字段或对象，Elasticsearch 会在解析阶段抛出如下异常：
failed to parse [heuristic] significance heuristic. unknown object [field]
该异常属于 ElasticsearchParseException，发生在 DSL 解析阶段，而非聚合执行阶段。也就是说，请求尚未真正执行，就已经因为 DSL 结构不合法被拒绝。
常见现象 #
- 请求返回
400 Bad Request，伴随上述解析异常信息。 - Kibana、客户端 SDK 或应用程序收到解析错误，聚合结果无法返回。
- 异常信息中会明确指出是哪个对象名不被识别，例如
unknown object [field]或unknown object [script]。 - 该错误通常与
significant_terms聚合中的heuristic配置直接相关。
典型报错与异常栈 #
ElasticsearchParseException: failed to parse [percentage] significance heuristic. unknown object [field]
at org.elasticsearch.search.aggregations.bucket.significant.heuristics.SignificanceHeuristicParser.parse(SignificanceHeuristicParser.java)
at org.elasticsearch.search.aggregations.bucket.significant.SignificantTermsParser.parseHeuristic(SignificantTermsParser.java)
2. 为什么会发生这个错误 #
significant_terms 聚合支持多种显著性启发式（significance heuristic），用于衡量某个词的显著性程度。常见的启发式类型包括：
percentage：空对象，不接受任何额外字段。script_heuristic：接受script字段，用于自定义显著性计算逻辑。mutual_information、chi_square、gini等：各有自己固定的参数结构。
每种启发式在源码中都有对应的解析器，解析器内部维护了一个字段白名单。当 DSL 中出现白名单以外的字段或对象时，解析器会直接抛出 ElasticsearchParseException，提示 unknown object。
常见触发原因包括：
- 将
script_heuristic的参数（如script）错误地用在了不支持脚本的启发式（如percentage）中。 - 拼写错误导致字段名不匹配，例如将
script写成scripts。 - 从文档或博客中复制了错误示例，将不同启发式的参数混用在了一起。
- 在 DSL 生成工具或模板中，没有按启发式类型做字段校验，导致生成了非法结构。
3. 如何排查和解决这个异常 #
建议按以下步骤排查：
- 定位异常字段：从报错信息中找到
unknown object [xxx]中的xxx，这就是导致问题的字段名。 - 检查启发式类型：确认
significant_terms聚合中heuristic使用的是哪种类型（如percentage、script_heuristic等）。 - 对照文档：查阅对应版本的 Elasticsearch 官方文档，确认该启发式类型支持哪些字段。
- 检查 DSL 生成逻辑：如果是通过代码或模板生成 DSL，检查是否有字段拼接错误或类型判断遗漏。
排查时需要注意的问题 #
- 不同版本的 Elasticsearch 对同一启发式的支持字段可能略有差异，务必对照当前运行版本的文档。
percentage启发式要求传入空对象{}，任何额外字段都会触发此错误。script_heuristic是唯一支持script字段的启发式类型，其他类型不应包含script。
4. 如何解决这个错误 #
方案一：删除或修正未知对象 #
对照启发式类型的文档，删除不支持的字段。例如，percentage 启发式应写为：
{
"aggs": {
"significant_tags": {
"significant_terms": {
"field": "tag",
"heuristic": {
"percentage": {}
}
}
}
}
}
方案二：切换到正确的启发式类型 #
如果业务需要脚本化逻辑，应使用 script_heuristic：
{
"aggs": {
"significant_tags": {
"significant_terms": {
"field": "tag",
"heuristic": {
"script_heuristic": {
"script": {
"source": "return 1;"
}
}
}
}
}
}
}
方案三：从最小可用示例重建 #
复杂聚合容易把不同启发式的参数混在一起。建议从一个最小可用示例开始，逐步添加字段，确保每一步都符合目标启发式的规范。
后续注意事项与推荐建议 #
- 在 DSL 生成层按启发式类型做字段白名单校验，避免生成非法结构。
- 对显著性聚合增加集成测试，覆盖不同启发式类型，避免升级后参数兼容性漂移。
- 在开发环境中使用 Elasticsearch 的
/_validate/queryAPI 提前验证 DSL 合法性。
借助 INFINI 产品提升排障效率 #
- INFINI Console 适合查看集群健康度、索引状态、聚合请求的执行情况，帮助快速判断 DSL 是否符合预期。
- INFINI Gateway 适合部署在 Elasticsearch 前面做请求观测、DSL 校验和流量治理，在请求到达 Elasticsearch 之前拦截非法 DSL。
5. 预防建议 #
- 不同 significance heuristic 不要共用一套自由参数模板，每种启发式应有独立的结构定义。
- 在代码中维护一份启发式类型与允许字段的映射表，生成 DSL 时按类型校验。
- 定期 Review 聚合相关的 DSL 模板，确保与当前 Elasticsearch 版本保持兼容。
- 对显著性聚合的使用场景做文档化记录，明确每种启发式的适用场景和参数规范。
6. 小结 #
failed to parse significance heuristic. unknown object 表示显著性启发式配置里出现了不被该类型接受的对象。修复重点是对照启发式类型文档，删除或替换非法字段。只要在 DSL 生成和校验环节做好类型区分，这类问题完全可以在开发阶段避免。
相关错误 #
- failed-to-parse-percentage-significance-heuristic-expected-an-empty-object-but-got-instead-how-to-solve-this-elasticsearch-exception
- unexpected-token-token-in-reducername-how-to-solve-this-elasticsearch-exception
- failed-to-parse-request-how-to-solve-this-elasticsearch-exception
附：日志上下文 #
currentFieldName = parser.currentName();
} else {
if (Script.SCRIPT_PARSE_FIELD.match(currentFieldName, parser.getDeprecationHandler())) {
script = Script.parse(parser);
} else {
throw new ElasticsearchParseException("failed to parse [{}] significance heuristic. unknown object [{}]",
heuristicName, currentFieldName);
}
}
