查询分片

此 API 用于显示集群中所有索引的分片状态和详细统计信息。

API #

GET /_cat/shards
GET /_cat/shards/{index}

API 的作用 #

返回集群中所有分片的状态和统计信息，包括：

分片基本信息：索引名称、分片 ID、主副分片标识、状态
文档统计：分片中的文档数量
存储信息：分片存储大小
节点信息：分片所在节点的 IP 和名称
操作统计：索引、查询、刷新、合并等操作的计数和耗时
缓存统计：查询缓存、字段数据缓存等
段统计：段数量、内存使用等

API 的参数 #

路由参数 #

参数	类型	是否必需	描述
`index`	string	可选	索引名称支持逗号分隔多个索引支持通配符 `*`

查询字符串参数 #

参数	类型	是否必需	默认值	描述
`bytes`	string	可选	自动	字节显示单位可选值：`b`, `kb`, `mb`, `gb`, `tb`, `pb`
`format`	string	可选	text	响应格式可选值：`json`, `yaml`, `text`
`h`	string	可选	默认列	指定显示的列，逗号分隔
`help`	boolean	可选	false	显示帮助信息
`local`	boolean	可选	false	是否从本地节点获取信息
`master_timeout`	time	可选	30s	等待主节点响应的超时时间
`s`	string	可选	-	排序列，支持 `:asc` 和 `:desc`
`size`	string	可选	原始	计数显示单位可选值：`k`, `m`, `g`, `t`, `p`
`time`	string	可选	ms	时间显示单位可选值：`nanos`, `micros`, `ms`, `s`, `m`, `h`, `d`
`v`	boolean	可选	false	详细模式，显示列头

返回的字段信息 #

默认显示字段 #

列名	描述
`index`	索引名称
`shard`	分片 ID
`prirep`	主副分片标识（p=primary, r=replica）
`state`	分片状态（STARTED、UNASSIGNED、INITIALIZING、RELOCATING）
`docs`	分片中的文档数量
`store`	分片存储大小
`ip`	分片所在节点的 IP 地址
`node`	分片所在节点的名称

可选显示字段 #

列名	描述
`sync_id`	同步 ID
`unassigned.reason`	分片未分配的原因
`unassigned.at`	分片未分配的时间
`unassigned.for`	分片未持续的时长
`completion.size`	完成字段的大小
`fielddata.memory_size`	字段数据缓存内存大小
`fielddata.evictions`	字段数据驱逐次数
`query_cache.memory_size`	查询缓存内存大小
`query_cache.evictions`	查询缓存驱逐次数
`flush.total`	刷新操作总数
`flush.total_time`	刷新操作总耗时
`get.current`	当前 get 操作数
`get.time`	get 操作耗时
`get.total`	get 操作总数
`get.exists_time`	成功 get 操作耗时
`get.exists_total`	成功 get 操作总数
`get.missing_time`	失败 get 操作耗时
`get.missing_total`	失败 get 操作总数
`indexing.delete_current`	当前删除操作数
`indexing.delete_time`	删除操作耗时
`indexing.delete_total`	删除操作总数
`indexing.index_current`	当前索引操作数
`indexing.index_time`	索引操作耗时
`indexing.index_total`	索引操作总数
`indexing.index_failed`	索引失败操作数
`merges.current`	当前合并操作数
`merges.current_docs`	当前合并的文档数
`merges.current_size`	当前合并的大小
`merges.total`	合并操作总数
`merges.total_time`	合并操作总耗时
`refresh.total`	刷新操作总数
`refresh.time`	刷新操作耗时
`refresh.external_total`	外部刷新操作总数
`refresh.external_time`	外部刷新操作耗时
`refresh.listeners`	待处理的刷新监听器数
`search.fetch_current`	当前获取阶段操作数
`search.fetch_time`	获取阶段耗时
`search.fetch_total`	获取操作总数
`search.open_contexts`	开放的搜索上下文
`search.query_current`	当前查询阶段操作数
`search.query_time`	查询阶段耗时
`search.query_total`	查询操作总数
`search.scroll_current`	开放的滚动上下文
`search.scroll_time`	滚动上下文保持时间
`search.scroll_total`	完成的滚动上下文数
`segments.count`	段数量
`segments.memory`	段内存使用
`segments.index_writer_memory`	索引写入器内存使用
`segments.version_map_memory`	版本图内存使用
`segments.fixed_bitset_memory`	固定位集内存使用
`seq_no.max`	最大序列号
`seq_no.local_checkpoint`	本地检查点
`seq_no.global_checkpoint`	全局检查点
`warmer.current`	当前预热操作数
`warmer.total`	预热操作总数
`warmer.total_time`	预热操作总耗时
`path.data`	分片数据路径
`path.state`	分片状态路径

