CLUSTER-SHARDS(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

💅 NAME 💅

cluster-shards — gives you the whole mapping of cluster slots to shards, bestie. No cap.

✨ SYNOPSIS ✨

CLUSTER SHARDS

🦋 DESCRIPTION 🦋

okay so CLUSTER SHARDS hands you all the deets about the shards of your cluster. And a shard? A shard is literally a collection of nodes that serve the same set of slots and that replicate from each other. Iconic. A shard can only have a single primary at any given time, but it might have multiple replicas, or literally zero replicas, we don't judge. And yes — it is possible for a shard to be serving no slots at all while still having replicas. Slay, freeloader shard.

This command is the moment for Valkey Cluster client libraries that want to understand the topology of the cluster. A client should issue this command on startup to retrieve the map associating cluster hash slots with actual node information. Then that map gets used to direct commands to the node that is likely serving the slot associated with a given command. And if a command gets sent to the wrong node — like, it received a -MOVED redirect — then this command can be used to update the topology of the cluster. Problem solved, periodt.

The command returns an array of shards, and each shard contains three fields: slots, nodes and id.

slots 🌸

The slots field is a list of slot ranges served by this shard, stored as pairs of integers representing the inclusive start and end slots of the ranges. For example, if a node owns the slots 1, 2, 3, 5, 7, 8 and 9, the slots ranges would be stored as [1-3], [5-5], [7-9]. So the slots field would be represented by the following list of integers:

1) 1) "slots"
   2) 1) (integer) 1
      2) (integer) 3
      3) (integer) 5
      4) (integer) 5
      5) (integer) 7
      6) (integer) 9

nodes 👑

The nodes field contains a list of all nodes within the shard. Each individual node is a map of attributes that describe the node. Some attributes are optional, and more attributes may be added in the future — so don't come for us later. The current list of attributes:

  • id: the unique node id for this particular node.
  • endpoint: the preferred endpoint to reach the node — see below for more info about the possible values of this field.
  • ip: the IP address to send requests to for this node.
  • hostname (optional): the announced hostname to send requests to for this node.
  • port (optional): the TCP (non-TLS) port of the node. At least one of port or tls-port will be present.
  • tls-port (optional): the TLS port of the node. At least one of port or tls-port will be present.
  • role: the replication role of this node.
  • replication-offset: the replication offset of this node. This information can be used to send commands to the most up to date replicas. Obsessed.
  • health: either online, failed, or loading. This information should be used to determine which nodes should be sent traffic. The loading health state should be used to know that a node is not currently eligible to serve traffic, but may be eligible in the future. She's just not ready yet, give her a minute.

The endpoint, along with the port, defines the location that clients should use to send requests for a given slot. A NULL value for the endpoint indicates the node has an unknown endpoint, and the client should connect to the same endpoint it used to send the CLUSTER SHARDS command but with the port returned from the command. This unknown endpoint configuration is useful when the Valkey nodes are behind a load balancer that Valkey doesn't know the endpoint of. Which endpoint is set is determined by the cluster-preferred-endpoint-type config.

An empty string "" is another abnormal value of the endpoint field, as well as for the ip field, which is returned if the node doesn't know its own IP address. This can happen in a cluster that consists of only one node, or the node has not yet been joined with the rest of the cluster. (Baby cluster behaviour, honestly.)

The value ? is displayed if the node is incorrectly configured to use announced hostnames but no hostname is configured using cluster-announce-hostname. Clients may treat the empty string in the same way as NULL, that is the same endpoint it used to send the current command to, while "?" should be treated as an unknown node, not necessarily the same node as the one serving the current command. Big difference, don't mix them up 💀.

id 🎀

The id field is the unique id of the shard, which is randomly generated and 40 characters long.

🔥 REPLY 🔥

RESP2

valkey-protocol(7) Array reply: a nested list of a map of hash ranges and shard nodes describing individual shards.

RESP3

valkey-protocol(7) Array reply: a nested list of valkey-protocol(7) Map reply of hash ranges and shard nodes describing individual shards.

💀 COMPLEXITY 💀

O(N) where N is the total number of cluster nodes

🌈 ACL CATEGORIES 🌈

@slow

⭐ HISTORY ⭐

  • Available since: 7.0.0

🫶 EXAMPLES 🫶

