按访问模式设计 Elasticsearch…

在新建索引、审查现有 mapping 或修复错误字段类型时，依据字段的搜索/过滤/聚合/排序用途选择正确类型并规划 reindex。

适用场景

解决思路

1. 先逐字段收集访问模式：对每个字段确认它是用于全文搜索（match/phrase/相关性打分）、精确过滤（term/terms/prefix）、聚合（terms/cardinality/histogram/stats）、排序，还是仅返回在 _source 中从不查询；为每个字段归类到一个主要访问模式（search、exact、numeric metric、date、boolean、structured object 或 retrieve-only）。缺少访问模式信息时不要猜测，直接询问用户。
2. 调用 GET / 确认连通性；审查现有索引时调用 GET /{index}/_mapping 以当前映射为基础展开讨论。
3. 按访问模式选择最小类型集合：仅全文搜索用 text（不加 keyword 子字段）；仅过滤/聚合/排序用 keyword（不用 text）；既要全文搜索又要排序或聚合时用 text 加 fields.keyword 多字段；小数价格或指标用 double、float 或 scaled_float（不用 text 或整数）；时间戳用 date；真假标志用 boolean；键数量很多的自由键值映射用 flattened（不用动态 object）。
4. 多字段规则：当字段必须既可搜索又可排序/聚合（如商品 name）时，映射为 text 并带 keyword 子字段——在 name 上搜索，在 name.keyword 上排序和聚合；只映射 text 或只映射 keyword 对该组合模式都是错误的。
5. 显式映射规则：新索引始终用 PUT /{index} 显式定义 mappings，不要依赖动态映射，因为第一个文档可能锁定错误类型（字符串被映射为 text、含义不明的数字被映射为 keyword）。
6. 索引设置：在部署允许时（Self-Managed / Elastic Cloud Hosted）于同一个 PUT /{index} 请求中设置明确的 number_of_shards 和 number_of_replicas；在 Serverless 上省略分片和副本数（由 Elastic 管理），但仍需提供显式 mappings；说明所选值或记录使用默认值。
7. 创建后验证：用 GET /products/_mapping 确认映射生效。
8. 防止映射爆炸与存储膨胀的审查检查：仅用于过滤和聚合的字段（url、HTTP status_code、tags、ID）必须是 keyword 而非 text；text 浪费空间，且在 text 上聚合需要 fielddata 或本不该存在的 .keyword 子字段。
9. 检查 message.keyword 是否缺少 ignore_above：大段全文正文上的 keyword 子字段会把整个原始字符串索引为单个词项；仅在需要全文搜索时移除该子字段，或确实需要有限精确匹配子字段时加上 ignore_above。
10. 检查动态自由对象：对用户提供的键值数据使用 object 且 dynamic 为 true、存在数千个不同键时会导致映射爆炸；建议改用 flattened（或 strict dynamic / 白名单策略）。
11. 对仅在命中结果中返回、从不排序/聚合/过滤的字段（如仅展示用的 session_id），在 keyword 上设置 doc_values: false 以在大规模下节省磁盘。
12. 对精度有界的指标（如 response_time_ms），当存储是主要考量时，优先使用带合适 scaling_factor 的 scaled_float 而非普通 float/double。
13. 除非未知字段是明确需求，根映射优先使用 dynamic: strict。
14. 类型变更必须新建索引并 reindex：Elasticsearch 无法原地修改已有字段类型；当审查发现错误类型（text→keyword、object→flattened、float→scaled_float、已有字段的 doc_values 变更）时，明确说明修复需要新索引加 reindex，而不是在线上索引上更新 mapping。
15. 修正现有大流量索引（如 events）的工作流：在新索引名（如 events-v2）上设计包含步骤 2–3 全部修正的 mapping；用 PUT /events-v2 和完整修正后的 mappings（以及适用时的 settings）创建目标索引；用 POST /_reindex 复制文档（大索引用 wait_for_completion=false 并跟踪任务），source 为 { "index": "events" }，dest 为 { "index": "events-v2" }；用 GET /events-v2/_count（与源计数对比）和 GET /events-v2/_mapping（确认类型）验证；验证通过后切换读写（索引别名切换或应用配置）。
16. 对绿地索引，在首次写入前用一次 PUT /{index} 即可完全避免 reindex。
17. 按顺序执行审查清单：1) 将每个字段类型与其声明的访问模式匹配；2) 标记仅用于过滤/聚合的字段上的 text，以及搜索与排序/聚合共用一个逻辑字段时缺失的多字段；3) 标记大段分析文本上缺少 ignore_above 的 message.keyword（或类似字段）；4) 标记高基数自由映射上的动态 object，建议 flattened；5) 提出仅检索字段和数值存储优化（doc_values: false、scaled_float）；6) 说明类型变更需要新索引和 POST /_reindex，然后给出修正后的 mapping 和 reindex 计划。
18. 遵循最小映射原则：只映射访问模式所需内容，每个子字段和分析形式都会增加索引数据。
19. 创建后始终用 GET /{index}/_mapping 确认；reindex 后用 GET /{index}/_count 确认。
20. 注意跨技能边界：在索引间复制文档属于 POST /_reindex（切片、限流、任务跟踪见 reindex 技能）；把文件加载到新索引属于批量写入，不属于索引设计。

适用边界 · 注意事项

• 需要先安装并配置 elastic CLI（≥ 0.2，支持 stack es）并通过它执行操作；未安装时不要猜测凭据、直接调用 HTTP API 或尝试其他变通方式。
• 显式分片和副本设置仅适用于 Self-Managed 和 Elastic Cloud Hosted；Serverless 上由 Elastic 内部管理，应省略分片和副本数。
• 不要对上述类型变更尝试原地 mapping 修复——它们会被拒绝或导致数据不一致。