Warming Redis Caches for Parcel Lookup Endpoints

12 min read

Pre-warming Redis for parcel lookups is a focused technique inside Cache Warming Strategies for Permit Lookup APIs, part of the broader Automated Permit Ingestion and Parsing Workflows track: it keeps parcel-keyed reads fast during counter hours without hammering a rate-limited county GIS or permit API. This guide walks Python builders through populating Redis with redis-py pipelines, spreading TTLs with jitter to avoid a stampede, choosing between cache-aside and write-through, mining access logs for the hot set, and invalidating cleanly when a permit changes.

The task is narrow and high-stakes. A parcel lookup — “what is the zoning, permit status, and open-inspection state for parcel 0142-007-031?” — sits on the critical path of nearly every clerk portal screen and every enrichment step in the ingestion pipeline. When those reads miss cold against a legacy county endpoint that caps at five concurrent requests, a single morning rush produces multi-second stalls, quota exhaustion, and the classic thundering-herd collapse the moment a deploy flushes the cache. The inputs are predictable (a bounded set of parcel identifiers that recur daily) and the compliance stakes are real: a stale cached zoning code can drive an incorrect fee assessment or a missed setback violation. The output is a Redis keyspace that is already warm before the first clerk logs in, with staleness bounded and every write auditable.

Why jittered TTLs prevent a cache stampede on parcel lookups Two timelines compare cache-key expiry strategies. In the top timeline, six parcel keys share one uniform TTL and all expire at the same instant, so six cold reads hit the source permit API simultaneously, producing a load spike and HTTP 429 rate-limit errors. In the bottom timeline the same six keys carry a base TTL plus random jitter, so their expiries stagger across the window and the source API sees a smooth trickle of one refresh at a time, holding load flat and well under the quota. UNIFORM TTL · SYNCHRONIZED CLIFF time → 6 keys expire at 05:00 6 cold reads at once Source permit API 429 spike TTL + JITTER · STAGGERED REFRESH time → expiries spread across window one refresh at a time Source permit API flat load

Step 1: Mine the Hot Parcel Set From Access Logs

Warming only pays off if you warm the right keys. Parcel access is heavily skewed — a small set of parcels tied to active commercial projects and pending inspections absorbs most daytime reads — so the warm set should be derived from observed demand, not guessed. Parse the previous day’s lookup access log, count hits per parcel, and keep the top-N in a Redis sorted set that doubles as the manifest for the next warming run.

from __future__ import annotations

import re
from collections import Counter

import redis  # redis-py 5.x, sync client is fine for the offline miner

# Matches a logged lookup line: ... "GET /parcels/0142-007-031" 200 ...
_PARCEL_RE = re.compile(r"GET /parcels/(?P<pid>[0-9A-Z\-]{6,24})\b")


def rank_hot_parcels(log_path: str, r: redis.Redis, *, top_n: int = 2000) -> int:
    """Count parcel-lookup hits and store the ranked hot set in a Redis ZSET."""
    counts: Counter[str] = Counter()
    with open(log_path, encoding="utf-8", errors="replace") as fh:
        for line in fh:
            if m := _PARCEL_RE.search(line):
                counts[m["pid"]] += 1  # frequency = warming priority

    # Keep only the busiest parcels; warming the rarely-hit parcels wastes quota.
    hot = dict(counts.most_common(top_n))
    pipe = r.pipeline(transaction=False)
    pipe.delete("warm:parcels")                 # rebuild the set each cycle
    if hot:
        pipe.zadd("warm:parcels", hot)          # score = observed hit count
    pipe.execute()
    return len(hot)

Storing the ranked set in Redis (rather than a flat file) lets the warmer pull the top slice with a single ZREVRANGE and lets you promote seasonally hot parcels — spring roofing clusters, fiscal-year tenant-improvement filings — by nudging their scores. Where the source system exposes no queryable demand signal, seed the set from bulk captures produced by the ingestion track’s scraping and CSV-sync stages instead.

Step 2: Warm Redis With a Pipelined, Jittered Write

With the hot set ranked, fetch each parcel record from the source and write it to Redis. Two details make this production-grade. First, pipeline the writes: sending each SET as its own round-trip is the dominant cost when warming thousands of keys, and a single pipeline collapses them into one network flush. Second, add jitter to every TTL. If all keys share an identical TTL they expire on the same tick and the next read wave stampedes the source — exactly the failure the diagram above contrasts. A small random offset spreads expiries across a window so the source sees a trickle of refreshes, never a cliff.

