Elasticsearch REST API 实战精要：从索引建模到聚合分析的工程闭环
你有没有遇到过这样的场景？
凌晨两点，线上搜索服务突然响应变慢，Kibana 里search.query.time.ms指标飙升；翻看日志发现大量query_phase_execution_exception；排查半天才发现——某个新上线的wildcard查询正在全表扫描title字段，而这个字段压根没配ngram分词器，也没加keyword子字段……
这不是玄学故障，而是对 Elasticsearch REST API语义理解偏差的典型代价。Elasticsearch 的强大，从来不在它有多“智能”，而在于它把分布式搜索的复杂性，封装进了一套可预测、可调试、可脚本化的 HTTP 接口体系中。但前提是：你得真正读懂它的 URL 路径设计逻辑、HTTP 方法隐含契约、JSON 请求体的 DSL 分层意图，以及每个参数背后真实的执行路径。
下面的内容，不是手册复读，也不是概念堆砌。它来自真实生产环境中的踩坑记录、性能调优笔记和架构演进思考——我们以工程师的视角，重新梳理 Elasticsearch REST API 的核心脉络。
索引不是“数据库”，而是“查询上下文”的声明式定义
很多人初学时会下意识把PUT /products类比为CREATE DATABASE products，这埋下了第一个隐患：索引一旦创建，它的分片数（number_of_shards）就锁死了。你无法像 ALTER TABLE 那样后期扩容。这意味着：
- 如果预估错误，写入吞吐撑不住，只能重建索引 + reindex —— 停机或双写迁移；
- 如果设得过大（比如 100 个分片），小数据量下反而因协调开销拖慢查询；
- 更隐蔽的是：_routing默认关闭，所有文档均匀打散到各分片，但如果你的查询天然按user_id聚焦，却没启用 routing，那每次查询都要 fan-out 到全部分片。
所以，创建索引的第一步，永远不是敲PUT，而是回答三个问题：
1.数据规模与写入压力→ 决定number_of_shards（建议单分片 10~50GB，不超过 3 万文档/秒写入）；
2.查询模式是否具备局部性→ 决定是否启用_routing（如user_id作为 routing key）；
3.字段语义是否清晰可分→ 决定 mapping 中text与keyword的拆分粒度（例如product_name.text用于搜索，product_name.keyword用于聚合和精确过滤）。
PUT /products_v2 { "settings": { "number_of_shards": 6, "number_of_replicas": 1, "refresh_interval": "60s", "routing_partition_size": 2 // 启用 routing 时必配，避免单分片热点 },
