Cache key

The cache key is the identifier a cache builds to store and look up a response — typically host + path + query string, optionally extended by headers, cookies or geo attributes. Two requests share a cache entry only if their keys match exactly. Most "why is my hit ratio terrible?" stories end at the cache key.

What goes into the key

default key   = host + path + query string
custom key    = default ± query params ± headers ± cookies ± device/geo

CDNs let you customize this per route: ignore marketing parameters, include a language header, key on a device-type bucket. Everything you add multiplies the number of entries; everything you ignore merges requests into one entry.

The classic failure: query-string noise

These four URLs are one page but four cache keys:

/product/42
/product/42?utm_source=newsletter
/product/42?utm_source=x&utm_campaign=july
/product/42?fbclid=IwAR3…

Every ad click and tracking link becomes a cache miss — each 3.5× slower than a hit at the median, per our production data. The fix is to strip known tracking parameters from the cache key (most CDNs support ignore-lists) or normalize/sort query strings, so all variants collapse into one hot entry.

Key design rules of thumb

• Only include what changes the response. Any component that doesn't affect the bytes just splits your cache.
• Prefer enumerable buckets over raw values — a mobile|desktop flag, not the User-Agent string (see Vary header for how raw headers explode).
• Remember: purge and warm operate on keys, not URLs. A purge of /product/42 may leave variant keys alive, and warming must request each variant you actually serve.

To see how a specific URL behaves at the edge — including whether query variants hit the same entry — test it with the cache checker.