Elasticsearch 命令速查表 - Elasticsearch 常用命令大全
面向接管 Elasticsearch 集群、要回答"为什么索引慢、为什么分片不是主"的运维与搜索工程师。难点不在列出 REST，而在读懂集群颜色、理解什么会触发分片搬移、以及 ILM 策略的取舍。读完能检查集群健康、定位并诊断 red/unassigned 分片、管理别名与索引生命周期、用 term/range 及多搜索查询取数，并按慢查询与磁盘压力定位瓶颈。
典型使用场景
面向需要直接对着 Elasticsearch 集群排障的工程师：索引为什么是 red、有未分配分片吗、某条查询为什么慢、内存为什么爆。这里用 curl 而非客户端 SDK 是刻意的——排障时你要能确认「服务端到底收到了什么请求」。本表覆盖集群状态（_cluster/health、_cat/nodes、_cat/allocation）、分片与索引（_cat/indices、_cat/shards、_cluster/allocation/explain、_ilm/explain、动态改副本数）、文档 CRUD（_doc / _update / _bulk 与 ndjson 格式）、查询 DSL（match / term / range / bool）、聚合（terms / avg / date_histogram / range / cardinality）、以及慢日志与熔断器、磁盘水位与 forcemerge 等运维动作。必须先建立的一条判断是：写入报错时先看 _cat/shards 与 allocation/explain，而不是反复重试。
集群状态 Cluster 6
curl localhost:9200/_cluster/health?prettycurl localhost:9200/_cat/nodes?vcurl localhost:9200/_cat/health?vcurl localhost:9200/_cluster/stats?prettycurl localhost:9200/_cat/allocation?vcurl localhost:9200/_cat/master?v分片与索引 Shard & Index 6
curl localhost:9200/_cat/indices?vcurl localhost:9200/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reasoncurl localhost:9200/_cluster/allocation/explain?prettycurl -XDELETE localhost:9200/<index>curl localhost:9200/_ilm/explain/<index>?prettycurl -XPUT localhost:9200/<index>/_settings -H "Content-Type:application/json" -d '{"number_of_replicas":1}'文档 CRUD 6
curl -XPOST localhost:9200/<index>/_doc -d '{"name":"tom"}' -H "Content-Type:application/json"curl -XPUT localhost:9200/<index>/_doc/1 -d '{"name":"tom"}' -H "Content-Type:application/json"curl -XPOST localhost:9200/<index>/_update/1 -d '{"doc":{"age":20}}' -H "Content-Type:application/json"curl -XDELETE localhost:9200/<index>/_doc/1curl -XPOST localhost:9200/<index>/_bulk -d '{"index":{"_id":"1"}}
{"name":"a"}
' -H "Content-Type:application/x-ndjson"curl localhost:9200/<index>/_doc/1?pretty搜索查询 Search 6
curl localhost:9200/<index>/_search?q=name:tom&prettycurl localhost:9200/<index>/_search -d '{"query":{"match":{"name":"tom"}}}' -H "Content-Type:application/json"curl localhost:9200/<index>/_search -d '{"query":{"term":{"status":"active"}}}' -H "Content-Type:application/json"curl localhost:9200/<index>/_search -d '{"query":{"range":{"age":{"gte":18,"lte":30}}}}' -H "Content-Type:application/json"curl localhost:9200/<index>/_search -d '{"query":{"bool":{"must":[{"match":{"name":"tom"}}],"filter":[{"term":{"status":"active"}}]}}}' -H "Content-Type:application/json"curl localhost:9200/<index>/_search -d '{"query":{"match_all":{}},"sort":[{"created_at":"desc"}],"from":0,"size":10}' -H "Content-Type:application/json"聚合分析 Aggregation 5
curl localhost:9200/<index>/_search -d '{"size":0,"aggs":{"by_status":{"terms":{"field":"status"}}}}' -H "Content-Type:application/json"curl localhost:9200/<index>/_search -d '{"size":0,"aggs":{"avg_age":{"avg":{"field":"age"}}}}' -H "Content-Type:application/json"curl localhost:9200/<index>/_search -d '{"size":0,"aggs":{"sales":{"date_histogram":{"field":"created_at","calendar_interval":"1d"}}}}' -H "Content-Type:application/json"curl localhost:9200/<index>/_search -d '{"size":0,"aggs":{"price_ranges":{"range":{"field":"price","ranges":[{"to":100},{"from":100,"to":500},{"from":500}]}}}}' -H "Content-Type:application/json"curl localhost:9200/<index>/_search -d '{"size":0,"aggs":{"users":{"cardinality":{"field":"user_id"}}}}' -H "Content-Type:application/json"查询与慢日志 Query & Slowlog 5
curl localhost:9200/<index>/_count?prettycurl localhost:9200/_nodes/stats/thread_pool?prettycurl localhost:9200/_nodes/stats/breaker?prettytail -f /var/log/elasticsearch/*_index_search_slowlog.jsoncurl localhost:9200/<index>/_settings?pretty运维与磁盘 Disk & Ops 6
curl localhost:9200/_cluster/settings?prettycurl -XPUT localhost:9200/_cluster/settings -H "Content-Type:application/json" -d '{"transient":{"cluster.routing.allocation.disk.watermark.low":"85%"}}'curl -XPOST localhost:9200/_forcemerge?max_num_segments=1df -h /var/lib/elasticsearchcurl -XPOST localhost:9200/<index>/_closecurl -XPOST localhost:9200/<index>/_refresh参数矩阵
| 参数 | 作用 | 示例 |
|---|---|---|
?pretty | 让响应格式化输出，排查时几乎必加，否则 JSON 会挤成一行 | curl localhost:9200/_cluster/health?pretty |
_cat/nodes?v | 列出节点与它们的角色、堆内存与负载，是节点级问题的入口 | curl localhost:9200/_cat/nodes?v |
_cat/health?v | 紧凑形式看集群状态、节点数与分片计数，比 JSON 版好读 | curl localhost:9200/_cat/health?v |
_cat/allocation?v | 按节点看分片分布与磁盘占用，能看出数据倾斜 | curl localhost:9200/_cat/allocation?v |
_cat/master?v | 确认当前 master 是哪台；多 master 配置错乱时先看这里 | curl localhost:9200/_cat/master?v |
_cat/indices?v | 列出全部索引的文档数、存储大小与健康状态，排查「哪张索引在涨」 | curl localhost:9200/_cat/indices?v |
_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason | 用 -h 定制列并带上未分配原因，是分片异常排查的标准命令 | curl localhost:9200/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason |
_cluster/allocation/explain | 解释为什么某个分片没有被分配，输出磁盘水位、节点数等具体原因 | curl localhost:9200/_cluster/allocation/explain?pretty |
-XPUT <index>/_settings -d '{"number_of_replicas":1}' | 动态改副本数；单节点测试环境设为 0 才能让索引变绿 | curl -XPUT localhost:9200/<index>/_settings -H "Content-Type:application/json" -d '{"number_of_replicas":1}' |
_ilm/explain/<index> | 查看索引生命周期策略卡在哪一步，是托管索引无法删除/写入时的排查起点 | curl localhost:9200/_ilm/explain/<index>?pretty |
-XPOST <index>/_doc | 自动生成 ID 写入一条文档；成功返回 201 与 _id | curl -XPOST localhost:9200/<index>/_doc -d '{"name":"tom"}' -H "Content-Type:application/json" |
-XPUT <index>/_doc/1 | 指定 ID 写入，重复执行会整文档覆盖（不是部分更新） | curl -XPUT localhost:9200/<index>/_doc/1 -d '{"name":"tom"}' -H "Content-Type:application/json" |
-XPOST <index>/_update/1 -d '{"doc":{...}}' | 部分更新，文档内部用 doc 包裹；这是与 PUT 的关键区别 | curl -XPOST localhost:9200/<index>/_update/1 -d '{"doc":{"age":20}}' -H "Content-Type:application/json" |
_bulk 与 application/x-ndjson | 批量写入；每行必须以换行结尾，末行也要带 ，格式错了会整批失败 | curl -XPOST localhost:9200/<index>/_bulk -d '{"index":{"_id":"1"}}\n{"name":"a"}\n' -H "Content-Type:application/x-ndjson" |
_search?q=name:tom | Lucene 查询语法，最适合快速试探字段是否存在及可分词性 | curl localhost:9200/<index>/_search?q=name:tom&pretty |
{"query":{"match":{"name":"tom"}}} | match 查询会分词、score 按相关度排序，是全文检索默认选择 | curl localhost:9200/<index>/_search -d '{"query":{"match":{"name":"tom"}}}' -H "Content-Type:application/json" |
{"query":{"term":{"status":"active"}}} | term 查询不分词，必须匹配倒排里的完整词项；用错是「查不到数据」的常见原因 | curl localhost:9200/<index>/_search -d '{"query":{"term":{"status":"active"}}}' -H "Content-Type:application/json" |
{"query":{"range":{"age":{"gte":18,"lte":30}}}} | 范围查询，用于数值与日期过滤 | curl localhost:9200/<index>/_search -d '{"query":{"range":{"age":{"gte":18,"lte":30}}}}' -H "Content-Type:application/json" |
{"query":{"bool":{"must":[...],"filter":[...]}}} | must 参与打分、filter 不打分（可缓存），性能敏感时把非相关条件放 filter | curl localhost:9200/<index>/_search -d '{"query":{"bool":{"must":[{"match":{"name":"tom"}}],"filter":[{"term":{"status":"active"}}]}}}' -H "Content-Type:application/json" |
"size":0 + aggs | 把 size 设为 0 只算聚合不返回文档，聚合查询的标准写法 | curl localhost:9200/<index>/_search -d '{"size":0,"aggs":{"by_status":{"terms":{"field":"status"}}}}' -H "Content-Type:application/json" |
date_histogram + calendar_interval | 按日历间隔分桶（1d / 1w / 1M），处理时区与跨月时比 fixed_interval 更符合直觉 | curl localhost:9200/<index>/_search -d '{"size":0,"aggs":{"sales":{"date_histogram":{"field":"created_at","calendar_interval":"1d"}}}}' -H "Content-Type:application/json" |
cardinality | 近似去重计数，速度与内存远好于精确计数，但结果是近似值 | curl localhost:9200/<index>/_search -d '{"size":0,"aggs":{"users":{"cardinality":{"field":"user_id"}}}}' -H "Content-Type:application/json" |
_nodes/stats/breaker | 查看熔断器触发次数；parent breaker 频繁触发意味着内存压力已到临界 | curl localhost:9200/_nodes/stats/breaker?pretty |
_nodes/stats/thread_pool | 查看搜索与写入线程池的队列与拒绝数，是查询打爆集群的证据 | curl localhost:9200/_nodes/stats/thread_pool?pretty |
_forcemerge?max_num_segments=1 | 强制合并段，减少段数提升查询速度，但会占大量 IO，生产上应限流执行 | curl -XPOST localhost:9200/_forcemerge?max_num_segments=1 |
_close / _refresh | _close 停止对该索引读写省资源；_refresh 让最新写入立即可搜，代价是产生新段 | curl -XPOST localhost:9200/<index>/_close |
transient 集群设置 + disk.watermark | 动态调整磁盘水位；transient 重启后失效，persistent 才会持久化 | curl -XPUT localhost:9200/_cluster/settings -H "Content-Type:application/json" -d '{"transient":{"cluster.routing.allocation.disk.watermark.low":"85%"}}' |
易错点与避坑指南
现象数据明明写进去了，用同一个关键词却查不到。
原因用 term 去查一个被分词（text 类型）的字段。term 不分词，只能匹配完整词项。
处置全文字段用 match；term 只用于 keyword、status、ID 这类不分词字段。
现象_bulk 请求返回 400，整批都没写进去。
原因ndjson 格式错误：action 行与数据行必须各占一行、每行以换行结尾，最后一行也必须有换行。
处置用文件而非 -d 拼字符串生成请求体，并确认文件以换行结束；先少量几条验证再放量。
现象索引状态是 red，重建索引也没有恢复。
原因存在未分配的主分片；red 表示有数据不可用，yellow 才只是副本缺失。
处置先 curl _cluster/allocation/explain 看具体原因（常见是磁盘超水位或节点数不足），处理后再看 _cat/shards。
现象单节点测试环境下索引一直是 yellow。
原因副本数为 1 但只有一个节点，副本无处可放。
处置把 number_of_replicas 设为 0；这是单节点环境的正常做法，不是故障。
现象改了集群设置，重启后又失效。
原因写进了 transient 段，它只在节点存活期间有效。
处置需要持久的设置写进 persistent 段；同时确认该磁盘水位设置确实被集群接受。
现象查询变慢，线程池里有大量 rejected 计数。
原因深分页（from + size 过大）或宽聚合把搜索线程池打满，请求被拒绝；用 curl localhost:9200/_nodes/stats/thread_pool?pretty 可见拒绝计数
处置改用 search_after 或 PIT 做深翻页，收敛聚合范围，并对查询接口做限流。
现象刚写入的文档查不到，过一会儿又能查到。
原因近实时（NRT）机制：写入后默认约 1 秒才可见。
处置需要立即可见时调用 _refresh（注意会产生新段，生产上不要每次都调）。
现象forcemerge 之后集群 IO 飙升、查询反而更抖。
原因合并会读取大量段数据并重建索引，属于重 IO 操作。
处置在低峰期执行并限制批处理规模；对高频写入索引改用 rollover 按大小滚动而不是反复合并。
排障路径
1先看集群整体健康度
curl localhost:9200/_cluster/health?prettyred 表示有主分片不可用，yellow 表示副本缺失。
2看分片状态与未分配原因
curl localhost:9200/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reasonunassigned.reason 列直接给出原因线索。
3解释分片未被分配的具体原因
curl localhost:9200/_cluster/allocation/explain?pretty常见输出指向磁盘水位、分片感知或节点数不足。
4定位是哪张索引在持续增长
curl localhost:9200/_cat/indices?v对比多次执行的 store 与 docs.count 变化。
5检查内存压力与熔断器
curl localhost:9200/_nodes/stats/breaker?prettyparent breaker 计数持续增长说明内存已触顶。
6查慢查询日志
tail -f /var/log/elasticsearch/*_index_search_slowlog.json需要事先启用 search slowlog 才能拿到记录。
命令示例
yellow 排障：先看分片，再解释未分配原因
curl localhost:9200/_cat/health?v
curl localhost:9200/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason
curl localhost:9200/_cluster/allocation/explain?pretty单节点集群默认副本数为 1，分片永远分不出第二份，yellow 是预期状态而非故障。但如果是多节点仍然 yellow，_cat/shards 里的 unassigned.reason 会给出具体原因（磁盘水位、节点数不够、awareness），_cluster/allocation/explain 再给出决策器的完整解释。
输出
health status index pri rep docs.count store.size yellow open orders 3 1 1204 8.1mb
写完立刻查：手动 refresh
curl -XPOST localhost:9200/<index>/_doc -d '{"name":"tom"}' -H "Content-Type:application/json"
curl -XPOST localhost:9200/<index>/_refresh
curl localhost:9200/<index>/_search?q=name:tom&prettyElasticsearch 的写入先进入内存，refresh 才把近实时（NRT）段提交到可搜索状态，默认间隔 1 秒。所以「刚写完查不到」是正常行为而不是 bug。测试环境调完数据立刻断言时必须手动 _refresh，否则测试会随机失败；生产写入路径上不要为了「实时」而把 refresh_interval 调到极小，会严重拖慢索引。
输出
{"_index":"orders","result":"created","_id":"Yb3nXk0B..."}bool 查询：must 走打分，filter 走缓存
curl -XPOST localhost:9200/<index>/_search -d '{"query":{"bool":{"must":[{"match":{"name":"tom"}}],"filter":[{"term":{"status":"active"}}]}}}' -H "Content-Type:application/json"语义相同的条件放在 filter 里不参与相关性打分，而且结果可被缓存复用：status 这类只做「要/不要」判断的字段放 filter，参与排序和 bm25 打分的字段（name、title）放 must。这一条对搜索接口的吞吐差别很大。
批量写入用 _bulk，别循环单条
curl -XPOST localhost:9200/<index>/_bulk -d '{"index":{"_id":"1"}}
{"name":"a"}
' -H "Content-Type:application/x-ndjson"_bulk 用 x-ndjson：每两行构成一个操作（第一行元信息、第二行文档），末尾必须带换行，否则最后一条会被丢弃。循环单条 _doc 写入要为每个文档付一次 HTTP 往返，吞吐通常差一到两个数量级，导入百万级数据时是数量级的耗时差别。
size:0 聚合：只要统计，不要文档
curl -XPOST localhost:9200/<index>/_search -d '{"size":0,"aggs":{"by_status":{"terms":{"field":"status"}},"avg_age":{"avg":{"field":"age"}}}}' -H "Content-Type:application/json"默认 size 是 10，即使你只关心聚合结果，ES 也会组装并序列化这 10 条文档；size:0 直接跳过这一步，报表类查询的速度和响应体大小差别明显。terms 聚合的 field 必须是 keyword 类型（text 字段直接聚合会报 fielddata disabled）。
常见坑与注意事项
- curl -XDELETE localhost:9200/<index> 直接删索引，连同里面全部文档一起消失，且没有回收站。执行前务必用 curl localhost:9200/_cat/indices?v 确认索引名拼写（生产和测试索引常常只差后缀），并确认没有仍在写入该索引的服务。
- 不要在生产索引上跑 size:0 都省掉的全量 _search 来"看看数据"。不带任何过滤的查询会在命中的每个分片上分配线程，节点负载飙升，容易把整个集群拖进 red 或触发熔断器。排查一律带上明确的过滤条件与 size 上限。
- curl -XPUT 调大 number_of_replicas 会瞬间触发副本分配，磁盘空间按副本数直接翻倍；设成 0 又让索引失去高可用。这两个值都应通过 ILM 策略管理，手工 -XPUT 的设置在策略触发时会被覆盖，看起来"改不动"的设置通常就是被 ILM 接管了。
- 深度分页 from + size 有硬上限（默认 max_result_window 10000），from 越大单次查询的内存和耗时呈线性增长。翻到后面几页时改用 search_after，或用 scroll / PIT。强行调大 max_result_window 会显著增加节点内存压力甚至触发熔断。
- term 查询用于 keyword 字段，match 用于全文分词字段。用错的结果不是报错而是「查不到」：对 text 字段发 term 会拿整串未分词的输入做精确匹配，永远返回空；调试时先 curl localhost:9200/<index>/_mapping?pretty 看清字段类型。
- curl -XPUT 临时下调 cluster.routing.allocation.disk.watermark 会让集群在磁盘已满时继续接收写入，撑满后节点直接崩且索引损坏。transient 设置重启即失效（真正生效需要 persistent），排障时改完必须记得改回去。
提示
- 集群变 red 先用 _cat/shards 找未分配分片，再用 allocation/explain 看原因，别急着强制分配。
- 查询变慢先区分是 filter 没走缓存还是聚合基数过高，深分页用 search_after 替代 from+size。
- 磁盘超 flood watermark 会拒绝写入，先清冷索引或调水位线，而不是直接加节点。
- text 字段用 match 做全文检索，keyword 字段用 term 精确匹配，混用会导致查不到结果。
- 批量写入用 _bulk 接口，比逐条 _doc 快一个数量级，注意 Content-Type 是 application/x-ndjson。
常见问题
集群变 red/yellow 了，按什么顺序排查？
三步走。第一步定位未分配分片：curl localhost:9200/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason 直接看出是哪个索引、哪个副本没上去。第二步要原因：curl localhost:9200/_cluster/allocation/explain?pretty 会给出具体解释。第三步看整体盘面：curl localhost:9200/_cat/allocation?v 检查各节点磁盘水位，df -h /var/lib/elasticsearch 核对磁盘使用率。如果只是副本数问题，curl -XPUT localhost:9200/<index>/_settings -H "Content-Type:application/json" -d '{"number_of_replicas":1}' 动态调整副本数即可，不要急着强制分配。
term 查不到数据，换成 match 就行了吗？
别急着换，先看字段类型。match 会对查询词分词，适合 text 字段做全文检索；term 不分词，只能精确命中一个完整词值，适合 keyword 字段。用 term 查 text 字段或反过来就会查不到。另外确认状态值这类字段有没有做 keyword 子字段；多个条件组合时优先放进 bool 的 filter 而不是 must，filter 走缓存性能明显更好。排查时 curl localhost:9200/<index>/_settings?pretty 能确认索引设置。
写入的数据立刻查不到，是不是 ES 坏了？
不是，默认写入后有一小段时间不可被搜索到，属正常行为。写完马上要查到就手动刷新：curl -XPOST localhost:9200/<index>/_refresh。批量灌数据时更该用 _bulk 而不是逐条 _doc，性能差一个数量级，Content-Type 必须是 application/x-ndjson，并且用换行分隔操作行与文档体。refresh 会影响写入吞吐，生产写入路径不要每条都调；确认文档是否存在用 curl localhost:9200/<index>/_doc/1 走实时 get。
只要统计不要明细，聚合查询该怎么构造？
关键是设 "size":0，只返回聚合桶不回文档。常见几种：terms 按字段分组 {"aggs":{"by_status":{"terms":{"field":"status"}}}}；avg 求平均，还有 sum/max/min；cardinality 去重计数，用的是 HyperLogLog 近似值，精度略有损耗但内存友好；date_histogram 按时间分桶，calendar_interval 支持 1d/1M/1y；range 做数值区间分桶，用 ranges 数组配 from/to 分段统计落在各价格带的数据量。
磁盘快满了，除了加节点还能做什么？
先确认是水位线在挡写入：curl localhost:9200/_cluster/settings?pretty 看 cluster.routing.allocation.disk.watermark.low 等设置，df -h /var/lib/elasticsearch 看实际占用，超过 flood watermark 会被直接拒绝写入。应急手段有三类：临时抬高水位线 curl -XPUT localhost:9200/_cluster/settings 配 transient.cluster.routing.allocation.disk.watermark.low，但这是临时生效且需慎用；清理空间，curl -XPUT 或 -XDELETE 删除冷索引，或对只读索引 curl -XPOST localhost:9200/_forcemerge?max_num_segments=1 合并段以降低磁盘占用；暂时不用了就 curl -XPOST localhost:9200/<index>/_close 关闭索引释放资源，需要时再 open。
由 巧匠 维护
公开更新于 2026年7月21日，内容持续校对官方文档。