分片状态说明 #

状态	描述
`STARTED`	分片已启动并正常运行
`UNASSIGNED`	分片未分配到任何节点
`INITIALIZING`	分片正在初始化
`RELOCATING`	分片正在迁移到其他节点

请求示例 #

# 查询所有分片
GET /_cat/shards

# 显示列头
GET /_cat/shards?v

# 查询指定索引的分片
GET /_cat/shards/my-index

# 查询多个索引的分片
GET /_cat/shards/index1,index2

# 使用通配符查询
GET /_cat/shards/logs-*

# 使用 JSON 格式
GET /_cat/shards?format=json

# 只显示特定列
GET /_cat/shards?h=index,shard,prirep,state,store,node

# 按存储大小降序排列
GET /_cat/shards?s=store:desc

# 显示未分配的分片
GET /_cat/shards?h=index,shard,prirep,state,unassigned.reason

# 显示索引操作统计
GET /_cat/shards?h=index,indexing.index_current,indexing.index_total

# 显示段统计信息
GET /_cat/shards?h=index,segments.count,segments.memory

响应示例 #

文本格式（默认） #

index shard prirep state      docs store ip        node
logs  0     p      STARTED  1000  5mb  10.0.1.1   data-node-1
logs  0     r      STARTED  1000  5mb  10.0.1.2   data-node-2
logs  1     p      STARTED  1200  6mb  10.0.1.2   data-node-2
logs  1     r      STARTED  1200  6mb  10.0.1.3   data-node-3

JSON 格式 #

[
  {
    "index": "logs",
    "shard": "0",
    "prirep": "p",
    "state": "STARTED",
    "docs": "1000",
    "store": "5mb",
    "ip": "10.0.1.1",
    "node": "data-node-1"
  },
  {
    "index": "logs",
    "shard": "0",
    "prirep": "r",
    "state": "STARTED",
    "docs": "1000",
    "store": "5mb",
    "ip": "10.0.1.2",
    "node": "data-node-2"
  }
]

未分配分片示例 #

index       shard prirep state        docs store ip   node
test-index  0     p      UNASSIGNED   -    -    -    -
test-index  0     r      STARTED      100  1mb  ...  data-node-1

使用场景 #

分片状态监控：检查所有分片是否正常分配
负载均衡检查：确认主副分片分布是否合理
性能分析：查看索引、查询等操作的统计信息
存储管理：监控各分片的存储大小
问题排查：诊断未分配分片的原因

排查未分配分片 #

# 查看未分配分片及原因
GET /_cat/shards?h=index,shard,prirep,state,unassigned.reason,unassigned.details

常见的未分配原因：

INDEX_CREATED：索引创建后分片尚未分配
CLUSTER_RECOVERED：集群恢复后的分片
NODE_LEFT：节点离开导致分片未分配
ALLOCATION_FAILED：分片分配失败

性能监控示例 #

# 查看索引操作统计
GET /_cat/shards?h=index,indexing.index_current,indexing.index_total,indexing.index_failed

# 查看搜索操作统计
GET /_cat/shards?h=index,search.query_current,search.fetch_current

# 查看合并操作
GET /_cat/shards?h=index,merges.current,merges.total,merges.total_time

# 查看段统计
GET /_cat/shards?h=index,segments.count,segments.memory,segments.index_writer_memory

注意事项 #

local=true 时可能返回过时信息，但响应更快
通配符 * 可以匹配多个索引
分片状态变化频繁，建议实时监控
大量分片时响应时间可能较长
某些字段（如 docs）可能显示 - 表示不可用

最佳实践 #

定期检查：定期检查未分配分片，及时处理
均衡分布：确保主副分片分布在不同节点
监控性能：关注索引和查询操作的统计信息
段管理：监控段数量，定期执行 force_merge
告警设置：对未分配分片设置告警

API #

API 的作用 #

API 的参数 #

路由参数 #

查询字符串参数 #

返回的字段信息 #

默认显示字段 #

可选显示字段 #

分片状态说明 #

请求示例 #

响应示例 #

文本格式（默认） #

JSON 格式 #

未分配分片示例 #

使用场景 #

排查未分配分片 #

性能监控示例 #

注意事项 #

最佳实践 #

相关文档 #