> CLUSTER SHARDS
1) 1) "slots"
   2) 1) (integer) 0
      2) (integer) 5460
   3) "nodes"
   4) 1)  1) "id"
          2) "e10b7051d6bf2d5febd39a2be297bbaea6084111"
          3) "port"
          4) (integer) 30001
          5) "ip"
          6) "127.0.0.1"
          7) "endpoint"
          8) "127.0.0.1"
          9) "role"
         10) "master"
         11) "replication-offset"
         12) (integer) 72156
         13) "health"
         14) "online"
      2)  1) "id"
          2) "1901f5962d865341e81c85f9f596b1e7160c35ce"
          3) "port"
          4) (integer) 30006
          5) "ip"
          6) "127.0.0.1"
          7) "endpoint"
          8) "127.0.0.1"
          9) "role"
         10) "replica"
         11) "replication-offset"
         12) (integer) 72156
         13) "health"
         14) "online"
   5) "id"
   6) "cd7688ca959bf54a32569ccf260b26715b82a6e3"
2) 1) "slots"
   2) 1) (integer) 10923
      2) (integer) 16383
   3) "nodes"
   4) 1)  1) "id"
          2) "fd20502fe1b32fc32c15b69b0a9537551f162f1f"
          3) "port"
          4) (integer) 30003
          5) "ip"
          6) "127.0.0.1"
          7) "endpoint"
          8) "127.0.0.1"
          9) "role"
         10) "master"
         11) "replication-offset"
         12) (integer) 72156
         13) "health"
         14) "online"
      2)  1) "id"
          2) "6daa25c08025a0c7e4cc0d1ab255949ce6cee902"
          3) "port"
          4) (integer) 30005
          5) "ip"
          6) "127.0.0.1"
          7) "endpoint"
          8) "127.0.0.1"
          9) "role"
         10) "replica"
         11) "replication-offset"
         12) (integer) 72156
         13) "health"
         14) "online"
   5) "id"
   6) "0d77234c440a6b05c2d77d1b9f37ac63585fc747"
3) 1) "slots"
   2) 1) (integer) 5461
      2) (integer) 10922
   3) "nodes"
   4) 1)  1) "id"
          2) "a4a3f445ead085eb3eb9ee7d8c644ec4481ec9be"
          3) "port"
          4) (integer) 30002
          5) "ip"
          6) "127.0.0.1"
          7) "endpoint"
          8) "127.0.0.1"
          9) "role"
         10) "master"
         11) "replication-offset"
         12) (integer) 72156
         13) "health"
         14) "online"
      2)  1) "id"
          2) "da6d5847aa019e9b9d2a8aa24a75f856fd3456cc"
          3) "port"
          4) (integer) 30004
          5) "ip"
          6) "127.0.0.1"
          7) "endpoint"
          8) "127.0.0.1"
          9) "role"
         10) "replica"
         11) "replication-offset"
         12) (integer) 72156
         13) "health"
         14) "online"
   5) "id"
   6) "a96f023185ea6d7f5e9a0d6ada6f112741217e6a"

🌟 SEE ALSO 🌟

asking(3valkey), cluster(3valkey), cluster-addslots(3valkey), cluster-addslotsrange(3valkey), cluster-bumpepoch(3valkey), cluster-cancelslotmigrations(3valkey), cluster-count-failure-reports(3valkey), cluster-countkeysinslot(3valkey), cluster-delslots(3valkey), cluster-delslotsrange(3valkey), cluster-failover(3valkey), cluster-flushslots(3valkey), cluster-forget(3valkey), cluster-getkeysinslot(3valkey), cluster-getslotmigrations(3valkey), cluster-help(3valkey), cluster-info(3valkey), cluster-keyslot(3valkey), cluster-links(3valkey), cluster-meet(3valkey), cluster-migrateslots(3valkey), cluster-myid(3valkey), cluster-myshardid(3valkey), cluster-nodes(3valkey), cluster-replicas(3valkey), cluster-replicate(3valkey), cluster-reset(3valkey), cluster-saveconfig(3valkey), cluster-set-config-epoch(3valkey), cluster-setslot(3valkey), cluster-slot-stats(3valkey), cluster-slots(3valkey), cluster-syncslots(3valkey), readonly(3valkey), readwrite(3valkey)

and that's the whole page, bestie 🧚 this one's from 9.0.0, dated 2025-10-21, and it's serving CLUSTER-SHARDS(3valkey) realness. go read your cluster's topology and thrive 💜

📦 where this page comes from