Redis Cluster and replication guidance covering hash tags for multi-key operations, avoiding CROSSSLOT errors, and reading from replicas to scale read-heavy workloads. Use when designing keys for a sharded Redis Cluster, debugging CROSSSLOT errors on MGET / SDIFF / pipelines, configuring a multi-key transaction in a cluster, or routing reads to replicas for caches, analytics, or dashboards.
Permissions
Just instructions. No commands, network, or file access.
Files
Redis Cluster and replication guidance covering hash tags for multi-key operations, avoiding CROSSSLOT errors, and reading from replicas to scale read-heavy workloads. Use when designing keys for a sharded Redis Cluster, debugging CROSSSLOT errors on MGET / SDIFF / pipelines, configuring a multi-key transaction in a cluster, or routing reads to replicas for caches, analytics, or dashboards.
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.
CROSSSLOT error on , , transactions, or pipelines.Version history
MGETSDIFFRedis 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}:settings", "...")
redis.lmove("{user:1001}:pending", "{user:1001}:processed", "LEFT", "RIGHT")
# Different keys, no hash tag — CROSSSLOT on multi-key commands in cluster mode
redis.set("user:1001:profile", "...")
redis.set("user:1001:settings", "...")
pipe = redis.pipeline()
pipe.get("user:1001:profile")
pipe.get("user:1001:settings")
pipe.execute() # CROSSSLOT error in cluster
Rules of thumb:
{user:1001}. Avoid bare {1001} — unrelated namespaces (purchase:{1001}, employee:{1001}) would all collide on the same slot.See references/hash-tags.md.
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.
# Redis Cluster: enable replica reads on the client
from redis.cluster import RedisCluster
rc = RedisCluster(host="localhost", port=6379, read_from_replicas=True)
rc.set("key", "value") # → primary
value = rc.get("key") # → may be served by a replica
For non-cluster setups, point two clients at the right nodes:
primary = Redis(host="primary-host", port=6379)
replica = Redis(host="replica-host", port=6379)
primary.set("key", "value")
value = replica.get("key")
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.
In these kits
Works with
Claude, Codex, Cursor & more