Elasticsearch 在执行聚合、排序或脚本访问字段值时，如果字段类型是 text 且没有开启 doc_values，就需要把倒排索引里的词项构建成 fielddata 结构并放进堆内存。这个过程非常消耗内存，尤其在高基数字段上很容易把老年代迅速填满。为了防止节点因为单个查询而崩溃，Elasticsearch 设计了一系列断路器（circuit breaker），其中 fielddata 断路器专门负责在加载字段数据之前做内存预估，超过阈值就直接抛异常拒绝请求，从而把故障控制在查询层而不是 JVM 层。
fielddata 断路器的核心参数与内存估算逻辑
fielddata 断路器由 indices.breaker.fielddata.limit 控制，默认值是 JVM 堆的 40%。还有一个配套的 indices.breaker.fielddata.overhead，默认是 1.03，用于在估算内存时乘以一个系数来应对碎片和对象头开销。实际允许加载的 fielddata 内存等于堆大小乘以 limit 再乘以 overhead。例如堆为 8GB 时，理论上限大约是 8 * 0.4 * 1.03 ≈ 3.3GB。当某个分片准备加载 fielddata 时，断路器会把预估大小加上已用大小，如果超过这个上限就会触发 CircuitBreakingException。
需要注意，fielddata 断路器估算的是“将要加载”的内存，而不是已加载的。也就是说，哪怕当前缓存里只有 1GB 数据，只要本次查询预估要再加载 3GB，且总和超过上限，请求也会被拒绝。这和 indices.fielddata.cache.size 不同，后者只是控制淘汰策略下的缓存上限，并不具备前置拦截能力。很多用户误以为调大 cache.size 就能解决熔断问题，实际上断路器照样会拦。
在集群层面还可以通过 indices.breaker.total.limit 限制所有断路器合计占堆的比例，默认 70%。fielddata、request、in flight requests 等断路器都受它约束。如果只调高 fielddata 的 limit 而不看 total，可能因为其他部分内存占用高而依然被 total 拦住。下面是一段典型的elasticsearch.yml配置片段：
# elasticsearch.yml 断路器相关配置示例 indices.breaker.fielddata.limit: 40% indices.breaker.fielddata.overhead: 1.03 indices.breaker.request.limit: 60% indices.breaker.total.limit: 70% indices.fielddata.cache.size: 30%
不同业务场景下的设置策略与对比
对于日志类集群，字段基数极高且查询分散，fielddata 的使用应当尽量禁止，改为使用 keyword 类型加 doc_values。如果确实需要对 text 做聚合，可以设置较低的 limit，比如 20%，并配合较小的 cache.size，让热点数据常驻、冷数据快速淘汰。这样即使发生熔断，影响范围也局限于少数宽聚合，不会波及其他查询。相反，在商品搜索集群中，如果类目聚合非常频繁且类目基数低，可以适当把 limit 提到 50%，减少误杀带来的空结果。
另一种常见做法是使用 request 断路器来兜底。request 断路器默认占堆 60%，负责计算聚合桶、排序数组等临时结构。当 fielddata 和 request 同时吃内存时，total 断路器会综合判断。我们通过一张简表对比两种极端配置的差异：
| 策略 | fielddata.limit | cache.size | 适用场景 | 风险 |
|---|---|---|---|---|
| 保守型 | 20% | 15% | 高基数日志 | 宽聚合易熔断 |
| 宽松型 | 50% | 35% | 低基数搜索 | 堆压力较大 |
从实践看，宽松型配置在堆小于 4GB 的节点上风险很高，因为 JVM 本身还需要空间给段缓存和索引缓冲。建议小堆节点一律采用保守型，并在查询端拆分聚合任务，避免单次拉取过多字段数据。大堆节点（16GB 以上）可以适度放宽，但仍要留足给 total 断路器和其他模块的余地。
监控、调优与常见误区
运维上应通过 _nodes/stats/breaker 接口观察各断路器的 tripped 次数和 estimated 大小。如果 fielddata 的 tripped 持续增长，说明要么查询模式不合理，要么 limit 确实偏低。此时不要盲目调大 limit，而应先检查是否有 text 字段本该用 keyword 却走了 fielddata。使用如下命令可快速查看熔断统计：
# 查看节点断路器状态 curl -X GET 'http://127.0.0.1:9200/_nodes/stats/breaker?pretty'
一个典型误区是认为断路器能“自动释放”内存。实际上断路器只负责拦截，已加载的 fielddata 依然要靠 cache.size 的 LRU 淘汰或节点重启来回收。如果 cache.size 设得过大，旧数据长期不淘汰，新请求即便估算很小也可能因为总使用量接近 limit 而被拒。因此 cache.size 通常应明显小于 breaker limit，例如 limit 40% 时 cache.size 设 25% 左右比较安全。
另一个坑是在堆外内存紧张时忽略 overhead 的作用。overhead 默认 1.03 看似很小，但在 TB 级索引上，3% 的误差可能就是上百 MB，足以让临界请求被误杀。对于对象头开销明显的场景，可以把 overhead 微调到 1.1，让预估更保守。最后要强调，fielddata 断路器不是性能优化工具，而是保护绳；根本解决之道仍是合理建模，把需要聚合的字段设为 keyword 并开启 doc_values，从源头避开 fielddata 加载。
Elasticsearchfielddatacircuit_breaker修改时间：2026-08-18 20:14:31