CLUSTER-SLOTS(3valkey)

📦

version 9.0.6 · 2 versions

9.0.6 · fedora 44 (latest)
8.1.10 · fedora 43

✨ CLUSTER-SLOTS ✨

okay bestie, welcome to CLUSTER-SLOTS(3valkey) from the Valkey Command Manual — this is the one where you find out which cluster slots live on which nodes. grab a boba, we're going in 💖

💅 NAME

cluster-slots — returns the mapping of cluster slots to nodes.

🌸 SYNOPSIS

CLUSTER SLOTS

🦋 DESCRIPTION

CLUSTER SLOTS spills the tea on which cluster slots map to which Valkey instances. It's literally built for Valkey Cluster client library implementations, so they can fetch (or update, whenever a redirection shows up) the map that ties cluster hash slots to the actual nodes' network info. that way, when a command comes in, the client can yeet it to whatever instance is probably the right one for the keys in that command. main character routing behavior, honestly ✨

The networking information for each node is an array with these elements:

Preferred endpoint (either an IP address, a hostname, or NULL)
Port number
The node ID
A map of additional networking metadata

The preferred endpoint plus the port = the location clients should use to send requests for a given slot. A NULL value for the endpoint means the node has an unknown endpoint, so the client should connect to the same endpoint it used to send the CLUSTER SLOTS command, but with the port returned from the command. This unknown-endpoint config is lowkey a lifesaver when the Valkey nodes sit behind a load balancer whose endpoint Valkey doesn't know about. Which endpoint gets set as preferred is decided by the cluster-preferred-endpoint-type config. An empty string "" is another abnormal value of the endpoint field, and it's also an abnormal value for the ip field — it gets returned when the node doesn't know its own IP address. This can happen in a cluster made of just one node, or when the node hasn't been joined with the rest of the cluster yet. The value ? shows up if the node is incorrectly configured to use announced hostnames but no hostname is configured via cluster-announce-hostname. Clients may treat the empty string the same way as NULL — meaning the same endpoint it used to send the current command to — while "?" should be treated as an unknown node, not necessarily the same node serving the current command. ok noted 📝

Additional networking metadata is provided as a map on the fourth argument for each node. These are the networking metadata fields that may be returned:

IP: when the preferred endpoint is not set to IP.
Hostname: when a node has an announced hostname but the primary endpoint is not set to hostname.

🎀 Nested Result Array

Each nested result is:

Start slot range
End slot range
Primary for slot range, represented as nested networking information
First replica of primary for slot range
Second replica
...continues until all replicas for this primary are returned.

Each result includes all active replicas of the primary instance for the listed slot range. Failed replicas are not returned. 💀

The command response is deterministic across all nodes in a cluster, which means if two nodes return the same response, they have the same view of the cluster. Primaries are ordered by the slots they serve, and then replicas are ordered lexicographically by the node-id they were assigned by the cluster. The third nested reply is guaranteed to be the networking information of the primary instance for the slot range. All networking information after the third nested reply are replicas of the primary. no cap 🫶

If a cluster instance has non-contiguous slots (e.g. 1-400,900,1800-6000), then primary and replica networking information results will be duplicated for each top-level slot range reply. it's giving copy-paste energy but that's just how it is 🙈

> CLUSTER SLOTS
1) 1) (integer) 0
   2) (integer) 5460
   3) 1) "127.0.0.1"
      2) (integer) 30001
      3) "09dbe9720cda62f7865eabc5fd8857c5d2678366"
      4) 1) hostname
         2) "host-1.valkey.example.com"
   4) 1) "127.0.0.1"
      2) (integer) 30004
      3) "821d8ca00d7ccf931ed3ffc7e3db0599d2271abf"
      4) 1) hostname
         2) "host-2.valkey.example.com"
2) 1) (integer) 5461
   2) (integer) 10922
   3) 1) "127.0.0.1"
      2) (integer) 30002
      3) "c9d93d9f2c0c524ff34cc11838c2003d8c29e013"
      4) 1) hostname
         2) "host-3.valkey.example.com"
   4) 1) "127.0.0.1"
      2) (integer) 30005
      3) "faadb3eb99009de4ab72ad6b6ed87634c7ee410f"
      4) 1) hostname
         2) "host-4.valkey.example.com"
3) 1) (integer) 10923
   2) (integer) 16383
   3) 1) "127.0.0.1"
      2) (integer) 30003
      3) "044ec91f325b7595e76dbcb18cc688b6a5b434a1"
      4) 1) hostname
         2) "host-5.valkey.example.com"
   4) 1) "127.0.0.1"
      2) (integer) 30006
      3) "58e6e48d41228013e5d9c1c37c5060693925e97e"
      4) 1) hostname
         2) "host-6.valkey.example.com"

⚠️ Warning: in future versions there could be more elements describing the node better. In general, a client implementation should just rely on the fact that certain parameters are at fixed positions as specified, but more parameters may follow and should be ignored. Similarly, a client library should try, if possible, to cope with the fact that older versions may just have the primary endpoint and port parameter. read this twice, bestie, forward-compatibility is the vibe.

💖 REPLY

valkey-protocol(7) Array reply: nested list of slot ranges with networking information.

⭐ COMPLEXITY

O(N) where N is the total number of Cluster nodes.

👑 ACL CATEGORIES

@slow

🌈 HISTORY

Available since: 3.0.0
Changed in 4.0.0: Added node IDs.
Changed in 7.0.0: Added additional networking metadata field.

and that's the whole page, babe 🫶 this one's from version 9.0.0, dated 2025-10-21 — go forth and route those keys correctly, you absolute icon 💅✨

📦 where this page comes from

fedora 44: valkey-doc 9.0.3-2.fc44 · CC-BY-SA-4.0
fedora 44: valkey-doc 9.0.6-1.fc44 · CC-BY-SA-4.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms