CLUSTER SHARDS

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, 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, CLUSTER NODES, CLUSTER MYSHARDID

In a cluster: Monitoring a cluster