43 · 常见错误与排查阶段第五阶段 / 进阶与实战目标把最常踩的坑集中列出遇到报错能快速定位。1. text 字段不能精确匹配 / 排序 / 聚合现象对text字段用term查不到或聚合报 fielddata 错误。原因text会被分词term是精确匹配整个未分词值text默认不建 doc_values不能排序/聚合。解决精确匹配、排序、聚合用keyword或多字段field.keyword。全文搜索用match对text。# 错term 匹配 text { term: { material: ThinkPad X1 } } # 查不到 # 对用 keyword 子字段 { term: { material.keyword: ThinkPad X1 } }2. 聚合报 “fielddata is disabled”原因对text字段做聚合/排序ES 要求开 fielddata很吃内存默认关闭。解决改用该字段的.keyword子字段不要开 fielddata。3. mapping 冲突 / 字段类型无法修改现象mapper_parsing_exception或加字段时类型冲突。原因ES 的 mapping 一旦确定已有字段类型不可改。解决新建索引用正确类型 →reindex搬数据 → 别名切换第 33 篇。4. 深分页报错 “Result window is too large”原因from size 10000index.max_result_window默认上限。解决用search_after PIT代替深from/size第 40 篇不要盲目调大上限。5. 查不到刚写入的数据原因ES 是近实时NRT默认refresh_interval1s写完到可搜有延迟。解决测试可写完带refreshtrue生产别滥用影响性能。正常业务接受 1s 延迟即可。6. bulk 返回 200 但部分数据没进去原因bulk整体 HTTP 200 不代表每条成功。解决检查response.errors()遍历items()打印失败项的error().reason()第 31 篇。7. 日期字段解析失败现象failed to parse date field。原因写入的日期格式和 mapping 里format不一致。解决统一格式如yyyy-MM-dd写 ES 前用to_char(col, YYYY-MM-DD)格式化本项目calcFields_2有此写法。8. terms 聚合 doc_count 不准原因多分片下terms计数是近似的。解决加大shard_size或高基数场景用composite聚合分页第 21 篇。9. scroll 上下文泄漏现象段一直不释放、资源占用高。原因scroll 用完没clearScroll。解决用完必须清理本项目SelectEsDataHandler在末尾clearScroll新场景优先 PIT search_after。10. 排查工具箱工具用途GET index/_mapping看字段类型排 text/keyword 问题GET index/_count确认数据量 / 删除前评估影响POST index/_search {explain:true}看某条为什么这么打分GET _cat/indices?v看索引健康、文档数、大小GET _tasks跟踪update_by_query/reindex异步任务Kibana Dev Tools先调通 DSL再翻译成 Java全系列小结到这里你应该能用「SQL 母语」理解 ESmapping ≈ DDL、term/range/bool≈WHERE、terms/date_histogram≈GROUP BY、bulk≈ 批量 INSERT、别名 ≈ 视图、search_after≈ 键集分页。配合本项目AbstractEsHepler/SelectEsDataHandler即可上手改真实链路。下一篇进阶专题按需选读
