Redis / Advanced: persistence, distribution and operations / Lesson 15

Cluster slots, routing and multi-key design

Design around hash-slot placement and topology-aware clients. Distinguish sharding from replication, same-slot atomic work and managed proxy behavior.

About 4 min readContent reviewed 2026-10-25

On this page

Lesson goals

Explain hash tags, redirections and same-slot requirements.
Evaluate distribution and hot-key tradeoffs before co-locating data.

Cluster distributes slots, not arbitrary pieces of one key

Redis Cluster partitions keys into 16,384 hash slots, each owned by an appropriate primary with replication for availability. It does not split one large key’s internal hash or list automatically across all nodes. A Cluster-aware client uses routing information and handles supported redirection behavior rather than treating one seed as a permanent proxy for every command. Redis Open Source Cluster uses database zero rather than arbitrary SELECT namespaces. Managed Redis products may offer proxy and multi-key semantics that differ, so identify the actual service contract before applying an Open Source Cluster recipe.

Use a hash tag only for a required locality boundary

The local naming example places the same nonempty tag between braces in two keys, making them eligible to hash from the same tagged substring under Cluster’s documented algorithm. It does not compute every edge case of tag parsing or create a cluster. Co-location can allow supported multi-key operations, but putting every tenant or object under one shared tag can concentrate all work on one slot. Choose a small business atomicity boundary, then validate the exact generated names and routing with the actual client and version. Namespace readability and load distribution remain separate concerns.

python Offline shared-tag illustration for two known names

keys = ['lab:{order-17}:items', 'lab:{order-17}:status']
def simple_nonempty_tag(key):
    start = key.index('{') + 1
    end = key.index('}', start)
    return key[start:end]

assert [simple_nonempty_tag(key) for key in keys] == ['order-17', 'order-17']

The helper supports only these controlled nonempty-brace names; it is not a production implementation of Redis key-slot parsing or CRC16.

Same-slot constraints are correctness requirements

In ordinary Redis Open Source Cluster, supported multi-key commands, transactions and scripts generally require all participating keys to be in the same slot. CROSSSLOT is not fixed by increasing a timeout. Refactor the atomicity boundary or deliberately co-locate required keys, without claiming arbitrary cross-shard transactions. A hash tag does not authorize access and can create a hot slot if used too broadly. During resharding, clients must follow documented MOVED and ASK handling; ASK is a temporary routing situation and differs from simply caching a permanent new owner. Use a compatible library rather than handwaving redirections away.

Show a compatible local multi-key shape

These illustrative keys share the order-17 tag, so the stated Cluster slot rule can be satisfied for MGET. The example assumes both keys contain prepared strings and the caller has suitable permissions. Expected results are the string values items-v1 and ready in request order. It neither starts Cluster nor proves failover safety or cross-system consistency. A standalone server may accept other multi-key names that Cluster rejects, so tests must represent the deployment topology rather than assume local development behavior is universal. Avoid over-co-locating unrelated objects just to make this command convenient.

redis Non-runnable same-tag MGET illustration

MGET lab:{order-17}:items lab:{order-17}:status

Expected output

[items-v1, ready]

For the prepared strings, expected logical result is [items-v1, ready]. Key placement and client topology are assumptions to verify independently.

Scaling requires distribution and failure evidence

Adding nodes can distribute slots and memory, but a single hot key or one oversized tag remains concentrated. Measure key/value size, request distribution and command complexity before deciding the topology is the bottleneck. Resharding and failover consume resources and can alter latency or retry paths. Cluster’s asynchronous replication does not guarantee strong consistency or zero acknowledged-write loss. Define routing, retry, persistence and restore requirements together, including what happens when a slot is unavailable. No node creation, slot movement, administrative command or network test is performed by this course.

Common errors and fixes

CROSSSLOT Keys in request don't hash to the same slot

Why it happens: A multi-key operation spans incompatible Cluster slot locations.
How to fix it: Review the atomicity boundary and legitimate shared-tag design.
Prevent it next time: Test multi-key workflows against actual Cluster semantics.

MOVED or ASK is treated as an ordinary permanent connection failure

Why it happens: The client does not implement the required routing protocol.
How to fix it: Use the supported Cluster-aware library and inspect reachability of discovered nodes.
Prevent it next time: Include redirects and topology changes in client acceptance tests.

One shared tag defeats expected distribution

Why it happens: Unrelated data was co-located in a single hash slot.
How to fix it: Revisit tag scope and model migration under review.
Prevent it next time: Assess hotspot and key cardinality before choosing tags.

Check your understanding

1. All cache keys use {all} so multi-key commands always share a slot. What tradeoff was hidden?

Show worked solution

The design can concentrate the whole workload and dataset in one slot, undermining sharding. Co-locate only the keys that genuinely require a shared operation boundary and evaluate their size and traffic. Same-slot convenience does not automatically justify losing distribution or creating a hot node.

2. A two-key script works on a standalone lab but fails in Cluster. Is the script necessarily syntactically wrong?