未知属性 - 如何解决此 Elasticsearch 异常

适用版本： 6.8-8.9

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

Unknown property: [fieldName] 表示 Elasticsearch 已经进入某个已知对象的解析分支，但当前字段名不在该分支允许的参数列表里，因此直接拒绝继续解析。

从当前页面保留的源码片段看，这类异常不是网络、权限或执行阶段故障，而是 请求体里的字段名写错、写多了，或者放错了层级。示例片段中它出现在 Graph 请求相关解析逻辑里，说明某个对象只接受少数固定字段，例如 sample_diversity_field、max_docs_per_value，超出名单就会抛错。

典型报错 #

ElasticsearchParseException: Unknown property: [unexpected_field]

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

• 在 Graph Explore、聚合或其他 DSL 对象中传入了未定义字段。
• 把本应属于上一层或下一层对象的参数写到了当前对象里。
• 参考了其他版本文档，使用了当前版本并不支持的参数名。
• 手工拼接 JSON 时字段名拼写错误，或把驼峰/下划线形式写混了。

3. 排查步骤 #

1. 先定位报错中方括号里的字段名，确认它具体出现在哪个对象下。
2. 对照当前 API 文档，核实该对象允许哪些字段。
3. 检查字段是否放错层级，例如把对象级参数写成了内部属性。
4. 如果请求来自 SDK、模板或网关改写，抓取最终发到 Elasticsearch 的原始 JSON 再判断。

4. 修复建议 #

方案一：删除或改正未知字段 #

{
    "controls": {
        "use_significance": true,
        "sample_diversity_field": "user_id",
        "max_docs_per_value": 100
    }
}

如果写成：

{
    "controls": {
        "sample_diversity_field": "user_id",
        "unexpected_field": true
    }
}

就可能触发该异常。

方案二：把字段移到正确层级 #

有些参数并不是不存在，而是只能出现在父对象或子对象里。遇到这种情况不要只改名字，要同时校正 JSON 结构。

方案三：核对版本差异 #

如果请求样例来自新版本文档，而集群版本较旧，先确认参数是否在当前版本中可用。

5. 小结 #

Unknown property: [fieldName] 的核心含义很明确：当前对象不认识这个字段。处理时重点不是查节点状态，而是把请求体缩小到具体对象，核对允许字段清单和参数层级。

相关错误 #

• unknown-object-property-fieldname-how-to-solve-this-elasticsearch-exception
• unknown-string-property-fieldname-how-to-solve-this-elasticsearch-exception
• unexpected-token-token-after-fieldname-how-to-solve-this-elasticsearch-exception

附：日志上下文 #

if (FIELD_NAME_FIELD.match(fieldName; parser.getDeprecationHandler())) {
        graphRequest.sampleDiversityField(parser.text());
} else if (MAX_DOCS_PER_VALUE_FIELD.match(fieldName; parser.getDeprecationHandler())) {
        graphRequest.maxDocsPerDiversityValue(parser.intValue());
} else {
        throw new ElasticsearchParseException("Unknown property: [" + fieldName + "]");
}
}
} else {
        throw new ElasticsearchParseException("Unknown object property: [" + fieldName + "]");
}