import random

BASE_TTL = 900          # 15-minute hot-tier freshness window, in seconds
JITTER = 180            # +/- up to 3 minutes so keys never expire in lockstep


def parcel_key(pid: str) -> str:
    # Namespaced, deterministic, PII-free — safe to log and to scan.
    return f"parcel:lookup:{pid}"


def warm_parcels(
    r: redis.Redis,
    records: dict[str, bytes],   # {parcel_id: serialized record} from the source
) -> int:
    """Bulk-load parcel records with per-key jittered TTLs in one pipeline."""
    pipe = r.pipeline(transaction=False)  # batch writes, one network flush
    for pid, blob in records.items():
        # Jitter breaks TTL synchronization that would otherwise cause a stampede.
        ttl = BASE_TTL + random.randint(-JITTER, JITTER)
        pipe.set(parcel_key(pid), blob, ex=ttl)
    pipe.execute()
    return len(records)

Keep pipeline batches bounded (a few thousand commands) so a single execute() neither blocks the Redis event loop nor balloons client memory; chunk a large warm set into successive pipelines. The serialized blob should be a compact, validated projection that deliberately excludes applicant PII — there is no field to leak if the cached value never carried it.

Step 3: Choose Cache-Aside or Write-Through for the Read Path

Warming populates the cache proactively; the read path decides what happens on a miss and on a write. The two patterns solve different problems and municipal stacks usually blend them.

Cache-aside (lazy): readers check Redis first and, on a miss, source the record and backfill it. It is simple, resilient (a Redis outage degrades to direct sourcing rather than an error), and the natural default for parcel reads.

import msgpack


def get_parcel(r: redis.Redis, pid: str, source_fetch) -> dict:
    """Cache-aside read: serve from Redis, backfill on a miss."""
    cached = r.get(parcel_key(pid))
    if cached is not None:
        return msgpack.unpackb(cached)          # hit — sub-millisecond
    record = source_fetch(pid)                  # miss — one source round-trip
    ttl = BASE_TTL + random.randint(-JITTER, JITTER)
    r.set(parcel_key(pid), msgpack.packb(record), ex=ttl)  # lazy backfill, jittered
    return record

Write-through: when your own system mutates a parcel-linked record — a permit status change, a new inspection result — update Redis in the same code path that writes the database of record, so the cache never lags behind an authoritative write you control. Write-through fits mutations you originate; cache-aside fits reads whose source you only consume. The canonical zoning_code and parcel_id fields cached here must match the identifiers established in Best Practices for Linking Zoning Codes to Parcel IDs, so a warmed value agrees with the spatial layer it will be joined against.

Step 4: Invalidate on Permit Updates

A warm cache is only trustworthy if it evicts stale entries promptly. TTL alone bounds staleness to the freshness window; event-driven invalidation removes it. When the source emits an authoritative change for a parcel — a permit issued, a status transition, a re-zoning — delete the key and re-warm it immediately so the hot path stays populated without waiting out the TTL.

def invalidate_parcel(r: redis.Redis, pid: str, source_fetch) -> None:
    """Evict on an authoritative change, then re-warm just that key."""
    r.delete(parcel_key(pid))                   # remove the now-stale entry
    record = source_fetch(pid)                  # targeted refresh, not a full run
    ttl = BASE_TTL + random.randint(-JITTER, JITTER)
    r.set(parcel_key(pid), msgpack.packb(record), ex=ttl)


def bump_namespace(r: redis.Redis, version: int) -> None:
    """On a taxonomy edition change, roll the key prefix so old entries age out."""
    r.set("parcel:ns", version)  # readers compose keys as parcel:lookup:v{ns}:{pid}

Point invalidation (delete one key) handles per-record changes; namespace rolling handles bulk changes such as an annual code-edition update, where every cached zoning_code is suspect at once. Bumping a version prefix instantly orphans the entire old keyspace to natural expiry without a blocking FLUSH, which would drop the cache cold and hand you the stampede you warmed to avoid.

Parameter and Flag Reference

