Surrogate Keys
Surrogate keys are cache tags attached to responses so a CDN can purge every object related to an entity in one call instead of enumerating thousands of URLs.
Definition
A surrogate key is a label, sent in a response header such as Surrogate-Key or Cache-Tag, that associates a cached object with one or more logical entities, letting the cache invalidate all objects sharing a tag without knowing their URLs.
Context and scope
Use it when a single content change affects many cached URLs, such as a product appearing on category, search, and recommendation pages.
Common misconceptions
- Surrogate keys replace URLs in the cache key; they are purge handles, not lookup keys
- Purging a tag is instant everywhere; propagation across edge locations takes time
- Any number of tags is free; tag cardinality has real cost and limits
Anti-patterns
- Tagging objects with per-request or per-user identifiers, creating millions of tags
- Forgetting to tag a new page template, so stale content survives purges
- Relying on tags alone when the origin has no invalidation event to trigger them
Related concepts
Related examples
Authoritative source
https://developer.fastly.com/reference/http/http-headers/Surrogate-Key/
Tagging cached objects
A surrogate key is metadata attached to a cached response that names the logical entities it represents. One HTML page might carry Surrogate-Key: product-123 category-shoes home-featured. The cache indexes those labels and can later remove every object bearing a given label, regardless of URL.
How it works
The origin emits the tag header when generating the response. The CDN stores the tags alongside the object. When a product changes, the backend calls the purge API with the key product-123, and the CDN invalidates every object carrying it. This turns invalidation from a URL enumeration problem into a graph lookup.
The hard part is consistency: every template that renders the entity must emit the same tags. A missing tag creates a stale object that no purge reaches. Teams usually centralize tag generation in one helper so templates cannot drift.
When to use it
Tags shine when content is fanned out across listing pages, search results, feeds, and personalized shells. They are also useful for “purge everything about this tenant” operations. For a single URL with no fan-out, plain URL purging is simpler and easier to reason about.
Trade-offs
Tags add a small header per response and an index entry per tag, so cardinality matters. Per-user tags can explode into millions of labels and slow purges. Propagation is eventually consistent, so a purge may take seconds to reach every edge. Vendor APIs and limits differ, which complicates multi-CDN setups.
Example and misconceptions
A retailer changes a price. The origin purges product-123, and the category page, the search fragment, and the recommendation carousel all refresh from one call. Without tags, the team would have to compute and purge hundreds of URLs and still miss some.
The common misconception is that tags are part of the cache key. They are not: two requests still resolve by URL and Vary, and tags only describe what to purge later.
Related concepts: Content Delivery Network, Cache Keys, and Cache Invalidation.