映射错误

• 始终明确定义映射——动态映射容易误判（例如首次遇到 "123" 会将字段设为 integer 类型，后续出现 "abc" 则写入失败）
• text 类型适用于全文检索，keyword 类型适用于精确匹配与聚合操作——对 ID 字段使用 text 会导致过滤器失效
• 索引创建后无法更改字段类型——必须通过重新索引（reindex）到一个具备正确映射的新索引中来修正
• 设置 dynamic: "strict" 可拒绝未定义的字段——有助于及时发现字段名拼写错误

text 与 keyword 的区别

• text 类型会被分析（分词、转小写等）——例如文档中为 "Quick Brown"，搜索 "quick" 可以匹配成功
• keyword 类型按原始字节精确匹配——"Quick Brown" 仅能与完全相同的 "Quick Brown" 匹配
• 若需兼顾两者功能，可使用多字段（multi-field）： "title": { "type": "text", "fields": { "raw": { "type": "keyword" }}}
• 在 title.raw 上执行排序或聚合，在 title 上执行全文检索

查询上下文（Query） vs 过滤上下文（Filter）

• 查询上下文会计算相关性得分（relevance score）——开销较高，适用于搜索结果排序
• 过滤上下文仅返回是/否结果——可被缓存，适用于精确条件筛选（如 status、日期范围等）
• 组合使用：bool.must 用于影响评分的条件，bool.filter 用于不参与评分的过滤条件
• 针对日期或数字的 range 查询几乎总是应置于 filter 上下文中，而非 query 中

分析器（Analyzers）

• standard 分析器会对文本进行小写转换并移除标点符号——适用于大多数普通文本场景
• keyword 分析器保留字符串原始形式——适用于代码、SKU、邮箱等需精确匹配的字段
• 语言专用分析器（如 english）支持词干提取（stemming）——例如 "running" 可匹配 "run"
• 在正式索引前，务必使用 _analyze API 测试分析器行为——生产环境中的意外行为将带来严重后果

nested 与 object 类型的区别

• object 类型会将数组结构展平——例如 {"tags": [{"key":"a","val":1}, {"key":"b","val":2}]} 将变为 tags.key: [a,b], tags.val: [1,2]
• 展平后丢失对象内字段间的关联关系——查询 key=a AND val=2 会错误地匹配上述数据
• 使用 nested 类型可保留嵌套对象边界——但查询时必须配合 nested 查询封装器
• nested 查询性能开销较大——高基数（high-cardinality）数组应避免使用

分页陷阱

• from + size 默认最多返回 10,000 条结果——深度分页将失败
• 深度分页应使用 search_after——需指定稳定排序字段（通常为 _id）
• 批量导出推荐使用 Scroll API——可保持时间点快照视图，但会持续占用集群资源
• 切勿将 Scroll 用于用户端分页——search_after 才是正确选择

批量操作（Bulk Operations）

• 切勿逐条索引文档——应使用 _bulk API，建议单次请求大小控制在 5–15 MB
• Bulk 格式为换行符分隔的 JSON：每组包含一行动作指令（action line），后跟一行文档内容（document line）
• 务必检查 bulk 响应中的部分失败（partial failures）——整体请求可能成功，但个别文档仍可能报错
• 批量导入期间设置 refresh=false——待整批完成后再手动触发 refresh

性能优化

• 若无需返回完整文档，可设置 _source: false 并配合 stored_fields——减少 I/O 开销
• 对可缓存的条件优先使用 filter——Elasticsearch 会自动缓存 filter 结果
• 避免使用前导通配符（如 *term）——将强制全量扫描；如需后缀匹配，可考虑添加 reverse 字段
• 启用 profile: true 可查看查询执行各阶段耗时——快速定位慢子句

分片（Sharding）

• 单个分片大小建议维持在 10–50 GB 区间——过小导致元数据与管理开销上升，过大则恢复缓慢
• 分片数量在索引创建时即固定——无法在线调整，必须通过 reindex 实现重分片
• 副本（replica）用于提升读取吞吐量与可用性——副本数应根据实际查询负载合理设定
• 小型索引建议从 1 个主分片起步——过度分片将显著损害性能

索引管理

• 使用索引模板（index templates）——确保新创建的索引具备一致的映射与配置
• 使用别名（aliases）实现零停机重新索引——reindex 完成后将别名指向新索引即可切换
• 时间序列类索引推荐启用 ILM（Index Lifecycle Management）——支持自动 rollover 和历史索引清理
• 关闭长期未使用的索引以释放内存——已关闭索引不占用 JVM heap

聚合（Aggregations）

• terms 聚合必须作用于 keyword 类型字段——在 text 字段上执行将失败或返回无意义结果
• terms 聚合默认只返回前 10 个桶（size: 10）——如需全部结果，请增大 size 或改用 composite 聚合
• cardinality 聚合基于 HyperLogLog 算法，结果为近似值——精确计数需遍历全部文档
• 对 nested 类型字段做聚合时，必须使用 nested 封装器——其使用模式与 nested 查询一致

常见错误

• "cluster_block_exception"——磁盘使用率超过 85%，集群进入只读状态；需清理磁盘空间，并通过 _cluster/settings 重置相关阈值
• "version conflict"——并发更新冲突；可通过设置 retry_on_conflict 参数自动重试，或采用乐观锁机制处理
• "circuit_breaker_exception"——查询内存超限；应缩小聚合范围或限制返回结果数量
• 因动态字段过多引发映射爆炸（mapping explosion）——建议设置 index.mapping.total_fields.limit 并启用 strict 映射策略