8. Application Design Patterns
The earlier chapters describe what Redis can do: data types, atomic operations, persistence and replication. This chapter is about putting those parts together into solutions that appear in almost every production system: caches, locks, rate limiters, queues, leaderboards, feeds and data models. Most Redis bugs in real applications do not come from Redis itself. They come from a pattern that is right in the common case and wrong under concurrency, failover or load, so each topic covers both how to build the pattern and where it breaks.
<a id="81-caching-patterns"></a>
8.1 Caching Patterns
This subchapter covers the most common use of Redis: keeping copies of slow-to-compute or slow-to-fetch data in memory. It compares the ways an application can read and write through a cache, how cached data goes stale and is removed, how to stop a single expired key from overloading the database, and how a client can keep its own in-process copy that Redis invalidates for it.
Cache-Aside
A database query that takes 20 ms is fine once and a problem at 10,000 requests per second. Most of those requests ask for the same few rows, and those rows rarely change. A cache keeps the answer in a faster store so that repeated requests skip the slow work. The question is who is responsible for filling the cache and keeping it in step with the database.
In cache-aside (also called lazy loading), the application does everything. Redis is a passive key-value store next to the database, and the application code decides when to read from it, when to fill it and when to clear it. An analogy: a cook keeps the most-used spices on the counter. When a spice is missing, the cook fetches it from the pantry and leaves a jar on the counter for next time. The counter never fetches anything by itself.
Read path
application Redis database
│ GET product:42 │ │
│──────────────────────────────▶│ │
│◀──────── (nil) cache miss ───│ │
│ SELECT ... WHERE id = 42 │
│──────────────────────────────────────────────────────▶│
│◀──────────────────────────────────────── row ─────────│
│ SET product:42 <json> EX 3600 │
│──────────────────────────────▶│ │
│ (next request: GET returns the JSON, database is not touched)
Write path
The safe default is: update the database, then delete the cache key. Deleting is better than writing the new value into the cache for two reasons:
- Two concurrent writers may update the database in one order and the cache in the other order. With
SET, the cache can end up holding the older value until the TTL expires. WithDEL, the next reader loads whatever the database holds. - Many writes are never read before the next write. Deleting avoids computing and serializing a value nobody will use.
Example
import json
import random
import redis
r = redis.Redis(decode_responses=True)
TTL = 3600 # one hour
MISSING = "__none__" # marker for "row does not exist"
def get_product(product_id: int, db) -> dict | None:
key = f"product:{product_id}"
cached = r.get(key)
if cached is not None: # cache hit (including a cached "not found")
return None if cached == MISSING else json.loads(cached)
row = db.fetch_product(product_id) # cache miss: go to the source of truth
if row is None:
r.set(key, MISSING, ex=60) # negative caching: short TTL
return None
ttl = TTL + random.randint(0, 300) # jitter: keys loaded together do not expire together
r.set(key, json.dumps(row), ex=ttl)
return row
def update_product(product_id: int, fields: dict, db) -> None:
db.update_product(product_id, fields) # 1. the database is the source of truth
r.delete(f"product:{product_id}") # 2. invalidate; the next read reloads
The race that remains
Cache-aside with delete-on-write still has one known race. It needs a slow reader and a writer interleaved exactly like this:
reader A writer B
GET product:42 -> miss
SELECT -> old row (v1)
UPDATE row -> v2
DEL product:42
SET product:42 v1 (stale value written after the delete)
The window is small (the reader must be slower than an entire write), and the TTL bounds how long the stale value lives. When that is not good enough, the usual mitigations are a shorter TTL for volatile data, a delayed second delete (delete again a few hundred milliseconds after the write), or storing a version with the value and only writing the cache if the version is newer (a short Lua script that compares versions and writes in one step, chapter 4.4).
Strengths and weaknesses
| Aspect | Cache-aside |
|---|---|
| What gets cached | Only data that is actually requested |
| Redis outage | Reads fall back to the database (slower, but correct) |
| First request after a miss | Pays the full database cost |
| Consistency | Eventual, bounded by the TTL plus the race above |
| Code | Cache logic repeated wherever data is read and written, unless wrapped in a helper |
Key Takeaways
- In cache-aside, the application reads from Redis, falls back to the database on a miss, and fills the cache itself.
- On writes, update the database first, then delete the key. Do not write the new value into the cache.
- Always set a TTL. It is the safety net that bounds every consistency bug.
- Add random jitter to TTLs and cache "not found" results with a short TTL.
- A Redis failure should degrade performance, not correctness: treat cache errors as misses.
Practice
- (Beginner) Implement
get_productabove against a SQLite table. Measure the latency of the first call and of the next 1,000 calls, and checkINFO statsforkeyspace_hitsandkeyspace_misses.- (Intermediate) Reproduce the stale-write race with two threads and a
time.sleepplaced between the reader'sSELECTand itsSET. Then fix it with a version number stored next to the value and a Lua script that only overwrites an older version.- (Interview) "Why do we delete the cache entry after a database update instead of updating it?" Hint: consider two writers whose database commits and cache writes happen in opposite orders, and writes that are never read.
Read-Through and Write-Through
Cache-aside spreads cache logic over the application. Read-through and write-through move that logic into one layer, the cache provider, so that the application talks only to the cache, and the cache talks to the database.
- Read-through: on a miss, the cache itself loads the value from the database through a configured loader, stores it and returns it. The application never queries the database for reads.
- Write-through: on a write, the cache writes to the database synchronously and updates its own copy. The call returns only when both have succeeded.
The analogy is a library front desk. You never go into the stacks yourself: you ask the desk, and the desk either has the book on the shelf behind it or fetches it for you (read-through). When you return a book, the desk puts it back in the stacks before thanking you (write-through).
Where this lives with Redis
Core Redis does not connect to databases. It has no loader hooks, so with Redis "read-through" and "write-through" are implemented by a layer in front of it:
| Layer | Examples |
|---|---|
| A caching abstraction in the application framework | Spring Cache (@Cacheable, @CachePut) with a Redis backend, Django's cache framework, NestJS cache manager |
| A client library with loader support | Redisson's RMapCache with MapLoader and MapWriter (Java) |
| A repository class you write | A ProductRepository that hides both Redis and the database behind one interface |
| A managed ingestion pipeline | Redis Data Integration (RDI), which streams database changes into Redis with change data capture (CDC) |
Example: a small read-through and write-through repository
import json
from typing import Callable
import redis
class ReadWriteThroughCache:
"""The application calls get() and put() only. The cache owns the database calls."""
def __init__(self, r: redis.Redis, prefix: str,
loader: Callable[[str], dict | None],
writer: Callable[[str, dict], None],
ttl: int = 3600):
self.r, self.prefix, self.ttl = r, prefix, ttl
self.loader, self.writer = loader, writer
def get(self, key: str) -> dict | None:
cached = self.r.get(self.prefix + key)
if cached is not None:
return json.loads(cached)
value = self.loader(key) # read-through: the cache loads
if value is not None:
self.r.set(self.prefix + key, json.dumps(value), ex=self.ttl)
return value
def put(self, key: str, value: dict) -> None:
self.writer(key, value) # write-through: database first, synchronously
self.r.set(self.prefix + key, json.dumps(value), ex=self.ttl) # then the cache
# Usage: the application never touches the database directly
products = ReadWriteThroughCache(redis.Redis(decode_responses=True), "product:",
loader=lambda k: db.fetch_product(k),
writer=lambda k, v: db.save_product(k, v))
products.put("42", {"name": "Lamp", "price": 19.9})
print(products.get("42"))
Write-through writes the new value into the cache instead of deleting it. That is acceptable here because all writes go through one layer, but concurrent put calls for the same key can still reach the database and the cache in different orders. Serialize writers per key (a lock, 8.2), or use delete instead of set if the layer is shared by many processes.
Comparison
| Cache-aside | Read-through | Write-through | |
|---|---|---|---|
| Who loads on a miss | Application | Cache layer | (read side unchanged) |
| Who writes the database | Application | Application | Cache layer, synchronously |
| Cache after a write | Key deleted | Key deleted | Key holds the new value |
| Write latency | Database only | Database only | Database + cache |
| Cache holds data nobody reads | No | No | Yes, every written value is cached |
| Typical with Redis | Most common | Framework annotations, libraries | Paired with read-through |
Key Takeaways
- Read-through and write-through put one layer in charge of both cache and database, which removes duplicated cache code.
- Redis has no built-in loaders. The layer is a framework, a client library or your own repository class.
- Write-through keeps the cache warm for recently written data at the cost of slower writes and caching data that may never be read.
- Write-through is still not atomic across two systems: a crash between the database write and the cache write leaves the old value until the TTL expires.
Practice
- (Beginner) Use the class above with a Python dictionary as the "database". Print a message in the loader and check that it runs only once for repeated
getcalls.- (Intermediate) Add Spring Cache (or your framework's equivalent) to a small service with Redis as the backend. Annotate a read method with
@Cacheableand an update method with@CacheEvict, then explain which of the patterns in the table you have built.- (Interview) "Our write-through cache sometimes shows a value older than the database for up to an hour. Writes go through the cache layer. How?" Hint: look for a write path that bypasses the layer (a migration, an admin tool, another service) and for concurrent writes to the same key.
Write-Behind
Write-through makes every write wait for the database. When writes are very frequent, such as view counters, game state or sensor readings, that wait limits throughput, and the database may not keep up at all. Write-behind (also called write-back) changes the order: the application writes to Redis and returns immediately, and a background process later persists the changes to the database, often in batches.
Think of a waiter who writes orders on a notepad and sends them to the kitchen system every few minutes, instead of walking to the terminal after every single item. Service is faster, but if the notepad is lost, those orders are gone.
application ──SET / HINCRBY / XADD──▶ Redis ──(async, batched)──▶ worker ──▶ database
◀─────────── OK (fast) ─────────┘
Design choices
| Decision | Options |
|---|---|
| How changes are recorded | A stream of change events (XADD); or a "dirty set" of keys to flush (SADD dirty k) next to the data itself |
| When to flush | Every N ms, every N changes, or both |
| How to coalesce | Write only the latest value per key, or sum the increments |
| Failure handling | Retry with backoff, park failed batches in a dead-letter stream |
A stream with a consumer group (chapter 3.4) is a good fit: entries survive worker crashes because they stay in the pending entries list until acknowledged, and several workers can share the load.
Example: counters flushed in batches
import sqlite3
import redis
r = redis.Redis(decode_responses=True)
def record_view(article_id: int) -> None:
pipe = r.pipeline() # MULTI/EXEC: both or neither
pipe.hincrby(f"article:{article_id}", "views", 1)
pipe.xadd("changes:articles", {"id": article_id}, maxlen=1_000_000, approximate=True)
pipe.execute() # returns in well under a millisecond
def flush_worker(db: sqlite3.Connection, consumer: str = "w1") -> None:
try:
r.xgroup_create("changes:articles", "db-writer", id="0", mkstream=True)
except redis.ResponseError:
pass # group already exists
while True:
resp = r.xreadgroup("db-writer", consumer, {"changes:articles": ">"},
count=500, block=1000) # up to 500 changes or 1 s
if not resp:
continue
_, entries = resp[0]
ids = {fields["id"] for _, fields in entries} # coalesce: one row per article
rows = [(int(r.hget(f"article:{i}", "views") or 0), int(i)) for i in ids]
db.executemany("UPDATE articles SET views = ? WHERE id = ?", rows)
db.commit() # durable in the database...
r.xack("changes:articles", "db-writer", *[eid for eid, _ in entries]) # ...then ack
The worker writes the current value from Redis instead of replaying each increment. This makes the flush idempotent: if the worker crashes after the commit and before XACK, the entries are redelivered and the same value is written again, which is harmless.
Risks
- Data loss. Anything in Redis and not yet in the database is lost if Redis loses it. Use AOF with
appendfsync everysecoralways(chapter 6.2) and replicas, and size the flush interval to the amount of loss you accept. - Stale database reads. Other systems reading the database see old data until the flush. Reports and joins in SQL are behind Redis.
- Ordering and conflicts. If the database is also written directly, a late flush can overwrite a newer value. Make Redis the only writer for write-behind data, or use version checks in the
UPDATE. - Backlog. If the database is down, the stream grows. Monitor its length and the consumer group's lag (
XINFO GROUPS).
Key Takeaways
- Write-behind acknowledges writes once they are in Redis and persists them later, in batches.
- It gives the highest write throughput and absorbs bursts, at the cost of a window of possible data loss and a database that lags behind.
- Record changes in a stream with a consumer group and acknowledge only after the database commit.
- Make flushes idempotent (write the latest value, not the delta) so redelivery is safe.
Practice
- (Beginner) Run
record_view10,000 times and the worker once. How manyUPDATEstatements were executed? How many stream entries were read?- (Intermediate) Kill the worker with
kill -9betweencommitandxack. Restart it and useXPENDINGandXAUTOCLAIMto recover the pending entries. Verify that the database values are still correct.- (Interview) "Would you use write-behind for a bank account balance? For a 'likes' counter?" Hint: compare the cost of losing the last second of writes with the cost of slow writes in each case.
Cache Invalidation Strategies
"There are only two hard things in computer science: cache invalidation and naming things" (a well-known quote attributed to Phil Karlton). It is hard because a cache is a copy, and every copy goes stale as soon as the original changes. Invalidation is how the copy is removed or refreshed. Each strategy accepts a different amount of staleness for a different amount of complexity.
The strategies
| Strategy | How it works | Staleness | Complexity |
|---|---|---|---|
| TTL only | Every key expires after a fixed time | Up to the TTL | Lowest |
| Explicit delete on write | The writer deletes affected keys after the database write | Small race window (see cache-aside) | Low, but every write path must know which keys to delete |
| Versioned keys | The key name contains a version (product:42:v17); writers bump the version | None for readers that use the new version | Old versions linger until their TTL |
| Namespace / generation keys | A counter (gen:catalog) is part of every key name; incrementing it invalidates the whole group at once | None | One extra read per lookup |
| Event-driven | Database change events (CDC, outbox, PUBLISH) trigger deletes in all services | Delay of the event pipeline | Needs an event pipeline |
| Tag-based | Each cached key is added to sets per tag (tag:category:7); invalidating a tag deletes all members | Small | Sets must be maintained and cleaned up |
Rules of thumb
- Always combine with a TTL. Explicit invalidation fails sometimes (a crashed process, a missed event, a code path someone forgot). The TTL bounds the damage.
- Delete, do not update, on the invalidation path.
- Invalidate everything derived from the change. A product price change may affect
product:42,category:7:page:1andsearch:lamp. Keeping the list of derived keys next to the writer, or using tags, avoids hunting for them. - Avoid
KEYS patternfor invalidation. It blocks the server while scanning the whole keyspace (chapter 2.1). Use tags, generations orSCAN.
Example: generation-based invalidation of a group
import json
import redis
r = redis.Redis(decode_responses=True)
def catalog_key(suffix: str) -> str:
gen = r.get("gen:catalog") or "0" # current generation of the catalog
return f"catalog:{gen}:{suffix}"
def get_category_page(category: int, page: int, db) -> list:
key = catalog_key(f"cat:{category}:p:{page}")
if (cached := r.get(key)) is not None:
return json.loads(cached)
rows = db.list_products(category, page)
r.set(key, json.dumps(rows), ex=600) # old generations simply expire
return rows
def reprice_everything(db) -> None:
db.apply_price_list()
r.incr("gen:catalog") # one command invalidates every catalog key
Example: tag-based invalidation
def cache_with_tags(key: str, value: str, tags: list[str], ttl: int = 600) -> None:
pipe = r.pipeline()
pipe.set(key, value, ex=ttl)
for tag in tags:
pipe.sadd(f"tag:{tag}", key)
pipe.expire(f"tag:{tag}", ttl, nx=True) # new tag set: give it a TTL
pipe.expire(f"tag:{tag}", ttl, gt=True) # existing set: only ever extend it
pipe.execute()
def invalidate_tag(tag: str) -> None:
keys = r.smembers(f"tag:{tag}")
if keys:
r.unlink(*keys, f"tag:{tag}") # UNLINK frees memory in the background
In Redis Cluster, UNLINK with many keys fails with CROSSSLOT unless all keys share a hash tag (chapter 7.3). Delete them one by one in a pipeline instead, or give a tag's keys a common hash tag.
Invalidation across many application instances
When each application server also keeps a small in-process cache, deleting the Redis key is not enough. The usual options are PUBLISH cache-invalidate <key> to all instances (chapter 4.1; fire-and-forget, so combine with a short local TTL), or Redis's built-in client-side caching, covered in the last topic of this subchapter.
Key Takeaways
- There is no perfect strategy, only trade-offs between staleness and complexity. TTL is always the backstop.
- Generation counters invalidate a whole group of keys with one
INCR. Tags invalidate a chosen set of keys. - Never use
KEYSto find keys to invalidate in production. - Remember the derived keys (lists, pages, search results), not only the object's own key.
Practice
- (Beginner) Implement versioned keys for a user profile (
user:7:v3). Where do you store the current version, and what happens touser:7:v2after the update?- (Intermediate) Implement tag-based invalidation for product pages and category pages. Change one product's category and list every key that must be invalidated.
- (Interview) "Our service caches user permissions for 10 minutes. Security asks that a revoked permission take effect within 1 second. What do you change?" Hint: a shorter TTL is not enough on its own. Think of event-driven invalidation and of what happens when the event is lost.
Cache Stampede Prevention
A popular key expires. In the next 50 ms, 2,000 requests miss the cache at the same moment, and all of them run the same expensive database query to rebuild it. The database slows down, the query takes longer, more requests pile up, and the system can collapse. This is a cache stampede (also called dog-piling or the thundering herd). It is the cache's success turning against it: the more a key is used, the worse its expiry hurts.
time ──▶ key expires
│
requests ─ hit ─ hit ┼ miss miss miss miss miss miss ... (all go to the database)
database idle ┼██████████████████████████████████ overload
Related failure modes
| Name | Cause | Main defense |
|---|---|---|
| Stampede (breakdown) | One hot key expires; many concurrent misses rebuild it | Single-flight lock, early refresh |
| Avalanche | Many keys expire at the same time (loaded together, same TTL) or Redis restarts empty | TTL jitter, warm-up, gradual traffic ramp |
| Penetration | Requests for keys that never exist always miss and always hit the database | Negative caching, Bloom filter (chapter 3.2) |
Defense 1: single flight with a lock
Only the first request that misses rebuilds the value. The others wait briefly and read the result.
import time
import uuid
import redis
r = redis.Redis(decode_responses=True)
def get_single_flight(key: str, load, ttl: int = 300, lock_ttl_ms: int = 5000):
value = r.get(key)
if value is not None:
return value
token = uuid.uuid4().hex
if r.set(f"lock:{key}", token, nx=True, px=lock_ttl_ms): # I rebuild
try:
value = load()
r.set(key, value, ex=ttl)
return value
finally:
r.delex(f"lock:{key}", ifeq=token) # release only my own lock (Redis 8.4+, see 8.2)
for _ in range(50): # others: wait up to ~2.5 s for the result
time.sleep(0.05)
value = r.get(key)
if value is not None:
return value
return load() # give up waiting: fall back (or serve an error)
In a test with 20 threads requesting the same missing key against Redis 8.10, the loader ran exactly once. Without the lock it ran 20 times.
Defense 2: refresh before expiry
Instead of waiting for the key to expire, refresh it a little early.
- Logical expiry (stale-while-revalidate): store the value with a "soft" expiry time inside it and a longer real TTL. A reader that sees the soft expiry has passed takes the lock and refreshes in the background, while all readers keep getting the slightly stale value. No reader waits.
- Probabilistic early expiration (XFetch): each reader decides at random to refresh early, with a probability that grows as the expiry approaches and with how long the recomputation takes. The chance that many readers refresh at once is very small, and no lock is needed. The formula comes from Vattani, Chierichetti and Lowenstein, Optimal Probabilistic Cache Stampede Prevention (VLDB 2015).
import math
import random
import time
def xfetch_get(key: str, recompute, ttl: int = 60, beta: float = 1.0) -> str:
data = r.hgetall(key) # {"value", "delta", "expiry"}
now = time.time()
if data:
delta, expiry = float(data["delta"]), float(data["expiry"])
# log(random()) is negative, so this moves "now" forward by a random amount
# proportional to delta (recompute time). Larger beta = earlier refresh.
if now - delta * beta * math.log(random.random()) < expiry:
return data["value"] # not refreshing this time
start = time.time()
value = recompute()
delta = time.time() - start # how long a rebuild takes
pipe = r.pipeline()
pipe.hset(key, mapping={"value": value, "delta": delta, "expiry": now + ttl})
pipe.expire(key, ttl)
pipe.execute()
return value
Defense 3: other measures
- TTL jitter, as in the cache-aside example, against avalanches.
- Warm-up after a deploy or a Redis restart: preload the hottest keys before sending traffic, or ramp traffic up gradually (chapter 6.3 discusses cold starts).
- Request coalescing in the process: inside one application server, let concurrent requests for the same key share one in-flight future. This reduces the problem from "requests" to "servers" without touching Redis.
- Never expire truly hot keys and refresh them from a scheduled job instead.
Key Takeaways
- A stampede happens when a hot key expires and many requests rebuild it at once. An avalanche is many keys expiring together. Penetration is misses on keys that do not exist.
- A short lock (
SET NX PX) lets exactly one request rebuild while others wait or serve stale data. - Refreshing before expiry, with logical expiry or XFetch, avoids the miss entirely.
- TTL jitter, warm-up and negative caching handle the related failure modes.
Practice
- (Beginner) Simulate a stampede: 50 threads call a cache-aside function on the same key, with a loader that sleeps 200 ms and counts calls. Then switch to
get_single_flightand compare the counts.- (Intermediate) Implement stale-while-revalidate: store
{"value", "soft_expiry"}as JSON with a real TTL 5 times longer than the soft one, and refresh in a background thread when the soft expiry has passed.- (Interview) "After a Redis failover, our database CPU goes to 100% for ten minutes. Why, and how do you prevent it?" Hint: what does the new primary contain if replication was healthy, and what if the cache was rebuilt from an empty node? Consider avalanches and warm-up.
Client-Side Caching and Tracking
A Redis round trip takes about 0.1 to 1 ms on a good network. For a value read thousands of times per second by the same application server, even that adds up, and some keys are so hot that they overload a single Redis node (a hot key, 8.4). The fastest cache is the process's own memory. The difficulty is the usual one: how does each application server learn that its local copy is stale?
Client-side caching with tracking (Redis 6.0+) solves this inside Redis. The client tells the server "remember which keys I read". When any client modifies one of those keys, the server sends this client an invalidation message, and the client drops its local copy. The analogy is a magazine subscription with a recall notice: you keep a copy at home, and the publisher tells you when a page has changed.
app server A (local cache) Redis app server B
│ CLIENT TRACKING ON │ │
│─────────────────────────────────────▶│ │
│ GET product:1 -> "v1" (cache it) │ remembers: A read product:1│
│─────────────────────────────────────▶│ │
│ GET product:1 (served locally, no network) │
│ │◀──────── SET product:1 v2 ──│
│◀──── push: invalidate [product:1] ───│ │
│ (local copy dropped; next GET goes to Redis) │
Modes
| Mode | Command | What the server remembers | Invalidations sent |
|---|---|---|---|
| Default | CLIENT TRACKING ON | Every key each client read, in an invalidation table | Only for keys the client actually read |
| Opt-in | CLIENT TRACKING ON OPTIN, then CLIENT CACHING YES before a read | Only keys read right after CLIENT CACHING YES | Only for those keys |
| Opt-out | CLIENT TRACKING ON OPTOUT, then CLIENT CACHING NO to skip a read | All keys except those excluded | As default |
| Broadcasting | CLIENT TRACKING ON BCAST PREFIX user: PREFIX product: | Nothing per client, only the prefixes | For every change to any key matching the prefixes |
Further options:
NOLOOP: do not send the client invalidations for keys it modified itself.REDIRECT <client-id>: send invalidations to another connection. With RESP2 this is required, because RESP2 cannot mix push messages with replies. The other connection subscribes to the__redis__:invalidatechannel. With RESP3 (HELLO 3), invalidations arrive as push messages on the same connection.
The server's invalidation table has a size limit, tracking-table-max-keys (default 1,000,000 in Redis 8.10). When it is full, the server evicts entries and sends invalidations for them, even though they did not change, so the client stays correct. Keys are also invalidated when they expire, are evicted, or by FLUSHALL / FLUSHDB (an invalidation with a null key list, meaning "drop everything").
Raw protocol view
Captured on Redis 8.10 with a RESP3 connection, after another client ran SET product:1 v3:
> HELLO 3
> CLIENT TRACKING ON
+OK
> GET product:1
$2
v2
(another client: SET product:1 v3)
>2 <- push message with 2 elements
$10
invalidate
*1
$9
product:1 <- the key to drop from the local cache
Using it from a client library
You rarely handle push messages yourself. Several official clients have built-in support: redis-py (cache_config), Jedis and Lettuce (Java), and node-redis.
import redis
from redis.cache import CacheConfig
# protocol=3 is required: invalidations arrive as RESP3 push messages
r = redis.Redis(host="localhost", protocol=3,
cache_config=CacheConfig(max_size=10_000), # local LRU of 10k entries
decode_responses=True)
for _ in range(1000):
r.get("product:1") # first call goes to Redis, the rest are served locally
With redis-py 8.1 against Redis 8.10, 1,000 calls to r.get("product:1") produced one GET on the server (cmdstat_get:calls=1 in INFO commandstats). After another client changed the key, the next get returned the new value.
When to use which mode
| Situation | Mode |
|---|---|
| Each server reads a different subset of many keys | Default (server tracks per client) |
| Only a few known-hot keys are worth caching locally | Opt-in |
| Small, well-defined key families read by every server (feature flags, configuration) | Broadcasting with prefixes, which uses no server memory per key |
Limits
- Local caches use application memory. Bound them (LRU, maximum size) and only cache small, hot, read-mostly values.
- A connection that drops loses its invalidations. The client must clear its whole local cache on reconnect, which good libraries do.
- Broadcasting sends a message for every change under a prefix, even for keys the client never read, so it is wasteful for write-heavy prefixes.
- In a cluster, each node tracks only its own keys, so the client needs tracking on every node connection.
Key Takeaways
- Client-side caching keeps hot values in the application's memory, with Redis sending invalidations when they change.
- Use RESP3 so that invalidations arrive on the same connection. With RESP2, use
REDIRECTand the__redis__:invalidatechannel. - Default mode tracks keys per client. Broadcasting tracks prefixes and costs no server memory per key, but sends more messages.
- Clear the local cache on reconnect and keep it bounded.
Practice
- (Beginner) Open two
redis-cli -3sessions. In the first, runCLIENT TRACKING ONandGET k. In the second, runSET k 2. Observe the push message in the first session (you may need to press Enter or run another command to see it).- (Intermediate) Use broadcasting mode with
PREFIX flag:to build a feature-flag cache in Python that never asks Redis for a flag unless it was invalidated. Measure the request rate on the server withINFO commandstats.- (Interview) "Why can't a client simply subscribe to keyspace notifications to implement client-side caching? What does tracking add?" Hint: compare who gets notified (everyone vs only clients that read the key), the ordering of the invalidation relative to the read reply, and what happens on disconnect.
<a id="82-coordination-patterns"></a>
8.2 Coordination Patterns
This subchapter covers how many processes on many machines use Redis to agree on something: who may do a piece of work (locks and semaphores), how often a client may act (rate limiting), and whether a request was already handled (idempotency keys). All of these patterns rely on Redis executing each command, transaction or script atomically (chapter 5.1). Each is also limited by Redis being a single, asynchronously replicated server, so this subchapter is precise about what each pattern guarantees and what it does not.
Distributed Locks with SET NX
Two workers pick up the same "charge invoice 77" job, and the customer is charged twice. Inside one process, a mutex prevents this. Across processes and machines there is no shared memory, so the mutex has to live somewhere all of them can reach. Redis is a common choice because one command can create a key only if it does not exist and give it an expiry, atomically.
The lock is a key. Whoever creates it holds the lock. The analogy is a meeting room with a single key on a hook: whoever takes the key may use the room, and a timer makes the key return to the hook by itself if the holder never comes back.
The three parts of a correct lock
| Step | Command | Why it must be like this |
|---|---|---|
| Acquire | SET lock:<res> <token> NX PX <ttl> | NX makes it exclusive, PX makes a crashed holder release it eventually, and one command makes both atomic. SETNX followed by EXPIRE is wrong: a crash between them leaves a lock that never expires |
| Token | A random value unique to this holder (UUID) | Lets the holder prove ownership when releasing or extending |
| Release | Delete only if the value is still my token | Plain DEL can delete a lock that expired and was taken by someone else |
Why the token matters:
worker A worker B
SET lock NX PX 10000 -> OK
(long GC pause: 12 s)
lock expires
SET lock NX PX 10000 -> OK
DEL lock <- deletes B's lock!
(B thinks it is still protected)
worker C acquires the lock too
Example
Redis 8.4 added DELEX key IFEQ value (delete if the value equals) and SET ... IFEQ value (write if the value equals). They make release and extension single commands. On older servers and on Valkey, use the Lua scripts shown afterwards.
127.0.0.1:6379> SET lock:invoice:77 tokA NX PX 30000
OK
127.0.0.1:6379> SET lock:invoice:77 tokB NX PX 30000
(nil) <- someone else holds it
127.0.0.1:6379> SET lock:invoice:77 tokA IFEQ tokA PX 60000
OK <- extended: still mine
127.0.0.1:6379> DELEX lock:invoice:77 IFEQ tokB
(integer) 0 <- not B's lock: nothing deleted
127.0.0.1:6379> DELEX lock:invoice:77 IFEQ tokA
(integer) 1 <- released by its owner
import uuid
import redis
r = redis.Redis(decode_responses=True)
# Portable release and extension (any Redis version, Valkey)
RELEASE = r.register_script("""
if redis.call('GET', KEYS[1]) == ARGV[1] then
return redis.call('DEL', KEYS[1])
end
return 0
""")
EXTEND = r.register_script("""
if redis.call('GET', KEYS[1]) == ARGV[1] then
return redis.call('PEXPIRE', KEYS[1], ARGV[2])
end
return 0
""")
class RedisLock:
def __init__(self, resource: str, ttl_ms: int = 10_000):
self.key, self.ttl_ms = f"lock:{resource}", ttl_ms
self.token = uuid.uuid4().hex # unique per acquisition
def acquire(self) -> bool:
return bool(r.set(self.key, self.token, nx=True, px=self.ttl_ms))
def extend(self) -> bool: # call periodically for long work
return EXTEND(keys=[self.key], args=[self.token, self.ttl_ms]) == 1
def release(self) -> bool:
return RELEASE(keys=[self.key], args=[self.token]) == 1
lock = RedisLock("invoice:77")
if lock.acquire():
try:
charge_invoice(77) # critical section
finally:
lock.release()
else:
print("another worker is charging invoice 77")
With redis-py 8.1 and Redis 8.4+, r.delex(key, ifeq=token) and r.set(key, token, ifeq=token, px=ttl) replace the two scripts. redis-py marks them as experimental, so the scripts are still the safer choice for portable code.
Choosing the TTL and waiting for a lock
- The TTL must be longer than the critical section normally takes. For work of unknown length, use a short TTL and a background "watchdog" thread that calls
extend()every TTL/3, which is what Redisson does in Java. - To wait for a lock, retry with a short random sleep (for example 50 to 150 ms) and a deadline. Fixed sleeps make waiters retry in lockstep.
What a single-instance lock does not guarantee
- Expiry during a pause. If the holder stops (garbage collection, swapping, a VM migration) for longer than the TTL, the lock expires and someone else gets it, while the first holder still believes it holds it. No lock with automatic expiry can prevent this alone.
- Failover. Replication is asynchronous (chapter 7.1). The primary can acknowledge the
SET, crash before replicating it, and a promoted replica will not contain the lock.WAIT 1 100after acquiring narrows the window but does not close it.
The defense against both is a fencing token: a number that increases with every acquisition, which the protected resource checks.
worker A: acquires lock, gets token 33 ── pause ──────────────── write(token=33) -> REJECTED
worker B: acquires lock, gets token 34 ── write(token=34) -> OK
storage remembers "highest = 34"
FENCED_ACQUIRE = r.register_script("""
if redis.call('SET', KEYS[1], ARGV[1], 'NX', 'PX', ARGV[2]) then
return redis.call('INCR', KEYS[2]) -- the fencing token, strictly increasing
end
return false
""")
# Hash tags keep both keys in one slot on a cluster (chapter 7.3)
token = FENCED_ACQUIRE(keys=["lock:{acct:1}", "fence:{acct:1}"], args=[uuid.uuid4().hex, 10_000])
# The storage then accepts a write only if token > the last token it saw, e.g. in SQL:
# UPDATE accounts SET balance = ?, fence = ? WHERE id = 1 AND fence < ?
The fencing token only helps if the resource checks it. When it can, the database's own check is what guarantees safety, and the Redis lock is an efficiency measure that avoids wasted work.
Efficiency locks and correctness locks
| Purpose | Consequence of two holders | Recommendation |
|---|---|---|
| Efficiency: avoid doing the same work twice (rebuild a cache, send a daily report) | Some duplicated work | A single Redis instance with SET NX PX is a good fit |
| Correctness: two holders corrupt data or move money twice | Data corruption | Use fencing tokens checked by the resource, or a consensus system (ZooKeeper, etcd) or the database's own locks and constraints |
Key Takeaways
- Acquire with one
SET key token NX PX ttl. Never useSETNX+EXPIRE. - Release and extend only if the value is still your token:
DELEX ... IFEQ/SET ... IFEQon Redis 8.4+, a Lua script elsewhere. - Locks with TTLs can be held by two processes after a pause or a failover. Fencing tokens checked by the resource make this safe.
- Redis locks are excellent for efficiency. For correctness, rely on the resource's own checks.
Practice
- (Beginner) In
redis-cli, acquirelock:demowith a 5-second TTL, try to acquire it from a second session, wait 5 seconds and try again. Then show whyDELwithout a token check is dangerous by replaying the timeline above.- (Intermediate) Add a watchdog thread to
RedisLockthat extends the lock everyttl/3and stops when the lock is released or an extension fails. What should the main thread do when an extension fails?- (Interview) "Our lock uses
SET NX PXon a primary with a replica and Sentinel. Under what sequence of events can two workers hold the lock at once?" Hint: consider asynchronous replication during a failover, and a long process pause, separately.
Redlock Algorithm and Critiques
A lock on one Redis primary is lost if that primary fails before replicating it. Redlock, proposed by Redis's creator Salvatore Sanfilippo (antirez), tries to remove this single point of failure without replication: it acquires the same lock on several independent Redis primaries (no replication between them) and considers it held only if a majority agreed.
The algorithm (with N = 5 independent primaries)
- Record the current time
t1in milliseconds. - Try
SET lock token NX PX ttlon each of the N instances in turn (or in parallel), with a per-instance timeout much shorter than the TTL (for example 5 to 50 ms for a 10 s TTL), so a dead node does not stall the attempt. - Record
t2. The lock is acquired only if at least N/2 + 1 instances (3 of 5) accepted it and the elapsed timet2 - t1is less than the TTL. - The lock's remaining validity time is
ttl - (t2 - t1) - drift, wheredriftis a small allowance for clock drift between machines. The holder must finish within this time. - If acquisition failed, release the lock on all instances (including those that seemed to fail, because a reply may have been lost), and retry after a random delay.
- To release, run the token-checked delete on all instances.
client ──SET NX PX──▶ R1 OK
──SET NX PX──▶ R2 OK
──SET NX PX──▶ R3 (timeout)
──SET NX PX──▶ R4 OK 3 of 5 within the TTL: lock held,
──SET NX PX──▶ R5 (held by another) validity = ttl - elapsed - drift
Instances that crash and restart can break safety if they lose the lock key (no persistence or appendfsync everysec). The algorithm's description therefore recommends delayed restarts: keep a crashed node out of service for at least the maximum lock TTL.
The critique
In 2016, Martin Kleppmann published How to do distributed locking, arguing that Redlock is unsafe for correctness. Sanfilippo replied in Is Redlock safe?. The main points:
| Kleppmann's argument | Sanfilippo's response |
|---|---|
| Redlock depends on timing assumptions: bounded network delay, bounded process pauses and bounded clock drift. A GC pause or a clock jump after acquisition lets two clients hold the lock | The check of elapsed time after acquisition covers delays during acquisition. Pauses after it affect every lock with automatic release, not only Redlock. Clocks should be monotonic and not stepped by administrators or NTP jumps |
| Redlock has no fencing tokens, so the resource cannot reject a stale holder | A random unique token can be used with a compare-and-set on the resource; if the resource can do that, it may not need a distributed lock at all |
| For efficiency a single Redis is enough; for correctness use a consensus system (ZooKeeper, etcd) with fencing. Redlock is too heavy for the first and too weak for the second | Redlock is meant for cases where a single instance's failover risk is unacceptable and a consensus system is not available |
The debate did not produce a winner, but it produced a widely accepted practical conclusion:
- For efficiency locks, a single Redis instance (with replication for availability) is simpler and good enough. Redlock adds cost for little benefit.
- For correctness, no lock with automatic expiry is safe on its own. The resource must reject stale holders (fencing, conditional writes, unique constraints), and then the lock mechanism matters much less.
- Some libraries reflect this. Redisson, for example, has deprecated its Redlock object in favor of its regular lock and a fenced lock.
When Redlock still appears
You will meet Redlock in libraries such as node-redlock and in interview questions. Use it only if you understand its assumptions: independent primaries (not a cluster, not replicas of each other), synchronized monotonic clocks, delayed restarts, and validity checks before every protected action.
Key Takeaways
- Redlock acquires the lock on a majority of N independent primaries within the TTL. The remaining validity time is TTL minus the elapsed time minus a drift allowance.
- Its safety depends on timing assumptions (pauses, network delay, clock drift) and on nodes not losing locks across restarts.
- Kleppmann's critique: no fencing tokens and reliance on timing make it unsuitable for correctness. Use consensus systems and fencing for that.
- In practice: single-instance locks for efficiency, fencing or database constraints for correctness.
Practice
- (Beginner) With a 10,000 ms TTL, 5 instances, an acquisition that took 120 ms and a drift allowance of 1% of the TTL plus 2 ms, compute the validity time. Is the lock acquired if only 2 instances accepted?
- (Intermediate) Start five Redis containers and implement Redlock acquisition and release in Python. Kill one container during acquisition and check that the lock is still acquired. Kill three and check that it is not, and that the partial locks are released.
- (Interview) "Explain a scenario where Redlock lets two clients believe they hold the lock at the same time." Hint: consider a client pausing between acquisition and use, and a node restarting without persistence after granting the lock.
Rate Limiting (Fixed Window, Sliding Window, Token Bucket)
An API that anyone can call as fast as they like will eventually be overwhelmed: by a misbehaving script, a scraper, a brute-force login attempt or one big customer. A rate limiter caps how many actions a client (a user, API key or IP address) may perform per unit of time. With many application servers, the counters must be shared, and Redis is a natural place for them because increments are atomic and keys can expire by themselves.
Algorithms at a glance
| Algorithm | Idea | Redis structure | Memory per client | Accuracy |
|---|---|---|---|---|
| Fixed window | Count requests per calendar window (for example per minute) | String counter with a TTL | 1 small key | Up to 2x the limit across a window boundary |
| Sliding window log | Keep a timestamp per request; count those in the last N seconds | Sorted set | One entry per request in the window | Exact |
| Sliding window counter | Weight the previous window's count by how much of it overlaps the sliding window | Two counters | 2 small keys | Close approximation |
| Token bucket | A bucket refills at a steady rate; each request takes a token | Hash (tokens, last refill time) + Lua | 1 small key | Exact; allows controlled bursts |
Fixed window
import time
import redis
r = redis.Redis(decode_responses=True)
def allow_fixed(client: str, limit: int = 100, window: int = 60) -> bool:
key = f"rl:{client}:{int(time.time()) // window}" # one key per window
pipe = r.pipeline() # MULTI/EXEC
pipe.incr(key)
pipe.expire(key, window, nx=True) # set TTL only on creation (Redis 7.0+)
count, _ = pipe.execute()
return count <= limit
Redis 8.8 added INCREX, which increments, applies a bound and sets the TTL in one command. The reply is [value, applied increment], and an increment rejected at the upper bound returns 0 as the second element:
127.0.0.1:6379> INCREX rl:user:1 BYINT 1 UBOUND 5 EX 60 ENX
1) (integer) 1
2) (integer) 1 <- applied: request allowed
... (four more calls)
127.0.0.1:6379> INCREX rl:user:1 BYINT 1 UBOUND 5 EX 60 ENX
1) (integer) 5
2) (integer) 0 <- rejected: limit of 5 reached, counter unchanged
ENX sets the expiry only if the key has none, so the window does not slide forward on every call.
The weakness of fixed windows is the boundary:
limit 100/min window 10:00 window 10:01
├──────────────────────────────┼──────────────────────────────┤
requests 100 at 10:00:59 │ 100 at 10:01:00
└── 200 requests in about 1 second ──┘
Sliding window log
Store each request's timestamp in a sorted set, remove those older than the window, and count the rest. This needs a script so that "count, then add" is atomic:
import uuid
SLIDING_LOG = r.register_script("""
local key, now, window, limit = KEYS[1], tonumber(ARGV[1]), tonumber(ARGV[2]), tonumber(ARGV[3])
redis.call('ZREMRANGEBYSCORE', key, '-inf', now - window) -- drop requests outside the window
if redis.call('ZCARD', key) >= limit then
return 0 -- over the limit: do not record
end
redis.call('ZADD', key, now, ARGV[4]) -- member must be unique per request
redis.call('PEXPIRE', key, window)
return 1
""")
def allow_sliding_log(client: str, limit: int = 100, window_ms: int = 60_000) -> bool:
now = int(time.time() * 1000)
member = f"{now}-{uuid.uuid4().hex[:8]}" # two requests in the same ms stay distinct
return SLIDING_LOG(keys=[f"rl:log:{client}"], args=[now, window_ms, limit, member]) == 1
It is exact, but memory grows with the limit: a limit of 10,000 requests per hour stores up to 10,000 members per client.
Sliding window counter
Keep the fixed-window counters, but estimate the sliding window as the current count plus the previous window's count weighted by how much of it still overlaps:
estimate = previous_count × (1 − elapsed_fraction_of_current_window) + current_count
example: limit 100/min, 15 s into the current minute (elapsed 0.25),
previous minute 80, current minute 30 → 80 × 0.75 + 30 = 90 → allowed
def allow_sliding_counter(client: str, limit: int = 100, window: int = 60) -> bool:
now = time.time()
current = int(now // window)
elapsed = (now % window) / window
k_cur, k_prev = f"rl:sc:{client}:{current}", f"rl:sc:{client}:{current - 1}"
prev, curr = r.mget(k_prev, k_cur)
if int(prev or 0) * (1 - elapsed) + int(curr or 0) >= limit:
return False
pipe = r.pipeline()
pipe.incr(k_cur)
pipe.expire(k_cur, window * 2) # still needed as "previous" next window
pipe.execute()
return True
The read and the increment are separate here, so concurrent requests can exceed the limit slightly. Move the logic into a Lua script if that matters. In a cluster, give both keys a hash tag (rl:sc:{client}:...).
Token bucket
A bucket holds up to capacity tokens and refills at rate tokens per second. Each request removes one token (or cost tokens for expensive operations). An idle client accumulates tokens up to the capacity and can then burst. This is the most flexible algorithm and the one used by many API gateways.
TOKEN_BUCKET = r.register_script("""
local key = KEYS[1]
local capacity = tonumber(ARGV[1])
local rate = tonumber(ARGV[2]) -- tokens per second
local cost = tonumber(ARGV[3])
local t = redis.call('TIME') -- server clock: all app servers agree
local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)
local state = redis.call('HMGET', key, 'tokens', 'ts')
local tokens = tonumber(state[1]) or capacity -- new client: full bucket
local ts = tonumber(state[2]) or now
tokens = math.min(capacity, tokens + (now - ts) * rate / 1000) -- refill since last call
local allowed = 0
if tokens >= cost then
tokens = tokens - cost
allowed = 1
end
redis.call('HSET', key, 'tokens', tokens, 'ts', now)
redis.call('PEXPIRE', key, math.ceil(capacity / rate * 1000)) -- full again by then: key unneeded
return {allowed, tostring(tokens)} -- tostring: Lua numbers become integers in replies
""")
def allow_token_bucket(client: str, capacity: int = 10, rate: float = 2, cost: int = 1):
allowed, tokens = TOKEN_BUCKET(keys=[f"rl:tb:{client}"], args=[capacity, rate, cost])
return allowed == 1, float(tokens)
A run against Redis 8.10 with capacity=5, rate=2: seven immediate calls gave five allowed and two rejected. One second later, about two tokens had refilled and the next call was allowed.
Practical details
- Return HTTP
429 Too Many Requestswith aRetry-Afterheader, and optionallyRateLimit-*headers so clients can slow down. - Decide what happens if Redis is unreachable: fail open (allow, protecting availability) or fail closed (deny, protecting the backend). Login and payment endpoints usually fail closed.
- Use the server's clock (
TIMEin scripts) or one source of time, not each application server's clock. - Limits can be layered: per IP, per user, per endpoint and globally.
Key Takeaways
- Fixed window is simplest (one
INCR+EXPIRE NX, orINCREXon 8.8+) but allows bursts of up to 2x at window boundaries. - Sliding window log is exact but stores one sorted-set member per request.
- Sliding window counter approximates a sliding window with two counters.
- Token bucket allows controlled bursts and weighted costs, and needs a Lua script for atomic refill-and-take.
- Every read-then-write limiter must be atomic (Lua,
INCREX), or concurrent requests slip through.
Practice
- (Beginner) Implement
allow_fixedand call it 120 times in a loop with a limit of 100 per minute. Then run two processes at the same time and check that the combined count is still limited.- (Intermediate) Rewrite
allow_sliding_counteras a single Lua script. Fire 1,000 concurrent requests with a limit of 100 using threads, and compare how many are allowed with the script and with the Python version.- (Interview) "Design rate limiting for a public API: 1,000 requests per hour per API key, with short bursts of up to 50 requests allowed, running on 30 application servers." Hint: choose the algorithm that supports bursts, decide on the key design, the behavior when Redis is down, and how clients learn when to retry.
Idempotency Keys
Networks fail in the worst place: after the server has done the work and before the client receives the answer. The client times out and retries, and a payment is made twice, an order created twice, an email sent twice. Idempotency means that repeating an operation has the same effect as doing it once. An idempotency key is a unique ID the client sends with a request (often in an Idempotency-Key HTTP header). The server records that ID with the result, and a retry with the same ID gets the stored result instead of running the operation again.
An analogy: a numbered cloakroom ticket. Showing the same ticket twice gets you the same coat, not two coats.
Flow
client server Redis
│ POST /payments Idempotency-Key: k1 │ │
│───────────────────────────────────────▶│ SET idem:k1 processing NX EX 60 │
│ │──────────────────────────────────────▶│ OK (first time)
│ │ charge card ... result R │
│ │ SET idem:k1 {done, R} EX 86400 │
│ (response lost, client times out) │──────────────────────────────────────▶│
│ POST /payments Idempotency-Key: k1 │ │
│───────────────────────────────────────▶│ SET idem:k1 ... NX -> nil (exists) │
│ │ GET idem:k1 -> {done, R} │
│◀──────────────── R (same as before) ───│ │
States
| Key state | Meaning | Response to a retry |
|---|---|---|
| Absent | Never seen | Claim it and run the operation |
processing | Another attempt is running now | 409 Conflict (or wait and poll) |
done + stored result | Completed | Return the stored result |
| (claim expired) | The first attempt crashed mid-way | Can be claimed again: the operation must be safe to resume |
Example
import json
import redis
r = redis.Redis(decode_responses=True)
class InProgress(Exception):
pass
def idempotent(key: str, operation, claim_ttl: int = 60, result_ttl: int = 86_400):
rkey = f"idem:{key}"
if r.set(rkey, json.dumps({"state": "processing"}), nx=True, ex=claim_ttl):
try:
result = operation()
except Exception:
r.delete(rkey) # failed: allow a clean retry
raise
r.set(rkey, json.dumps({"state": "done", "result": result}), ex=result_ttl)
return result
record = json.loads(r.get(rkey) or '{"state": "processing"}')
if record["state"] == "done":
return record["result"] # replay the original answer
raise InProgress(key) # map to HTTP 409
charges = []
def charge():
charges.append(1)
return {"charge_id": "ch_1", "amount": 1999}
print(idempotent("order-981-pay", charge)) # executes
print(idempotent("order-981-pay", charge)) # replays, does not execute
print(len(charges)) # 1
Design details
- Scope the key to the caller (
idem:<api_key>:<idempotency_key>), so two customers cannot collide or read each other's results. - Check the request body. Store a hash of the request with the key and reject a retry with the same key but a different body (
422); it is a client bug. - Claim TTL vs work duration. If the operation can outlive
claim_ttl, a retry may start a second execution. Keep the claim TTL above the worst-case duration, or extend it while working (like a lock). - Redis is not the final guard for money. If Redis loses the key (failover, eviction), a retry runs again. For critical operations, also enforce uniqueness in the system of record, for example a unique constraint on
(customer, idempotency_key)in the payments table, and pass the key to downstream providers that support idempotency. - Use
noevictionor avolatile-*policy on the instance holding idempotency keys, so they are not evicted early (chapter 5.3).
Two related Redis features are covered elsewhere: idempotent stream producers with XADD ... IDMP (Redis 8.6+, chapter 3.4), and the fact that retrying a non-idempotent command such as INCR after a timeout can apply it twice (chapter 7.2).
Key Takeaways
- An idempotency key turns "at least once" retries into "effectively once" processing.
- Claim the key atomically with
SET ... NX EX, then store the result for replay. - Distinguish "in progress" from "done", scope keys per client, and verify that retries carry the same request.
- For critical operations, back Redis with a uniqueness constraint in the system of record.
Practice
- (Beginner) Run the example, then run
TTL idem:order-981-payandGET idem:order-981-payinredis-cli. What does a client see if it retries after 25 hours?- (Intermediate) Add request-body fingerprinting: store a SHA-256 of the body with the claim, and make a retry with a different body raise an error. Write a test with two concurrent requests that use the same key.
- (Interview) "A payment API uses Redis idempotency keys. After a Redis failover, a customer was charged twice. Explain how, and how to make it impossible." Hint: asynchronous replication, and where a uniqueness guarantee must live for it to survive the loss of the cache.
Semaphores
A lock lets one holder in. A semaphore lets up to N holders in at once: at most 10 concurrent calls to a partner API that allows 10 connections, at most 4 PDF renderings per cluster, at most 3 devices streaming per account. It is a lock with a capacity, like a parking garage with a counter at the entrance showing free spaces.
Approach 1: a counter (simple, leaks on crash)
INCR sem and check the result against N; DECR when done. If a holder crashes before DECR, its slot is lost forever. Avoid this unless slots are reconciled by another process.
Approach 2: a sorted set of holders with timestamps (recommended)
Each holder adds a unique ID scored by the acquisition time. Holders older than the timeout are treated as crashed and removed. Everything happens in one Lua script, using the server's clock so that all clients agree.
import uuid
import redis
r = redis.Redis(decode_responses=True)
ACQUIRE = r.register_script("""
local key, ttl, limit, holder = KEYS[1], tonumber(ARGV[1]), tonumber(ARGV[2]), ARGV[3]
local t = redis.call('TIME')
local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)
redis.call('ZREMRANGEBYSCORE', key, '-inf', now - ttl) -- evict holders that timed out
if redis.call('ZCARD', key) < limit then
redis.call('ZADD', key, now, holder)
redis.call('PEXPIRE', key, ttl) -- whole set disappears if unused
return 1
end
return 0
""")
REFRESH = r.register_script("""
local t = redis.call('TIME')
local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)
if redis.call('ZSCORE', KEYS[1], ARGV[1]) then -- still a holder?
redis.call('ZADD', KEYS[1], 'XX', now, ARGV[1]) -- renew my timestamp
redis.call('PEXPIRE', KEYS[1], ARGV[2])
return 1
end
return 0 -- timed out: I lost my slot
""")
class Semaphore:
def __init__(self, name: str, limit: int, ttl_ms: int = 30_000):
self.key, self.limit, self.ttl_ms = f"sem:{name}", limit, ttl_ms
self.holder = uuid.uuid4().hex
def acquire(self) -> bool:
return ACQUIRE(keys=[self.key], args=[self.ttl_ms, self.limit, self.holder]) == 1
def refresh(self) -> bool: # call during long work
return REFRESH(keys=[self.key], args=[self.holder, self.ttl_ms]) == 1
def release(self) -> None:
r.zrem(self.key, self.holder)
sems = [Semaphore("pdf-render", limit=3) for _ in range(5)]
print([s.acquire() for s in sems]) # [True, True, True, False, False]
sems[0].release()
print(sems[3].acquire()) # True: a slot became free
Approach 3: a list of tokens (blocking wait)
Pre-fill a list with N tokens. A holder takes one with BLMOVE pool held RIGHT LEFT <timeout>, which blocks until a token is available, and returns it when done. Waiting is efficient, with no polling. The weakness is the same as the counter: a crashed holder's token stays in held until a reaper process moves it back, so tokens should carry an owner and a deadline.
| Approach | Crash-safe | Waiting | Fairness |
|---|---|---|---|
Counter (INCR/DECR) | No | Polling | None |
| Sorted set + timeout | Yes, after the timeout | Polling with backoff | Roughly first come, first served |
List of tokens (BLMOVE) | Needs a reaper | Blocking, no polling | First come, first served among blocked clients |
Key Takeaways
- A semaphore limits concurrency to N holders. A lock is the special case N = 1.
- The sorted-set semaphore removes holders that timed out, so crashes free their slots automatically.
- Use the server's
TIMEinside the script so that clock differences between clients do not distort timeouts. - Long-running holders must refresh their entry, and must stop work if the refresh fails.
Practice
- (Beginner) Run the example, then inspect the set with
ZRANGE sem:pdf-render 0 -1 WITHSCORES. Wait 30 seconds without refreshing and acquire again. What happened to the old holders?- (Intermediate) Implement a blocking
acquire(timeout)for the sorted-set semaphore with exponential backoff and jitter, and test it with 20 threads and a limit of 3. Record the maximum concurrency actually observed.- (Interview) "Limit each account to 3 simultaneous video streams across all devices. A phone that loses its connection must not block a slot forever." Hint: combine a per-account sorted-set semaphore with heartbeats from the player, and decide what the timeout should be.
<a id="83-common-application-use-cases"></a>
8.3 Common Application Use Cases
This subchapter works through the features that teams build with Redis most often: user sessions, background job queues, live counters and dashboards, leaderboards, social activity feeds and duplicate detection. Each one combines data types from chapters 2 and 3 with the atomicity tools from chapter 4. For each, the goal is a design that is fast in the common case, and the topic notes where it needs care at scale.
Session Storage
HTTP is stateless: every request arrives without memory of the previous one. A web application remembers that a user is logged in by giving the browser a session ID in a cookie and storing the session data (user ID, roles, cart, CSRF token) on the server, keyed by that ID. With one server, an in-memory map is enough. With several servers behind a load balancer, the next request may land on a different server, so the session store must be shared. Redis fits well: lookups take well under a millisecond, and sessions expire by themselves through TTLs.
browser ── Cookie: sid=9f2c... ──▶ load balancer ──▶ app server 1 ┐
└─▶ app server 2 ├──▶ Redis: session:9f2c... (hash, TTL 30 min)
└─▶ app server 3 ┘
Hash or string?
| Representation | Pros | Cons |
|---|---|---|
| String with serialized JSON | One GET/SET; GETEX reads and refreshes TTL atomically | Changing one field rewrites the whole value; concurrent requests can overwrite each other's changes |
| Hash, one field per attribute | Update single fields (HSET session:x cart_count 3); concurrent updates to different fields do not conflict | Values are flat strings; nested data needs JSON fields or RedisJSON |
Example
import json
import secrets
import redis
r = redis.Redis(decode_responses=True)
IDLE_TIMEOUT = 1800 # 30 minutes of inactivity
def create_session(user_id: int, roles: list[str]) -> str:
sid = secrets.token_urlsafe(32) # 256 bits of randomness: unguessable
key = f"session:{sid}"
pipe = r.pipeline()
pipe.hset(key, mapping={"user_id": user_id, "roles": json.dumps(roles),
"csrf": secrets.token_hex(16)})
pipe.expire(key, IDLE_TIMEOUT)
pipe.sadd(f"user:{user_id}:sessions", sid) # index: all sessions of a user
pipe.execute()
return sid
def load_session(sid: str) -> dict | None:
key = f"session:{sid}"
pipe = r.pipeline()
pipe.hgetall(key)
pipe.expire(key, IDLE_TIMEOUT, xx=True) # sliding expiration, only if it still exists
data, _ = pipe.execute()
return data or None # {} means expired or never existed
def logout_everywhere(user_id: int) -> None:
sids = r.smembers(f"user:{user_id}:sessions")
pipe = r.pipeline()
for sid in sids:
pipe.unlink(f"session:{sid}")
pipe.unlink(f"user:{user_id}:sessions")
pipe.execute()
For short-lived values inside a session, such as a one-time password or a step-up authentication flag, hash field expiration (Redis 7.4+, chapter 2.4) lets single fields expire while the session continues:
127.0.0.1:6379> HSETEX session:9f2c EX 120 FIELDS 1 otp 554433
(integer) 1
127.0.0.1:6379> HTTL session:9f2c FIELDS 1 otp
1) (integer) 118
Absolute and idle timeouts
Sliding expiration alone lets an active session live forever. Store created_at in the session and reject sessions older than an absolute limit (for example 12 hours) when loading them.
Operational choices
- Eviction. Under
allkeys-lru, sessions may be evicted when memory is full, which logs users out. Run sessions on an instance withnoevictionor avolatile-*policy (chapter 5.3), or a separate database from the cache. - Durability. Losing all sessions logs everyone out. That is usually acceptable but irritating, so enable AOF or RDB snapshots (chapter 6) and a replica.
- Security. Generate IDs with a cryptographic random generator, rotate the ID after login (against session fixation), never put the session ID in URLs, and protect Redis itself (chapter 11).
- Framework support. Most frameworks already offer Redis-backed sessions: Spring Session Data Redis,
connect-redisfor Express, Django's cache-based sessions, Railsredis-session-store.
Index cleanup
The user:<id>:sessions set is not cleaned when a session expires by TTL. Remove stale IDs lazily (when load_session returns nothing, SREM the ID), or periodically check members with EXISTS.
Key Takeaways
- A shared session store lets any application server handle any request. Redis offers fast lookups and automatic expiry.
- Use a hash per session for field-level updates, a random 256-bit ID, and sliding expiration with
EXPIRE ... XXplus an absolute limit. - Keep a per-user set of session IDs to support "log out of all devices".
- Make sure sessions are not evicted like cache entries, and persist them if mass logouts are unacceptable.
Practice
- (Beginner) Create a session, load it a few times while watching
TTL session:<sid>, then stop loading it and confirm that it disappears after the idle timeout (use a 20-second timeout for testing).- (Intermediate) Add an absolute timeout of 12 hours and session ID rotation after login. Write a test that shows the old ID no longer works after rotation.
- (Interview) "Our Redis session store hit
maxmemory, and users started being logged out at random. What happened and what do you change?" Hint: check the eviction policy and whether sessions share the instance with cache data.
Job and Task Queues
Some work should not happen inside the web request: sending email, resizing images, generating reports, calling slow partner APIs. The request puts a job on a queue and returns. Workers take jobs off the queue and process them in the background. Redis is one of the most common queue backends, behind libraries such as Sidekiq (Ruby), BullMQ (Node.js), RQ and Celery (Python) and Asynq (Go).
web app ──LPUSH──▶ [ job3 | job2 | job1 ] ──BRPOP──▶ worker 1
web app ──LPUSH──▶ ──BRPOP──▶ worker 2
Level 1: a simple list queue
LPUSH adds to the head, and BRPOP blocks until a job is available and removes it from the tail (first in, first out). Each job goes to exactly one worker.
import json
import redis
r = redis.Redis(decode_responses=True)
def enqueue(queue: str, payload: dict) -> None:
r.lpush(f"queue:{queue}", json.dumps(payload))
def worker(queue: str) -> None:
while True:
item = r.brpop([f"queue:{queue}"], timeout=5) # blocks up to 5 s, no busy polling
if item is None:
continue
_, raw = item
process(json.loads(raw))
The weakness: once BRPOP returns, the job is no longer in Redis. If the worker crashes while processing, the job is lost.
Level 2: a reliable queue with a processing list
BLMOVE (Redis 6.2+) atomically moves the job from the queue to a per-worker processing list. The worker removes it with LREM only after finishing. A separate reaper process returns jobs from the processing lists of dead workers to the queue.
def reliable_worker(queue: str, worker_id: str) -> None:
src, processing = f"queue:{queue}", f"queue:{queue}:processing:{worker_id}"
while True:
raw = r.blmove(src, processing, timeout=5, src="RIGHT", dest="LEFT") # atomic move
if raw is None:
continue
try:
process(json.loads(raw))
r.lrem(processing, 1, raw) # done: remove from processing
except Exception:
r.lmove(processing, f"queue:{queue}:failed", "LEFT", "LEFT") # park it
This gives at-least-once delivery: a job may be processed twice (a worker finishes, then crashes before LREM), so jobs should be idempotent (8.2).
Level 3: streams with consumer groups
Streams (chapter 3.4) provide the reliable-queue mechanics built in: a consumer group delivers each entry to one consumer, tracks unacknowledged entries in the pending entries list, and lets others claim them with XAUTOCLAIM after a timeout. Entries can also be kept for replay and for several independent groups.
Delayed and scheduled jobs
"Send a reminder in 24 hours" needs a job that becomes visible later. Put it in a sorted set scored by the due time, and move due jobs to the ready queue periodically with a script:
import time
PROMOTE_DUE = r.register_script("""
local due = redis.call('ZRANGE', KEYS[1], '-inf', ARGV[1], 'BYSCORE', 'LIMIT', 0, ARGV[2])
for _, job in ipairs(due) do
redis.call('ZREM', KEYS[1], job)
redis.call('LPUSH', KEYS[2], job) -- atomic: a job is never in both or in neither
end
return #due
""")
def schedule(payload: dict, run_at: float) -> None:
r.zadd("jobs:delayed", {json.dumps(payload): run_at})
def scheduler_tick() -> int: # run every ~100 ms in one or more processes
return PROMOTE_DUE(keys=["jobs:delayed", "queue:email"], args=[time.time(), 100])
Include a unique job ID in each payload: identical payloads are the same sorted-set member and would be merged.
Priorities
- Several lists:
BRPOP queue:high queue:normal queue:low 5checks the keys in the given order, so high-priority jobs are always taken first (low priority can starve). - A sorted set: score by priority and use
BZPOPMINto take the lowest score first.
Comparison
| Need | List + BRPOP | List + BLMOVE | Stream + consumer group |
|---|---|---|---|
| Survive worker crash | No | Yes, with a reaper | Yes, built in (XAUTOCLAIM) |
| Delivery | At most once | At least once | At least once |
| Several independent consumers of the same jobs | No | No | Yes, one group each |
| History and replay | No | No | Yes, until trimmed |
| Simplicity | Highest | Medium | Medium |
When to use something else
Redis queues are fast and simple, but the jobs live in memory and replication is asynchronous. For very large backlogs, multi-day retention or strict durability, a dedicated broker (RabbitMQ, Kafka, SQS) is often a better fit.
Key Takeaways
LPUSH+BRPOPis a minimal queue, but a crashed worker loses its job.BLMOVEto a processing list, or streams with consumer groups, give at-least-once delivery. Make jobs idempotent.- Delayed jobs are a sorted set scored by due time, promoted atomically by a script.
- Prefer a well-tested library (BullMQ, Sidekiq, RQ, Celery, Asynq) over a hand-made queue for production.
Practice
- (Beginner) Run two workers on the same list queue and enqueue 20 jobs. Check that each job is processed exactly once. Then kill one worker while it sleeps inside
processand count the lost jobs.- (Intermediate) Write the reaper for the
BLMOVEdesign: each worker refreshes a heartbeat keyworker:<id>:alivewith a 10-second TTL, and the reaper moves jobs back from the processing lists of workers whose heartbeat has expired.- (Interview) "Design a scheduler for 50 million reminder notifications per day with delivery within 5 seconds of the due time." Hint: consider sharding the delayed sorted set by time bucket or by hash, the batch size per promotion, and how several scheduler processes avoid promoting the same job twice.
Real-Time Analytics
Dashboards that show "orders in the last minute", "unique visitors today" or "top products this hour" are hard to serve from a transactional database. Counting with SQL scans many rows on every refresh. Redis turns these questions into pre-aggregation: each event updates a few small counters as it happens, and the dashboard reads the counters, which costs almost nothing.
Choosing the structure for each metric
| Question | Structure | Commands | Memory |
|---|---|---|---|
| How many events per minute/hour/day? | String counters per time bucket, or a hash per day with a field per minute | INCR, HINCRBY, MGET | A few bytes per bucket |
| How many unique visitors? | HyperLogLog (chapter 3.2) | PFADD, PFCOUNT, PFMERGE | At most 12 KB per key, about 0.81% standard error |
| Was user N active on day D? Retention? | Bitmap indexed by user ID (chapter 3.1) | SETBIT, BITCOUNT, BITOP | 1 bit per user ID |
| Top items by count | Sorted set (exact) or Top-K (approximate) | ZINCRBY, ZRANGE ... REV, TOPK.ADD | Proportional to items, or fixed |
| Values over time for charts | Time series (chapter 3.5) | TS.ADD, TS.RANGE with aggregation | Compressed samples |
Example: one event, several metrics, one round trip
import time
from datetime import datetime, timezone
import redis
r = redis.Redis(decode_responses=True)
def track_page_view(page: str, user_id: int) -> None:
now = datetime.now(timezone.utc)
day, minute = now.strftime("%Y%m%d"), now.strftime("%H%M")
pipe = r.pipeline(transaction=False) # pipelining only: fewer round trips
pipe.hincrby(f"pv:{day}", minute, 1) # views per minute, one hash per day
pipe.expire(f"pv:{day}", 7 * 86400, nx=True) # keep a week
pipe.pfadd(f"uv:{day}", user_id) # unique visitors (approximate)
pipe.expire(f"uv:{day}", 7 * 86400, nx=True)
pipe.setbit(f"active:{day}", user_id, 1) # exact daily activity per user ID
pipe.zincrby(f"top:pages:{day}{now:%H}", 1, page) # top pages this hour
pipe.expire(f"top:pages:{day}{now:%H}", 2 * 86400, nx=True)
pipe.execute()
def dashboard(day: str) -> dict:
pipe = r.pipeline(transaction=False)
pipe.hgetall(f"pv:{day}")
pipe.pfcount(f"uv:{day}")
pipe.bitcount(f"active:{day}")
hour = datetime.now(timezone.utc).strftime("%H")
pipe.zrange(f"top:pages:{day}{hour}", 0, 9, desc=True, withscores=True)
per_minute, unique, active, top = pipe.execute()
return {"views": sum(map(int, per_minute.values())), "unique_approx": unique,
"active_exact": active, "top_pages": top}
Rolling windows
"Unique visitors in the last 7 days" is PFCOUNT uv:20261104 uv:20261105 ... uv:20261110: PFCOUNT with several keys returns the cardinality of their union without storing it. "Views in the last 60 minutes" is an HMGET of the last 60 minute fields (across two day-hashes around midnight).
Design guidelines
- Bucket by time in the key name and let old buckets expire. Never keep one ever-growing key.
- Choose bucket granularity for the queries you need: minute buckets for the last hour, hour buckets for the last week. Roll up older data into coarser buckets with a periodic job.
- Bitmaps need dense integer IDs.
SETBIT active 4000000000 1allocates about 500 MB. Use HyperLogLog or map IDs to a dense range first. - Approximate structures trade accuracy for memory. Show "about 12,400 visitors" rather than an exact-looking number.
- Pipeline the writes, and if event volume is very high, aggregate in the application for a second and send one
HINCRBYper bucket.
Key Takeaways
- Pre-aggregate on write: each event increments small counters, so reads for dashboards are trivial.
- Pick the structure per question: counters for totals, HyperLogLog for unique counts, bitmaps for per-user flags, sorted sets or Top-K for rankings, time series for charts.
- Put the time bucket in the key name and expire old buckets.
- Pipeline the updates for one event into a single round trip.
Practice
- (Beginner) Call
track_page_view10,000 times with random user IDs from 1 to 2,000. ComparePFCOUNTwithBITCOUNTand with the true number of distinct IDs.- (Intermediate) Implement "unique visitors in the last 7 days" and "users active on all of the last 3 days" (hint:
BITOP AND). MeasureMEMORY USAGEof each key.- (Interview) "Design the backend for a live dashboard showing requests per second, p99 latency and the 10 slowest endpoints, for a service with 50,000 requests per second." Hint: which values can be counters, which need a structure that supports percentiles (look at t-digest, chapter 3.2), and how to avoid one Redis write per request.
Leaderboards and Ranking
A game shows each player their rank among ten million players, refreshed in real time. With SQL, ORDER BY score DESC plus "what is my position" means counting all rows with a higher score, a slow query at that scale. A Redis sorted set (chapter 2.6) keeps members ordered by score at all times. Updating a score and reading a rank both take O(log N) time, so even with tens of millions of entries they take a fraction of a millisecond.
Core operations
| Need | Command |
|---|---|
| Set a score | ZADD lb 1500 player:7 |
| Add points | ZINCRBY lb 25 player:7 |
| Keep only the best score | ZADD lb GT 1500 player:7 (updates only if higher) |
| Top 10 with scores | ZRANGE lb 0 9 REV WITHSCORES |
| My rank (0-based, highest first) | ZREVRANK lb player:7 (WITHSCORE returns the score too, Redis 7.2+) |
| Players around me | ZREVRANK, then ZRANGE lb <rank-5> <rank+5> REV WITHSCORES |
| How many players scored 1000 to 2000 | ZCOUNT lb 1000 2000 |
| Remove a player | ZREM lb player:7 |
Example
127.0.0.1:6379> ZADD lb:global 3200 alice 2800 bob 3500 carol 2800 dave 1500 erin
(integer) 5
127.0.0.1:6379> ZINCRBY lb:global 450 bob
"3250"
127.0.0.1:6379> ZRANGE lb:global 0 2 REV WITHSCORES
1) "carol"
2) "3500"
3) "bob"
4) "3250"
5) "alice"
6) "3200"
127.0.0.1:6379> ZREVRANK lb:global alice WITHSCORE
1) (integer) 2 <- third place (ranks are 0-based)
2) "3200"
import redis
r = redis.Redis(decode_responses=True)
def around_me(board: str, player: str, radius: int = 5) -> list[tuple[int, str, float]]:
rank = r.zrevrank(board, player)
if rank is None:
return []
start = max(0, rank - radius)
rows = r.zrange(board, start, rank + radius, desc=True, withscores=True)
return [(start + i + 1, member, score) for i, (member, score) in enumerate(rows)] # 1-based
Ties
Members with equal scores are ordered by member name (byte order), so bob and dave with 2800 always rank alphabetically. If ties should be broken by "who got there first", encode the time into the score. A double has 53 bits of integer precision (about 9 x 10^15), enough for the points in the high part and an inverted timestamp in the low part:
MAX_TS = 9_999_999_999 # seconds, valid until the year 2286
def composite(points: int, achieved_at: int) -> int:
# points * 10^10 keeps points dominant; earlier achievement = larger remainder = higher rank
return points * 10_000_000_000 + (MAX_TS - achieved_at) # points must stay below ~900,000
def points_of(score: float) -> int:
return int(score) // 10_000_000_000
Time-boxed and combined boards
- One key per period:
lb:daily:20261110,lb:weekly:2026-W46, each with a TTL slightly longer than its period. Update all current periods in one pipeline per score change. - Combine boards with
ZUNIONSTORE lb:month 4 lb:w1 lb:w2 lb:w3 lb:w4 AGGREGATE SUM(orMAXfor "best of"), and weight them withWEIGHTS. - Friends leaderboards:
ZINTERSTORE tmp 2 lb:global friends:7 WEIGHTS 1 0, wherefriends:7is a sorted set (or set) of friend IDs, then readtmpand delete it. For large friend lists, preferZMSCORE lb:global friend1 friend2 ...and sort in the application.
Scale
In a test on Redis 8.10, a sorted set of 1 million members named like player:123456 used about 78 MB (MEMORY USAGE), so 10 million players need close to 800 MB, more with longer member names. All of it lives on one node in a cluster. Keep member names short (IDs, not JSON), store player details in separate hashes, and if the board grows beyond one node, split by region or league.
Key Takeaways
- Sorted sets give O(log N) score updates and rank lookups, which makes real-time leaderboards straightforward.
- Use
ZRANGE ... REVfor top N,ZREVRANKfor a player's rank, and the rank plus a range for "around me". - Equal scores sort by member name. Encode a timestamp into the score to break ties by time.
- Use one key per period with a TTL, and
ZUNIONSTOREto combine boards.
Practice
- (Beginner) Load 100,000 players with random scores using a pipeline. Time
ZREVRANKandZRANGE 0 9 REVfor a random player.- (Intermediate) Implement daily, weekly and all-time boards updated by one function, with TTLs on the time-boxed keys. Write a query that returns a player's rank on all three in one round trip.
- (Interview) "How would you show a player their percentile ('top 3%') in a game with 50 million players, updated in real time?" Hint:
ZREVRANKdivided byZCARDis exact. Consider memory on one node, and whether bucketed counts per score range would be enough.
Activity Feeds
A social application shows each user a timeline of recent posts from the people they follow. The naive query, "posts from all accounts I follow, newest first, limit 50", becomes expensive when users follow hundreds of accounts and millions of people refresh at once. Feeds are a classic case of choosing when to do the work: when a post is written, or when a feed is read.
Fan-out on write (push)
When a user posts, the post ID is pushed into the feed of every follower. Reading a feed is then one range query on one key.
Fan-out on read (pull)
Each user keeps only their own posts. Reading a feed merges the recent posts of everyone they follow.
Fan-out on write Fan-out on read
author posts ──▶ feed:f1 feed:f2 ... feed:fN reader ──▶ posts:a1 ┐
(N writes) each reader: 1 read (M reads) posts:a2 ├─ merge, sort, take 50
posts:aM ┘
| Fan-out on write | Fan-out on read | |
|---|---|---|
| Write cost | One write per follower | One write |
| Read cost | One range read | One read per followed account, plus a merge |
| Problem case | Celebrity with 50 million followers | Users following thousands of accounts |
| Memory | A copy of each post ID per follower | One entry per post |
Large systems use a hybrid: fan out on write for normal accounts, and at read time merge in the posts of the few very popular accounts the reader follows.
Storing a feed
| Structure | Use when |
|---|---|
List (LPUSH + LTRIM) | Feed is strictly newest-first and paged by position |
| Sorted set scored by timestamp | Items can arrive out of order, duplicates must be avoided, or paging is by time ("older than X") |
Example: sorted-set feeds with fan-out on write
import time
import redis
r = redis.Redis(decode_responses=True)
FEED_LEN = 500 # keep only the newest 500 entries
def publish_post(author: int, post_id: str, followers: list[int]) -> None:
ts = time.time()
pipe = r.pipeline(transaction=False)
pipe.zadd(f"posts:{author}", {post_id: ts}) # the author's own timeline
for f in followers:
key = f"feed:{f}"
pipe.zadd(key, {post_id: ts})
pipe.zremrangebyrank(key, 0, -(FEED_LEN + 1)) # trim: drop all but the newest 500
pipe.execute() # batch large follower lists (see below)
def read_feed(user: int, before: float | None = None, limit: int = 20) -> list[tuple[str, float]]:
max_score = f"({before}" if before else "+inf" # "(" = exclusive: cursor-based paging
return r.zrange(f"feed:{user}", max_score, "-inf", byscore=True, desc=True,
offset=0, num=limit, withscores=True)
page1 = read_feed(7)
page2 = read_feed(7, before=page1[-1][1]) if page1 else [] # next page: older than the last item
Paging by score ("older than the last item I saw") is stable when new posts arrive. Paging by offset (ZRANGE ... 20 39) shifts every time a new post is added at the top, which shows duplicates.
Practical points
- Store IDs, not content. Feeds hold post IDs. Post bodies live in hashes (
post:<id>) or another store and are fetched in one pipeline. Editing a post then needs no fan-out. - Fan out asynchronously. Publishing should enqueue a fan-out job (see "Job and Task Queues") that processes followers in batches of a few thousand.
- Skip inactive users. Do not fan out to users who have not logged in for weeks. Rebuild their feed on read when they return.
- Deletions. Deleting a post means removing its ID from many feeds. Many systems instead filter deleted IDs when hydrating the feed.
- In a cluster, feeds of different users sit on different nodes, so fan-out naturally spreads across the cluster.
Key Takeaways
- Fan-out on write makes reads cheap and writes expensive; fan-out on read does the opposite. Hybrids handle accounts with very many followers.
- Store post IDs in capped lists or sorted sets, and post content separately.
- Sorted sets scored by time give deduplication and stable cursor-based paging.
- Run fan-out in background jobs and in batches.
Practice
- (Beginner) Create 3 authors and 10 followers, publish 30 posts and print the first two pages of one follower's feed using the cursor from the first page.
- (Intermediate) Implement fan-out on read for the same data with
ZUNIONSTOREinto a temporary key (or a merge in Python), and compare the number of commands for one feed read with the push approach.- (Interview) "Design the home timeline for a service where some accounts have 100 million followers." Hint: compute the cost of fan-out on write for such an account, then describe the hybrid and how the merge at read time is limited.
Deduplication
Duplicates come from everywhere: a client retries a request, a message broker redelivers a message, a crawler finds the same URL on a hundred pages, a user double-clicks "submit". Deduplication means remembering what has already been seen, quickly, and deciding what to do with a repeat. Redis offers several ways to remember, with different trade-offs between exactness, memory and how long the memory lasts.
Options
| Technique | Command | Exact? | Memory | Forgets |
|---|---|---|---|---|
| One key per item, with TTL | SET seen:<id> 1 NX EX 86400 | Yes | Tens of bytes per item (42 to 74 bytes on Redis 8.10, depending on the key length) | Automatically after the TTL |
| Set of seen IDs | SADD seen:<day> <id> (returns 1 if new) | Yes | Per member, compact for small integer sets | When the whole key expires |
| Bloom filter (chapter 3.2) | BF.ADD seen <id> (returns 1 if new) | No: false positives, never false negatives | About 1.2 bytes per item at 1% error | Never (rotate filters by time) |
| Stream idempotent producer | XADD ... IDMP <pid> <iid> (Redis 8.6+) | Yes | Bounded window | After the configured window |
Example: exact deduplication of incoming messages
import redis
r = redis.Redis(decode_responses=True)
def handle_once(message_id: str, payload: dict) -> bool:
# SET NX succeeds only for the first delivery; the key remembers it for 24 hours
if not r.set(f"seen:msg:{message_id}", 1, nx=True, ex=86_400):
return False # duplicate: acknowledge and skip
process(payload)
return True
If process fails, delete the key so a redelivery can try again, or mark the key as "processing" and "done" as with idempotency keys (8.2).
Example: approximate deduplication of URLs for a crawler
A crawler sees billions of URLs. An exact set would need tens of gigabytes. A Bloom filter answers "definitely new" or "probably seen" in fixed memory:
127.0.0.1:6379> BF.RESERVE crawl:seen 0.001 100000000 <- 0.1% error, 100 million URLs
OK
127.0.0.1:6379> BF.ADD crawl:seen "https://example.com/a"
(integer) 1 <- new: crawl it
127.0.0.1:6379> BF.ADD crawl:seen "https://example.com/a"
(integer) 0 <- probably seen: skip
A false positive here means that about 1 URL in 1,000 that is new is skipped. That is fine for a crawler and unacceptable for payments. Choose exact techniques when skipping a real item is costly.
Deduplicating within a time window
For "ignore the same alert for 10 minutes" or "no more than one password-reset email per hour", one key per item with a TTL is exactly the right shape: SET alert:<fingerprint> 1 NX EX 600. For a Bloom filter, rotate one filter per day (seen:20261110) and check today's and yesterday's.
Key Takeaways
SET key 1 NX EX ttlis exact, atomic, and forgets automatically. It is the default choice.SADDreturns whether a member was new, which is useful for bounded sets of IDs.- Bloom filters use fixed, small memory for huge volumes, at the price of occasional false positives (some new items treated as duplicates).
- Decide what a false positive costs before choosing an approximate structure.
Practice
- (Beginner) Simulate 10,000 messages with 10% duplicates and count how many
handle_onceprocesses. Check memory withINFO memorybefore and after.- (Intermediate) Insert 1 million random URLs into a Bloom filter created with
BF.RESERVE ... 0.01 1000000, then test 100,000 URLs that were never added and measure the false positive rate. CompareMEMORY USAGEwith a set holding the same URLs.- (Interview) "An event pipeline delivers messages at least once. Downstream wants exactly-once effects. Where do you deduplicate, and what key do you use?" Hint: consider whether the producer can supply a stable ID, how long duplicates can arrive after the original, and what happens if the dedup store loses data.
<a id="84-data-modeling"></a>
8.4 Data Modeling
This subchapter covers how to shape application data for Redis. A relational database models the data first and lets queries be written later. Redis works the other way round: it has no query planner, no joins and no secondary indexes unless you build them (or use the Query Engine, chapter 9.1). You model for the access patterns, choosing types, key names, indexes and copies so that every frequent question is answered by one or a few cheap commands. The topics go from choosing types to indexes and relationships, to deliberate duplication, and finally to the size and traffic limits of a single key.
Choosing the Right Data Type
In a relational database, the table is the only shape. In Redis, each key has a type, and the type decides which operations are cheap. Storing a user's followers as a JSON string works, but then "is Alice following Bob?" means downloading and parsing the whole list. Storing them as a set makes the same question a single O(1) SISMEMBER. Choosing the type is the most important modeling decision, and the right choice comes from the questions you will ask, not from the shape of the data.
Start from the questions
- List the operations the feature needs and how often each runs ("add follower" 100/s, "is following?" 50,000/s, "count followers" 5,000/s).
- For each candidate type, check the complexity of those operations.
- Pick the type that makes the most frequent operations O(1) or O(log N), and check the memory cost.
Decision table
| Access pattern | Type | Key operations |
|---|---|---|
| Get/set a whole value; counters; flags | String | GET, SET, INCR, GETEX |
| An object with fields read or updated individually | Hash | HGET, HSET, HINCRBY, HGETALL |
| An object with nested structure, partial updates in depth | JSON (chapter 3.5) | JSON.GET, JSON.SET with paths |
| Ordered sequence; queue; "last N items" | List | LPUSH, RPOP, LRANGE, LTRIM |
| Unique members; membership; set algebra | Set | SADD, SISMEMBER, SINTER |
| Members ordered by a number; ranges by score; rankings | Sorted set | ZADD, ZRANGE, ZRANK |
| Append-only events; consumer groups | Stream (chapter 3.4) | XADD, XREADGROUP |
| One bit per integer ID | Bitmap (chapter 3.1) | SETBIT, BITCOUNT |
| Approximate distinct counts, membership, frequencies | HyperLogLog, Bloom, Count-Min, Top-K (chapter 3.2) | PFADD, BF.ADD, TOPK.ADD |
| Points and radius queries | Geo (chapter 3.3) | GEOADD, GEOSEARCH |
| Numeric samples over time | Time series (chapter 3.5) | TS.ADD, TS.RANGE |
| Similarity search on embeddings | Vector set or vector index (chapter 9.2) | VADD, VSIM, FT.SEARCH |
Example: one entity, three models
A product with name, price and stock that changes often:
# Model A: a JSON string. Simple, but every stock change rewrites the whole value
SET product:42 '{"name":"Lamp","price":19.9,"stock":12}'
# Model B: a hash. Fields update independently and atomically
HSET product:42 name Lamp price 19.9 stock 12
HINCRBY product:42 stock -1 # no read-modify-write in the application
# Model C: separate string keys per field. Avoid: more keys, more memory, no single read
SET product:42:name Lamp
SET product:42:stock 12
Model B is usually right for flat objects. Model A is fine for values that are always read and written as a whole (a rendered page, an API response). Model C costs per-key overhead (tens of bytes each, plus expiry entries) and loses HGETALL.
Memory and encodings
Small hashes, sets, sorted sets and lists use compact listpack or intset encodings (chapter 5.2), which can be several times smaller than the full structures. On Redis 8.10, hashes stay compact up to 512 fields with values up to 64 bytes, and sorted sets up to 128 members. This enables a known trick: store many tiny objects as fields of bucketed hashes instead of separate keys.
import redis
r = redis.Redis(decode_responses=True)
# 1 million "user -> avatar URL" mappings
def set_avatar(user_id: int, url: str) -> None:
bucket = user_id // 500 # 500 fields per hash: stays a listpack
r.hset(f"avatar:{bucket}", str(user_id), url) # (if every URL is 64 bytes or less)
def get_avatar(user_id: int) -> str | None:
return r.hget(f"avatar:{user_id // 500}", str(user_id))
The costs: a single value longer than 64 bytes converts its whole bucket to a full hash table, per-item TTLs need hash field expiration (Redis 7.4+, chapter 2.4) instead of EXPIRE, and in a cluster the bucket, not the item, is the unit of distribution.
Key naming
- Use a consistent scheme:
object-type:id[:sub-part], such asuser:1001,user:1001:followers. - Keep names short but readable. Key names are stored in memory for every key.
- Put the part that must co-locate in a hash tag for cluster deployments:
cart:{user:1001},cart-items:{user:1001}(chapter 7.3). - Document the schema somewhere. Redis will not.
Key Takeaways
- Choose types from the operations you need and their frequency, not from the shape of the data.
- Hashes are the default for flat objects with independently updated fields. JSON is for nested documents.
- Small collections use compact encodings. Bucketing tiny values into hashes saves memory.
- Use a consistent key naming scheme, and hash tags where multi-key atomicity is needed in a cluster.
Practice
- (Beginner) Store 100,000 products as JSON strings and as hashes. Compare
INFO memoryand the code needed to decrement stock safely in each model.- (Intermediate) Implement the avatar bucketing above for 1 million users and compare total memory with 1 million separate string keys. Then set the bucket size to 1,000 and explain the change in memory using
OBJECT ENCODING.- (Interview) "Model a URL shortener in Redis: create short links, resolve them, count clicks per link and per day, and list a user's links newest first." Hint: write the list of operations first, then pick one type per operation and name the keys.
Secondary Indexes
Redis looks up data by key: HGETALL user:1001 is instant. "Find users in Italy aged 25 to 35" is not a key lookup, and Redis has no WHERE clause. Scanning all keys with SCAN and filtering in the application is O(N) and far too slow for a request path. A secondary index is an extra structure, maintained next to the data, that maps an attribute value to the keys (or IDs) that have it. It is the same idea as the index at the back of a book: to find "replication", you look it up in the index, not by reading every page.
There are two ways to get secondary indexes in Redis:
- Build them by hand with sets and sorted sets, as described here. This works on every Redis version and gives full control.
- Use the Redis Query Engine (
FT.CREATE, chapter 9.1), which indexes hashes and JSON documents automatically and supports full-text, numeric, tag, geo and vector queries. For new projects that can use it, it removes most of the manual work below.
Index types
| Query | Index structure | Example |
|---|---|---|
| Equality on a value ("country = IT") | A set per value | SADD idx:user:country:IT 1001 |
| Range on a number ("age 25..35") | A sorted set scored by the value | ZADD idx:user:age 31 1001 |
| Prefix / lexicographic ("name starts with 'mar'") | A sorted set with all scores 0, ordered by member | ZADD idx:user:name 0 "maria:1001" |
| Combination ("country = IT and age 25..35") | Intersect the results | ZINTERSTORE or ZRANGE + SMISMEMBER |
Example: maintaining indexes with the data
The data and its indexes must change together. Use MULTI/EXEC (chapter 4.2) for writes, and update or remove old index entries when a value changes.
import redis
r = redis.Redis(decode_responses=True)
def save_user(uid: int, name: str, country: str, age: int) -> None:
old = r.hmget(f"user:{uid}", "name", "country") # needed to clean up old index entries
pipe = r.pipeline() # MULTI/EXEC
if old[1] and old[1] != country:
pipe.srem(f"idx:user:country:{old[1]}", uid)
if old[0]:
pipe.zrem("idx:user:name", f"{old[0].lower()}:{uid}")
pipe.hset(f"user:{uid}", mapping={"name": name, "country": country, "age": age})
pipe.sadd(f"idx:user:country:{country}", uid) # equality index
pipe.zadd("idx:user:age", {uid: age}) # range index (overwrites the old score)
pipe.zadd("idx:user:name", {f"{name.lower()}:{uid}": 0}) # prefix index
pipe.execute()
def users_by_age(lo: int, hi: int) -> list[str]:
return r.zrange("idx:user:age", lo, hi, byscore=True)
def users_by_name_prefix(prefix: str, limit: int = 10) -> list[str]:
p = prefix.lower().encode()
# byte 0xFF sorts after every UTF-8 byte, so "[p" .. "[p\xff" covers all names starting with p
members = r.zrange("idx:user:name", b"[" + p, b"[" + p + b"\xff", bylex=True,
offset=0, num=limit)
return [m.rsplit(":", 1)[1] for m in members] # "maria:1001" -> "1001"
def users_in_country_by_age(country: str, lo: int, hi: int) -> list[str]:
ids = users_by_age(lo, hi)
if not ids:
return []
flags = r.smismember(f"idx:user:country:{country}", ids) # one round trip
return [i for i, ok in zip(ids, flags) if ok]
save_user(1001, "Maria", "IT", 31)
save_user(1002, "Mario", "IT", 45)
save_user(1003, "Marta", "ES", 29)
print(users_by_age(25, 35)) # ['1003', '1001']
print(users_by_name_prefix("mar")) # ['1001', '1002', '1003']
print(users_in_country_by_age("IT", 25, 35)) # ['1001']
The read of the old values (HMGET) happens before MULTI, so a concurrent update can slip in between. If the same object may be updated concurrently, wrap the read in WATCH user:<uid> or move the whole update into a Lua script.
Composite and sorted results
- For "country = IT, ordered by age", keep a sorted set per country:
ZADD idx:user:age:IT 31 1001. More indexes, simpler queries. ZINTERSTORE tmp 2 idx:user:age idx:user:country:IT WEIGHTS 1 0intersects a sorted set with a set (sets count as score 1), keeping the age as score. Deletetmpafterwards, or useZINTER(Redis 6.2+) to get the result without storing it.- A lexicographic index can encode several fields in order:
ZADD idx 0 "IT:0031:1001"(zero-padded age) supports "country = IT and age between 25 and 35" as oneBYLEXrange from[IT:0025to[IT:0035:\xff.
Costs and cluster caveats
- Every index is extra memory and an extra write per change.
- In Redis Cluster, a global index such as
idx:user:agelives on one node and all writes to it go there. Multi-key operations between the data and the index need a shared hash tag, which puts everything on one node. Common solutions: shard indexes by a prefix (idx:user:age:{shard-7}) and query all shards, or use the Query Engine, which handles distribution.
Key Takeaways
- Redis finds data only by key. Any other lookup needs an index you maintain, or the Query Engine.
- Sets index equality, sorted sets index numeric ranges, and score-0 sorted sets with
BYLEXindex prefixes and composite keys. - Update data and indexes in one transaction, and remove stale index entries when values change.
- Indexes cost memory and write throughput, and global indexes are a cluster hot spot.
Practice
- (Beginner) Run the example, change user 1001's country to
FR, and check thatidx:user:country:ITno longer contains1001.- (Intermediate) Add a composite lexicographic index
country:age:idwith zero-padded ages, and implement "users in IT aged 25 to 35" with a singleZRANGE ... BYLEX. Compare the number of commands withusers_in_country_by_age.- (Interview) "We need to find orders by customer, by status and by date range, at 20,000 orders per second. Would you build manual indexes or use the Query Engine? What changes in a cluster?" Hint: consider write amplification per order, consistency between data and indexes, and where each index key lives.
Modeling Relationships
Users have orders, orders have items, students take courses. In SQL, relationships are foreign keys and joins. Redis has neither. Relationships are modeled explicitly, usually as collections of IDs, and the "join" is a second round of lookups done by the application, usually in a pipeline. The patterns are few and predictable.
One-to-one
Embed the related data in the same hash when it is always read together (user:1001 with street, city), or use a separate key with the same ID (user:1001:settings) when it is large or rarely needed.
One-to-many
Keep the children's IDs in a collection on the parent, and a reference to the parent in each child:
| Need on the "many" side | Structure | Example |
|---|---|---|
| Unordered, membership checks | Set | SADD user:1001:addresses addr:9 |
| Ordered by time or another number, paging | Sorted set | ZADD user:1001:orders 1794300000 order:5001 |
| Insertion order, capped | List | LPUSH user:1001:recent order:5001 + LTRIM |
Many-to-many
Keep both directions, each as a set (or sorted set), and update them together:
students ◀──────────── enrollments ────────────▶ courses
student:7:courses = {course:db, course:os} course:db:students = {student:7, student:9}
Example
import time
import redis
r = redis.Redis(decode_responses=True)
def place_order(user_id: int, order_id: int, total: float) -> None:
pipe = r.pipeline() # MULTI/EXEC: both sides or neither
pipe.hset(f"order:{order_id}", mapping={"user_id": user_id, "total": total,
"created": int(time.time())})
pipe.zadd(f"user:{user_id}:orders", {order_id: time.time()}) # one-to-many, by time
pipe.execute()
def recent_orders(user_id: int, n: int = 10) -> list[dict]:
ids = r.zrange(f"user:{user_id}:orders", 0, n - 1, desc=True)
pipe = r.pipeline(transaction=False)
for oid in ids:
pipe.hgetall(f"order:{oid}") # the "join": one round trip for all
return pipe.execute()
def enroll(student: int, course: str) -> None:
pipe = r.pipeline()
pipe.sadd(f"student:{student}:courses", course) # many-to-many: both directions
pipe.sadd(f"course:{course}:students", student)
pipe.execute()
def classmates(student: int, course: str) -> set[str]:
return r.smembers(f"course:{course}:students") - {str(student)}
def shared_courses(a: int, b: int) -> set[str]:
return r.sinter(f"student:{a}:courses", f"student:{b}:courses")
Embedding vs referencing
| Embed (copy the child's data into the parent) | Reference (store the child's ID) |
|---|---|
| One read returns everything | Two steps: IDs, then a pipeline of lookups |
| Child data duplicated if shared | Single source for each object |
| Good for small, rarely changing children owned by one parent (order line items) | Good for shared, changing or large children (products, users) |
JSON documents (chapter 3.5) make embedding natural: an order with its line items as an array, updated with JSON.ARRAPPEND.
Deletes and integrity
Nothing enforces referential integrity. Deleting order:5001 leaves its ID in user:1001:orders unless you remove it in the same transaction. When reading, tolerate missing objects (skip empty HGETALL results) and clean up references lazily.
Clusters
Both sides of a relationship and the objects themselves are usually on different nodes, so the "join" pipeline touches several nodes (cluster-aware clients split it automatically, chapter 10.2). Transactions that update both sides need a common hash tag, for example {user:1001} on the user's orders index and on their order keys, which keeps one user's data together.
Key Takeaways
- Relationships are collections of IDs: sets for unordered, sorted sets for ordered, lists for capped recent items.
- Store many-to-many relationships in both directions and update both in one transaction.
- The "join" is a pipeline of lookups. Embed small, owned children and reference shared ones.
- Redis does not enforce integrity: clean up references on delete and tolerate dangling IDs on read.
Practice
- (Beginner) Implement
place_orderandrecent_orders, insert 50 orders and read the latest 10. Then delete one order hash without touching the index and makerecent_ordersskip it.- (Intermediate) Model a "who follows whom" graph with followers and following in both directions. Implement follow, unfollow, "do A and B follow each other?" and "accounts both A and B follow".
- (Interview) "Model a library: books, authors (a book can have several), members and loans with due dates. Show the keys for 'all overdue loans' and 'books by author X currently available'." Hint: one sorted set scored by due date answers the first question. The second needs a set intersection or a filter.
Denormalization Strategies
Relational design teaches normalization: store each fact once, and join at read time. Redis cannot join on the server, and every extra round trip costs latency. So Redis models are usually denormalized: the same fact is copied into the places where it is read, so that each read needs one key or one pipeline. The price is moved to writes: one change must update several copies, and they can disagree for a while.
An analogy: a phone number written on a sticky note on the fridge, in your phone and in your address book. Finding it is instant from anywhere, but when it changes, you must update every copy, and sometimes one is forgotten.
Common forms
| Strategy | Example | Read benefit | Write cost |
|---|---|---|---|
| Copy attributes into referencing objects | post:9 stores author_name and author_avatar next to author_id | Rendering a post needs no user lookup | Renaming a user must update their posts (or tolerate stale names) |
| Precomputed aggregates | user:7 has followers_count, HINCRBY on every follow | O(1) instead of SCARD on a large set or a SQL COUNT | One extra write per change |
| Materialized views | feed:7 (8.3), top:products:today | The answer is stored ready to read | Fan-out work on every change |
| Duplicate keys per access path | The same order in user:7:orders and orders:by-status:pending | Each query is one range read | Every status change touches two indexes |
| Pre-rendered responses | render:product:42:en with the full HTML or JSON | Zero work on read | Invalidated on every relevant change (8.1) |
Keeping copies consistent
| Technique | Consistency | When |
|---|---|---|
Update all copies in one MULTI/EXEC or Lua script | All-or-nothing in Redis | Copies are few and on the same node (or share a hash tag) |
| Update the source, then propagate asynchronously (stream or queue of change events) | Eventual; copies lag by the queue delay | Many copies (fan-out, counters across users) |
| Do not update; let copies expire and be rebuilt | Bounded by the TTL | Cached views and pre-rendered responses |
| Periodic reconciliation job that recomputes from the source | Repairs drift | Counters that must eventually be exact |
Example: denormalized counters with periodic repair
import redis
r = redis.Redis(decode_responses=True)
def follow(follower: int, followee: int) -> None:
# The source of truth decides whether this is a new relationship (SADD returns 0 if not)
if not r.sadd(f"followers:{followee}", follower):
return
pipe = r.pipeline(transaction=False) # keys of two users: maybe two nodes
pipe.sadd(f"following:{follower}", followee) # the other direction
pipe.hincrby(f"user:{followee}", "followers_count", 1) # denormalized aggregates
pipe.hincrby(f"user:{follower}", "following_count", 1)
pipe.execute()
def repair_counts(user_id: int) -> None:
# Reconciliation: recompute from the sets, fixing drift from crashes between steps
pipe = r.pipeline()
pipe.scard(f"followers:{user_id}")
pipe.scard(f"following:{user_id}")
followers, following = pipe.execute()
r.hset(f"user:{user_id}", mapping={"followers_count": followers,
"following_count": following})
The steps in follow are not in one transaction because the keys belong to different users, and in a cluster they are on different nodes. A crash after the first SADD leaves the other direction and the counts behind, which repair_counts (and a similar repair of following:<id>) fixes later. That is a deliberate trade: display counters may be briefly wrong, and they are cheap.
A cleaner version for a single node is a Lua script that does SADD on both sets and increments the counters only if SADD returned 1. It is atomic and counts exactly.
When not to denormalize
- When the copied data changes very often relative to how often it is read.
- When readers must never see stale or inconsistent data (balances, permissions).
- When the number of copies is unbounded (copying a user's name into every comment they ever wrote).
Key Takeaways
- Redis models copy data into the shape of each read, because there are no server-side joins.
- Denormalization moves cost from reads to writes, and creates copies that can disagree.
- Keep copies consistent with transactions when they are few and co-located, with asynchronous propagation when they are many, and with TTLs or reconciliation jobs as a safety net.
- Denormalize data that is read often and changes rarely. Keep frequently changing or critical data normalized.
Practice
- (Beginner) Store 1,000 posts that each copy their author's name. Rename the author and update all copies with a pipeline driven by a per-author set of post IDs.
- (Intermediate) Rewrite
followas a single Lua script that updates both sets and both counters only when the relationship is new. Addunfollow, and test both with concurrent calls.- (Interview) "Our product page shows the seller's name, rating and number of sales, copied into each product hash. Sellers complain that their rating takes hours to update. What are your options?" Hint: compare copying at write time with looking up the seller at read time (in the same pipeline), and consider an event-driven update of the copies.
Avoiding Big Keys and Hot Keys
Redis executes commands on one main thread (chapter 5.1), and in a cluster every key lives on exactly one node. Two problems follow from this. A big key, one key with a huge value or millions of elements, makes single commands slow and blocks everyone else. A hot key, one key receiving a disproportionate share of traffic, overloads the one node and the one core that serve it, no matter how many nodes the cluster has. Both are among the most common causes of latency spikes in production.
What counts as big or hot
There are no official thresholds. Common working limits are:
| Problem | Rough threshold | Symptoms |
|---|---|---|
| Big string | Over about 1 MB (alarming from 10 MB) | Slow GET, network spikes, large replication and AOF writes |
| Big collection | Over about 10,000 elements, or over about 100 MB | HGETALL / SMEMBERS / LRANGE 0 -1 block for milliseconds or seconds; DEL blocks; slow slot migration and MIGRATE (chapter 7.3) |
| Hot key | A key taking a large fraction of a node's commands, for example over 10,000 operations per second on one key | One node's CPU at 100% while others are idle, rising latency for all keys on that node |
Why big keys hurt
main thread timeline:
GET a │ GET b │ HGETALL big:hash (1.2 s) ███████████████████████ │ GET c │ ...
└ every client waits
Further effects: deleting a big key with DEL frees memory synchronously (use UNLINK, or enable lazyfree-lazy-user-del, chapter 5.3); expiry of a big key causes the same pause; replicas and AOF receive large writes; a cluster cannot split a key across nodes, so one big key can fill one node.
Finding them
# Sample the keyspace without blocking the server (uses SCAN)
redis-cli --bigkeys # largest keys by element count, per type
redis-cli --memkeys # largest keys by memory
redis-cli --keystats # both, with a size distribution (Redis 7.4+)
redis-cli MEMORY USAGE user:1001:followers
# Hot keys
redis-cli --hotkeys # needs an LFU maxmemory-policy (uses OBJECT FREQ)
Redis 8.6 added the HOTKEYS command, which tracks the keys that use the most CPU time or network bytes without needing an LFU policy. A run on Redis 8.10 after 300 reads of one key and 20 reads of other keys:
127.0.0.1:6379> HOTKEYS START METRICS 2 CPU NET COUNT 5
OK
(traffic runs)
127.0.0.1:6379> HOTKEYS GET
1) 1) "tracking-active"
2) (integer) 1
...
21) "by-cpu-time-us"
22) 1) "hot:item"
2) (integer) 537 <- microseconds of CPU spent on this key
3) "cold:1"
4) (integer) 4
...
23) "by-net-bytes"
24) 1) "hot:item"
2) (integer) 9600 <- bytes of network traffic for this key
...
127.0.0.1:6379> HOTKEYS STOP
OK
SAMPLE <ratio> tracks only a fraction of keys to reduce overhead, and DURATION <seconds> stops tracking automatically. Chapter 12.2 covers detection in more depth.
Fixing big keys
| Technique | How |
|---|---|
| Split by bucket | followers:7 becomes followers:7:0 ... followers:7:15, with the bucket chosen by hash(member) % 16 |
| Split by time | events:7 becomes events:7:20261110, one key per day, each with a TTL |
| Cap the size | LTRIM, ZREMRANGEBYRANK, XADD ... MAXLEN ~ n on every write |
| Read incrementally | HSCAN, SSCAN, ZSCAN, ZRANGE with LIMIT instead of HGETALL and friends |
| Delete in the background | UNLINK instead of DEL, or trim a large collection in batches before deleting it |
| Store less | Compress large strings in the application; move blobs (images, documents) to object storage and keep only a reference |
import zlib
import redis
r = redis.Redis(decode_responses=True)
BUCKETS = 16
def _bucket_key(user_id: int, member: str) -> str:
return f"followers:{user_id}:{zlib.crc32(member.encode()) % BUCKETS}"
def add_follower(user_id: int, follower: str) -> None:
r.sadd(_bucket_key(user_id, follower), follower)
def is_follower(user_id: int, follower: str) -> bool:
return bool(r.sismember(_bucket_key(user_id, follower), follower)) # still one O(1) lookup
def follower_count(user_id: int) -> int:
pipe = r.pipeline(transaction=False)
for b in range(BUCKETS):
pipe.scard(f"followers:{user_id}:{b}")
return sum(pipe.execute()) # one round trip
Choose the bucket function so that point lookups stay single-key. Operations that need the whole collection (count, iterate) touch every bucket, so keep a denormalized counter if they are frequent.
Fixing hot keys
| Technique | How | Works for |
|---|---|---|
| Client-side caching | Keep the value in application memory with tracking (8.1) | Read-hot keys |
| Read from replicas | Send reads of the key to replicas (chapter 7.1) | Read-hot keys that tolerate slight staleness |
| Key replication | Store N copies (config:flags:0 ... config:flags:7), read a random one, write all | Read-hot keys in a cluster, where copies land on different nodes |
| Shard the counter | INCR views:42:<random 0..15>, sum the shards on read | Write-hot counters |
| Batch in the application | Aggregate increments in memory for a second, then send one INCRBY | Write-hot counters that tolerate a short delay |
| Change the model | Split a global index or queue by region, tenant or time | Structurally hot keys |
Key Takeaways
- A big key makes single commands, deletes, expirations and migrations slow, and blocks every other client meanwhile.
- A hot key overloads one node and one core, and adding cluster nodes does not help.
- Find them with
redis-cli --bigkeys,--memkeys,--keystats,--hotkeys(LFU only) and, on Redis 8.6+,HOTKEYS. - Split big keys by bucket or time, cap their size, read them incrementally and delete them with
UNLINK. - Spread hot keys with client-side caching, replicas, key copies or sharded counters.
Practice
- (Beginner) Create a hash with 2 million fields. Time
HGETALLfrom one client while a second client runsredis-cli --latency. Then delete it withDELand recreate and delete it withUNLINK, comparing the pauses.- (Intermediate) Implement a sharded counter with 16 shards for a write-hot
page:viewskey. Run 50 threads ofINCRagainst both designs on a 3-node cluster and compare per-node CPU usage withINFO cpuorHOTKEYS.- (Interview) "During a flash sale, one product's stock key receives 200,000 decrements per second, and the node holding it is saturated. How do you sell exactly the available stock without overselling?" Hint: consider splitting the stock into several keys (allocate 100 units to each of N shards), what happens when one shard runs out while others have stock, and where the exact total must be enforced.
<a id="9-search-and-ai-workloads"></a>