---
title: "查询分片"
date: 2026-03-14
lastmod: 2026-03-14
description: "介绍如何使用 Cat API 查询集群中所有索引的分片状态和统计信息。"
tags: ["Cat API", "分片", "监控", "索引管理"]
summary: "此 API 用于显示集群中所有索引的分片状态和详细统计信息。
API #  GET /_cat/shards GET /_cat/shards/{index} API 的作用 #  返回集群中所有分片的状态和统计信息，包括：
 分片基本信息：索引名称、分片 ID、主副分片标识、状态 文档统计：分片中的文档数量 存储信息：分片存储大小 节点信息：分片所在节点的 IP 和名称 操作统计：索引、查询、刷新、合并等操作的计数和耗时 缓存统计：查询缓存、字段数据缓存等 段统计：段数量、内存使用等  API 的参数 #  路由参数 #     参数 类型 是否必需 描述     index string 可选 索引名称
支持逗号分隔多个索引
支持通配符 *    查询字符串参数 #     参数 类型 是否必需 默认值 描述     bytes string 可选 自动 字节显示单位"
---


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

## API

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

## API 的作用

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

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

## API 的参数

### 路由参数

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

### 查询字符串参数

| 参数 | 类型 | 是否必需 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `bytes` | string | 可选 | 自动 | 字节显示单位<br>可选值：`b`, `kb`, `mb`, `gb`, `tb`, `pb` |
| `format` | string | 可选 | text | 响应格式<br>可选值：`json`, `yaml`, `text` |
| `h` | string | 可选 | 默认列 | 指定显示的列，逗号分隔 |
| `help` | boolean | 可选 | false | 显示帮助信息 |
| `local` | boolean | 可选 | false | 是否从本地节点获取信息 |
| `master_timeout` | time | 可选 | 30s | 等待主节点响应的超时时间 |
| `s` | string | 可选 | - | 排序列，支持 `:asc` 和 `:desc` |
| `size` | string | 可选 | 原始 | 计数显示单位<br>可选值：`k`, `m`, `g`, `t`, `p` |
| `time` | string | 可选 | ms | 时间显示单位<br>可选值：`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` | 分片正在迁移到其他节点 |

## 请求示例

```bash
# 查询所有分片
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 格式

```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
```

## 使用场景

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

## 排查未分配分片

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

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

## 性能监控示例

```bash
# 查看索引操作统计
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
```

## 注意事项

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

## 最佳实践

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

## 相关文档

- [查询分片分配](./get-shard-allocation.md)
- [查询分段信息Cat格式](./get-segment-info-cat-format.md)
- [查询集群健康](./get-cluster-health-cat-format.md)
- [获取索引列表](./get-index-list.md)