Response and Field-level Caching

One Endpoint, Infinite Keys

HTTP caching was designed around resources identified by URLs. GraphQL gives you one URL, a POST body that changes per request, and a response assembled from fields with wildly different freshness: a published article is immutable for a year, its comment count changes by the minute, and the "recommended for you" block must never be stored by anything shared.

Leaving it all uncacheable wastes the best cache you have. Field-level cache hints solve it by turning the response's freshness into a function of its parts:

type Article {
  id: ID!
  body: String!      @cacheControl(maxAge: 600, scope: PUBLIC)
  publishedAt: Date! @cacheControl(maxAge: 600, scope: PUBLIC)
  commentCount: Int! @cacheControl(maxAge: 60)
}
type Query {
  article(slug: String!): Article
  recommendations: [Article!]! @cacheControl(maxAge: 30, scope: PRIVATE)
}

The rules the server applies when it builds the header:

So { article { body commentCount } } answers with Cache-Control: public, max-age=60 — the minimum of 600 and 60, because a response is only as fresh as its stalest-needed field. Add recommendations to the same document and the header drops to private, max-age=30, which shared caches must not store at all.

The lesson inside the lesson: caching decisions belong at the field where the freshness knowledge lives, and they propagate upward. A client cannot know that commentCount expires in a minute, and a CDN cannot see inside the response body — the header is the only channel that carries field-level truth to the layers above.

Choosing a Layer for Each Read Pattern

There are three caches in a federated stack and they answer different questions. Reaching for the wrong one is how teams end up with stale personalized data or a CDN that never hits.

The per-request loader is the one people misuse: a DataLoader lives for exactly one request and exists to collapse duplicates and N+1 patterns, not to remember anything. It expires at the end of the response, by design.

Entity caching at the gateway pays off when many clients converge on the same objects — a home page where every visitor requests the same fifty products. The key must include the field set, because "product with price" and "product with price and stock" are different entries; a key that omits the selection serves truncated data. Keep the TTL short (seconds, not minutes) and treat it as a latency optimisation rather than a source of truth, because the subgraph underneath will keep writing.

The CDN layer only works once requests are GET-addressable, which is the whole point of the hash-based approach in persisted queries and CDN: the query id plus canonicalized variables gives the CDN a stable URL per document-plus-arguments pair, and the cache-control rules from the previous chapter decide whether that URL is storable at all.

Invalidation, Personalization, and Poisoning

Nothing caches correctly until you can say what happens when the data changes. Three mechanisms, in increasing order of machinery:

1. Short TTL. Works when staleness of seconds is acceptable — comment counts, feeds, dashboards. Costs nothing, guarantees eventual freshness, and is the right default until something complains.
2. Tag-based purge. Tag each cached entry with the entities it contains (Cache-Tag: article-123, Surrogate-Key), then purge article-123 on mutation. One tag invalidates every query, page, and variant that touched the article, which is the only scalable answer when thousands of distinct documents embed the same row.
3. Entity write-through. The subgraph that mutates an entity evicts or rewrites the gateway's entity-cache entry for that type and id. Precise, but only works inside a federated topology where the gateway can be told what changed.

Personalization is a header problem, not a key problem. The tempting fix is Vary: Authorization, which turns every token into its own cache copy — your hit ratio collapses to roughly zero while you still pay for the storage. Instead: mark the personalized fields scope: PRIVATE, let the response go out as private, no-store, and keep shared layers serving only documents composed entirely of public fields.

Never cache a failure. A 200 carrying entries in errors[], a partially nulled response after a subgraph timeout, or a cost rejection replayed for ten minutes turns a transient incident into a sustained one. The rule: cache only responses with data and no errors, and make sure Set-Cookie is absent from anything cacheable — a cookie on a shared response both fragments the cache and leaks sessions between users.

Finally, remember what sits outside all of this: subscriptions deliver over SSE or WebSocket and have no URL to cache against, so realtime paths need delivery semantics of their own rather than borrowed HTTP headers.