# CLUSTER SHARDS

> Return each shard of the cluster with its slot ranges and its nodes.

URL: https://docs.hotkv.com/commands/cluster-shards/

```
CLUSTER SHARDS
```

- Group: Cluster
- Complexity: O(N) where N is the number of known nodes
- HotKV Cloud: all plans
- On-Premise: no license needed

`CLUSTER SHARDS` describes the cluster by shard: each primary with its
replicas, the slot ranges they serve, and each node's address, role,
replication offset and health. It is the structured replacement for
[CLUSTER SLOTS](https://docs.hotkv.com/commands/cluster-slots/index.md), and cluster clients use it to
build their slot map.

Shards that serve slots come first, ordered by their first slot, then
shards without slots. Within a shard the primary serving slots comes first,
then any other primaries, then the replicas. Nodes still in their handshake
are left out; a failed primary stays in the shard its replica took over.

## Return value

An array with one entry per shard. Each shard is a map in RESP3 and a flat
array of field and value pairs in RESP2:

| Field | Value |
| --- | --- |
| `slots` | Flat array of integers: the start and end of each slot range |
| `nodes` | Array of nodes, each a map (RESP3) or flat pairs (RESP2) with the fields below |
| `id` | The shard ID |

Node fields:

| Field | Type | Meaning |
| --- | --- | --- |
| `id` | Bulk string | Node ID |
| `port` | Integer | Plain client port, when the node has one |
| `tls-port` | Integer | TLS client port, when the node has one |
| `ip` | Bulk string | IP address |
| `endpoint` | Bulk string | The address clients should use, as `cluster-preferred-endpoint-type` chooses |
| `hostname` | Bulk string | The announced hostname, when the node has one |
| `role` | Bulk string | `master` or `replica` |
| `replication-offset` | Integer | The node's replication offset |
| `health` | Bulk string | `online`, `fail` (marked as failed), or `loading` (a replica that has not finished its first sync) |
| `availability-zone` | Bulk string | The node's `availability-zone` setting, when it has one. It comes last. |

`ip`, `endpoint` and the ports are what the node announces to clients, that is
`cluster-announce-client-ipv4` and `cluster-announce-client-port` when it has
them. A node started with `--availability-zone zone-a`, `--cluster-announce-hostname
host0.example.com`, `--cluster-announce-client-ipv4 10.0.0.1` and
`--cluster-announce-client-port 7000` reports (RESP2 form, one shard, one node):

```
127.0.0.1:7005> CLUSTER SHARDS
1) 1) "slots"
   2) 1) (integer) 0
      2) (integer) 16383
   3) "nodes"
   4) 1)  1) "id"
          2) "7a28581ffafcbe156e07d2e0fc7107eb808e2f1f"
          3) "port"
          4) (integer) 7000
          5) "ip"
          6) "10.0.0.1"
          7) "endpoint"
          8) "10.0.0.1"
          9) "hostname"
         10) "host0.example.com"
         11) "role"
         12) "master"
         13) "replication-offset"
         14) (integer) 0
         15) "health"
         16) "online"
         17) "availability-zone"
         18) "zone-a"
   5) "id"
   6) "9aa04484276b024fccfc4f24ad61c4b22b514f77"
```

With cluster mode off, the reply is an empty array.

## Examples

```
127.0.0.1:6379> CLUSTER SHARDS
1) 1) "slots"
   2) 1) (integer) 0
      2) (integer) 5460
   3) "nodes"
   4) 1)  1) "id"
          2) "b4240bf759694b9ba85b3b5efd51785b86261c3e"
          3) "port"
          4) (integer) 6379
          5) "ip"
          6) "10.0.0.1"
          7) "endpoint"
          8) "10.0.0.1"
          9) "role"
         10) "master"
         11) "replication-offset"
         12) (integer) 98213
         13) "health"
         14) "online"
      2)  1) "id"
          2) "80c69623243ebb98309adbe1d4c95f7857e37c2c"
          3) "port"
          4) (integer) 6379
          5) "ip"
          6) "10.0.0.4"
          7) "endpoint"
          8) "10.0.0.4"
          9) "role"
         10) "replica"
         11) "replication-offset"
         12) (integer) 98213
         13) "health"
         14) "online"
   5) "id"
   6) "2628190a08e92e42a2709833fd2f26ea9331c999"
2) 1) "slots"
...
```

## Compatibility

Same fields as Redis 7 and Valkey 8, plus the shard `id` that Valkey 9
added.

## See also

[CLUSTER SLOTS](https://docs.hotkv.com/commands/cluster-slots/index.md), [CLUSTER NODES](https://docs.hotkv.com/commands/cluster-nodes/index.md),
[CLUSTER MYSHARDID](https://docs.hotkv.com/commands/cluster-myshardid/index.md)

In a cluster: [Monitoring a cluster](https://docs.hotkv.com/clustering/monitoring/index.md)