redis-clustering

Redis Clustering

Guidance for designing keys and routing reads in a sharded Redis Cluster (and in standalone primary/replica replication). Covers the two failure modes that bite most new cluster users: CROSSSLOT errors on multi-key operations, and overloading primaries with read traffic.

When to apply

Designing keys for a Redis Cluster deployment.
Debugging a CROSSSLOT error on MGET, SDIFF, transactions, or pipelines.
Implementing transactions / Lua scripts that touch multiple keys.
Scaling out read traffic without adding shards.

1. Hash tags for multi-key operations

Redis Cluster distributes keys across 16,384 slots by hashing the key name. Any command that touches multiple keys (MGET, SDIFF, SUNIONSTORE, transactions, pipelines, Lua scripts with multiple KEYS[]) requires all keys to live on the same slot — otherwise the server returns a CROSSSLOT error.

Hash tags force this: the part between { and } is the only thing hashed for slot assignment, so two keys sharing a hash tag always land together.

# Same slot — multi-key ops work
redis.set("{user:1001}:profile",  "...")
redis.set("{user:1001}

Rules of thumb:

Use a tag scoped to the meaningful entity, e.g. {user:1001}. Avoid bare {1001} — unrelated namespaces (purchase:{1001}, employee:{1001}) would all collide on the same slot.
Only tag where you actually need multi-key ops. Tagging everything creates hotspots and defeats the point of sharding.
A single-key command on a hash-tagged key works fine, so adding tags later is incremental — but renaming keys in production is painful, so plan tagging up front for entities you'll group.

See references/hash-tags.md.

2. Read replicas for read-heavy workloads

If reads dominate writes, route them to replicas to free primary capacity. Works both in Redis Cluster (each shard has 1+ replica) and in standalone primary/replica replication.

For non-cluster setups, point two clients at the right nodes:

The trade-off is consistency: replicas are eventually consistent. Don't read your own writes from a replica; don't use replica reads for anything that requires strict freshness (financial balances, idempotency state). Good fits: cache layers, analytics, dashboards, recommendation feeds.

See references/read-replicas.md.

References

Redis Clustering

When to apply

Designing keys for a Redis Cluster deployment.

Debugging a CROSSSLOT error on MGET, SDIFF, transactions, or pipelines.

Implementing transactions / Lua scripts that touch multiple keys.

Scaling out read traffic without adding shards.

1. Hash tags for multi-key operations

Hash tags force this: the part between { and } is the only thing hashed for slot assignment, so two keys sharing a hash tag always land together.

# Same slot — multi-key ops work
redis.set("{user:1001}:profile",  "...")
redis.set("{user:1001}

Rules of thumb:

Use a tag scoped to the meaningful entity, e.g. {user:1001}. Avoid bare {1001} — unrelated namespaces (purchase:{1001}, employee:{1001}) would all collide on the same slot.

Only tag where you actually need multi-key ops. Tagging everything creates hotspots and defeats the point of sharding.

A single-key command on a hash-tagged key works fine, so adding tags later is incremental — but renaming keys in production is painful, so plan tagging up front for entities you'll group.

2. Read replicas for read-heavy workloads

If reads dominate writes, route them to replicas to free primary capacity. Works both in Redis Cluster (each shard has 1+ replica) and in standalone primary/replica replication.

For non-cluster setups, point two clients at the right nodes:

References

Documentation

Documentation