Cluster mode, hash slots and hash tags

Redis Course · lesson 16 of 19 · 6 min read

What breaks when one node becomes many, and how to keep related keys together.

Open this lesson in the learning hub

Key points

  • Cluster splits the keyspace into 16,384 hash slots, and each node owns a range. A key is placed by CRC16 of its name modulo 16384 - deterministic and client-computable.
  • The constraint that surprises people: a multi-key command only works if every key is in the same slot. MGET, SUNION, transactions and Lua scripts all fail across slots.
  • Hash tags are the escape hatch. Only the text inside braces is hashed, so user:{42}:profile and user:{42}:sessions land on the same node and can be used together.
  • Overusing hash tags recreates the problem it solves: forcing too much onto one tag produces a hot slot that cannot be rebalanced, since a slot is the smallest unit that moves.
  • Clients must handle MOVED and ASK redirects during resharding. A good client caches the slot map and refreshes on MOVED; a naive one adds a round trip to every request.
  • Cluster gives sharding, not stronger consistency. Replication is still asynchronous, so a failover can lose recently acknowledged writes - Cluster is for capacity, not durability.

Example

# Which slot, and which node?
> CLUSTER KEYSLOT user:42:profile
(integer) 12182
> CLUSTER KEYSLOT user:42:sessions
(integer) 3941                    # DIFFERENT node - cannot be used together

# CROSSSLOT failure - the most common Cluster surprise:
> MGET user:42:profile user:42:sessions
(error) CROSSSLOT Keys in request don't hash to the same slot

# HASH TAGS: only the braced part is hashed.
> CLUSTER KEYSLOT user:{42}:profile
(integer) 8555
> CLUSTER KEYSLOT user:{42}:sessions
(integer) 8555                    # same slot -> multi-key works

> MGET user:{42}:profile user:{42}:sessions
1) "..."
2) "..."

# But do not over-tag. This puts EVERYTHING on one node:
#   {app}:user:1 ... {app}:user:9999999
#   -> one slot, one node, no rebalancing possible

# Cluster health and slot distribution:
$ redis-cli --cluster check 10.0.0.1:6379
> CLUSTER SHARDS
> CLUSTER COUNTKEYSINSLOT 8555

# Find a hot slot - the thing that cannot be fixed by adding nodes:
$ redis-cli --hotkeys

---
# What still works, and what does not, in Cluster:
#
#   GET / SET / INCR                single key   fine
#   MGET / MSET                     same slot only
#   MULTI / EXEC                    same slot only
#   Lua EVAL                        all KEYS same slot
#   SCAN                            per node - must iterate every node
#   FLUSHALL, KEYS                  per node, and both are dangerous
#   SELECT (databases 1-15)         NOT SUPPORTED at all in Cluster

Multi-key commands need one slot - use hash tags to group related keys, but not so broadly that one slot becomes a hot node.

Where the memory actually goes Where Redis latency comes from

This is a reading copy. The full lesson — with the visual explainer, the interactive lab and a Run button for the code — lives in the Redis Course course, and every lesson in it is listed on the Redis Course contents page.