Parameter Type Default Municipal-context notes
BASE_TTL int (s) 900 15-minute hot window balances counter-hour freshness against source quota.
JITTER int (s) 180 +/- offset that de-synchronizes expiries; set to roughly 10–20% of BASE_TTL.
top_n int 2000 Size of the warmed hot set; cap near what one off-peak window can fetch inside quota.
pipeline batch int 2000 Commands per execute(); larger flushes cut round-trips but raise client memory.
parcel:ns int 1 Key-namespace version; bump on a taxonomy edition change to age out old entries.
read pattern enum cache-aside Cache-aside for consumed reads; write-through for mutations you originate.
maxmemory-policy Redis conf volatile-ttl Evict shortest-TTL keys first so warmed hot records outlive cold backfills under pressure.

Common Failure Patterns and Fixes

Synchronized TTLs cause a periodic stampede

Warming thousands of keys in one pass with an identical TTL makes them all expire on the same tick; every window boundary then fires a burst of cold reads at the source. Add per-key jitter (Step 2) so expiries spread, and prefer volatile-ttl eviction so the cache degrades gradually rather than in cliffs.

# WRONG: every key expires simultaneously -> stampede at t + BASE_TTL
pipe.set(parcel_key(pid), blob, ex=BASE_TTL)
# RIGHT: staggered expiry across a jitter window
pipe.set(parcel_key(pid), blob, ex=BASE_TTL + random.randint(-JITTER, JITTER))

Per-key round-trips make warming too slow to finish off-peak

Issuing one SET per key against a remote Redis spends nearly all wall-clock time in network latency, so a large warm set never completes inside the off-peak window. Batch writes into a pipeline; the fix is a single pipeline() / execute() around the loop, as in Step 2.

A stale entry survives an authoritative change

Relying on TTL alone means a re-zoning or issued permit stays wrong for up to the full window, which can drive an incorrect fee or missed setback. Wire event-driven invalidate_parcel into the write path so an authoritative change evicts and re-warms immediately rather than waiting out the TTL.

KEYS in production blocks the server

Scanning the keyspace with KEYS parcel:lookup:* to find entries to purge blocks Redis for every other client during the sweep. Use non-blocking SCAN with a cursor, or avoid the scan entirely by rolling the namespace prefix so old keys expire on their own.

# Non-blocking iteration; never use KEYS on a live instance.
for key in r.scan_iter(match="parcel:lookup:*", count=500):
    ...  # inspect or delete in bounded batches

Caching an error or partial body

A source that returns 200 with a truncated payload will poison the cache with a fast wrong answer. Validate the projection before writing and skip anything that fails schema checks — never cache a record you could not fully parse.

Audit and Logging Guidance

Every warming cycle should emit a structured record that a compliance officer can reconcile: the number of parcels warmed, source records fetched, quota consumed, the resulting hit/miss ratio on the next read window, and each invalidation event with its trigger. Log keys, never values — the parcel:lookup: namespace is deliberately PII-free, so it is safe to persist, whereas the cached record may not be. Record the active parcel:ns version alongside each run so an auditor can prove which taxonomy edition a cached value reflected at read time. Keep these run logs for the state-mandated retention period; they are the evidence that a served parcel lookup matched the authoritative source. When a warming run cannot reach the source during a maintenance window, defer rather than filling Redis with error payloads, and degrade reads through the ingestion track’s error handling and retry logic so the portal keeps serving from whatever remains warm.

Frequently Asked Questions

How much jitter should I add to parcel-lookup TTLs?

Roughly 10–20% of the base TTL. With a 15-minute (900 s) hot window, a +/- 180-second offset spreads expiries across a six-minute band — enough to turn a synchronized cliff into a smooth trickle without letting any record drift meaningfully past its freshness target. Scale the jitter with the base TTL, not as a fixed constant.

Should parcel reads use cache-aside or write-through?

Use cache-aside for reads whose source you only consume, because it degrades safely to direct sourcing if Redis is down and backfills misses automatically. Reserve write-through for mutations your own system originates — an issued permit or a recorded inspection — where you can update Redis in the same transaction that writes the database of record so the cache never trails an authoritative write you control.

How do I warm without exhausting the county API quota?

Rank the hot set from access logs and warm only the top slice, run inside the off-peak window when quotas reset, and stop cleanly when the daily budget nears its limit. Because the set is demand-ranked, a partial run still covers the busiest parcels first, and jittered TTLs keep the steady-state refresh load flat rather than spiky.