Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 37 ยท Security and Performance

Caching and Performance

Why HTTP caching is harder with GraphQL, and how persisted queries, response and field caches, normalized client caches and resolver timing fix it.

REST gets a lot of caching for free: every resource has a URL, GET responses are cacheable, and browsers, CDNs and proxies already know what to do. GraphQL usually sends one POST to one URL, with the query in the body. To a CDN, every request looks identical, and POST responses are not cached by default. So you have to put caching somewhere else, and you have several good options.

This lesson walks through the layers, from the network to the resolver to the browser. The real HTTP behavior, server settings and client libraries are shown as read-only code, because no GraphQL server runs on this site. The runnable examples are stand-ins: a hand-written resolver cache and a timing wrapper in plain Node, so you can see the ideas work.

Where can you cache?

CDN Whole responses, by URL.
Server Whole responses or single fields.
Data layer Rows and lookups, e.g. DataLoader.
Client A normalized store of objects.

Pick the layer that matches how stale the data may be.

1 / 2

HTTP caching and why POST gets in the way

A CDN caches a response by its URL (plus a few headers such as Vary). With the default transport in GraphQL over HTTP, the query is in a POST body, so every request has the same URL. Most CDNs do not cache POST at all, and those that can must hash the body.

Two practical fixes:

  1. Persisted queries over GET. The client sends only a short ID and the variables in the URL:

    TEXT
    GET /graphql?id=7f3a9c&variables=%7B%22slug%22%3A%22intro%22%7D
    

    Now each distinct operation and variable set has its own URL, which a CDN can cache. The same IDs also act as an allow-list, as described in Query Depth, Complexity and Other Attacks.

  2. Cache hints in the response. Servers can compute a Cache-Control header from the schema: each field gets a maximum age and a scope, and the response gets the smallest age among all fields it contains.

    GRAPHQL
    # shape only: directive syntax depends on your server library
    type Query {
      topPosts: [Post!]! @cacheControl(maxAge: 300)
      me: User @cacheControl(maxAge: 0, scope: PRIVATE)
    }
    

    A query that touches me is private and uncacheable at a shared CDN, even if the rest is public.

Never serve responses that depend on the logged-in user from a shared cache. Public pages cached at a CDN must come from queries that look identical for everyone. Per-user data belongs in separate, private requests.

Response and field caching on the server

Inside the server you can cache at two granularities:

  • Whole-response cache: key = operation + variables (+ user or role), value = the JSON response. It is fast to read and very effective for hot public queries, but any change in the data makes the whole entry stale.
  • Field or resolver cache: key = something like Product:42:price. Only the expensive resolvers cache; everything else runs normally. Entries can have different lifetimes, and an update can remove exactly the affected keys.

Both need an invalidation plan. Time to live (TTL) is the simplest: accept that data may be a little old. For data that must be fresh, delete keys when mutations succeed, or publish an event that other servers listen to.

The stand-in below caches an expensive resolver with a TTL. A fake clock keeps the output deterministic, and a counter shows how many times the "database" was actually hit.

Node.js A stand-in resolver cache with TTL

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The first read at t=0 goes to the database, the read at t=30 is served from the cache, and p2 has its own key. At t=61 the entry for p1 has expired, so the value is refreshed (and notice the price changed: that is the staleness you accepted in exchange for speed).

Remember that caching the resolver is different from the per-request cache inside a DataLoader (see The N+1 Problem and DataLoader). A DataLoader's cache lives for one request and prevents duplicate lookups; a resolver cache lives across requests and needs invalidation.

Client caches and normalization

GraphQL clients such as Apollo Client and urql keep an in-memory cache in the browser. A document cache stores each response by query and variables. A normalized cache is smarter: it splits every response into individual objects and stores each one under a key built from its __typename and id:

TEXT
User:1  -> { id: "1", name: "Ada", email: "[email protected]" }
Post:7  -> { id: "7", title: "Hello", author: -> User:1 }

That is why GraphQL queries should always select id and __typename (many clients add them automatically). When a mutation returns User:1 with a new name, every query on screen that displays that user updates at once. This is also why schema design favors globally unique, stable IDs. Client libraries get a closer look in Clients, Apollo and Code Generation.

Making responses faster, not just cached

Before caching anything, find what is slow:

  • Fix N+1 first. Batching with a DataLoader often beats any cache.

  • Select only what you need. A resolver can look at the requested fields (the info argument, see Resolvers) and fetch only those columns.

  • Paginate. Never return unbounded lists. See Pagination: Offset, Cursor and Connections.

  • Use incremental delivery for slow parts. The @defer and @stream directives (still evolving, and supported by only some servers and clients) let a server send the fast part of a response first and the slow part later:

    GRAPHQL
    query ProductPage {
      product(id: "42") {
        name
        price
        ... @defer {
          recommendations { name }
        }
      }
    }
    

    The page can render the name and price immediately while recommendations arrive in a later chunk. Treat this as an advanced option and check your server and client versions.

Measuring resolver time

You cannot tune what you cannot see. Wrap resolvers (or use your server's tracing plugin) to record how long each field takes, then look at the slowest fields and the most frequent ones. The stand-in below wraps every resolver in a map and records timings with a fake clock, so the numbers are repeatable.

Node.js A stand-in resolver timing wrapper

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The table shows that Post_comments was called three times and cost more in total than you might guess from one call. That "many calls to one field" pattern is the signature of N+1. Real servers expose the same data through tracing plugins and OpenTelemetry, and you should always name your operations so slow ones are easy to find in logs.

A practical order of attack

  1. Name every operation and log duration per operation.
  2. Fix N+1 and add pagination caps.
  3. Add TTL caches to the few expensive, shareable fields.
  4. Use persisted queries over GET with a CDN for public, read-heavy pages.
  5. Use a normalized client cache for snappy UIs.
  6. Consider incremental delivery only after the basics.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is a CDN usually unable to cache a default GraphQL request?

    CDNs key on the URL, and POST bodies are generally not cached. Persisted queries over GET give each operation its own URL.
  2. 2. A response includes fields with maxAge 300, 60 and 0. What Cache-Control max-age should the whole response get?

    The response is only as fresh as its least cacheable field, so the smallest max-age wins. Here that means no caching.
  3. 3. What does a normalized client cache use as the key for an object?

    Storing objects by type and ID lets one update refresh every query that shows the object.
  4. 4. What is the main difference between a DataLoader cache and a resolver cache with a TTL?

    DataLoader deduplicates and batches within a single request. A TTL cache is shared between requests and therefore needs an expiry or invalidation plan.

Summary

  • Default GraphQL traffic (POST to one URL) is invisible to CDNs; persisted queries over GET and cache hints fix that.
  • Server caches can store whole responses or single fields; plan invalidation with TTLs or events.
  • Normalized client caches key objects by __typename and id, so one mutation updates every view.
  • Fix N+1 and unbounded lists before adding caches.
  • @defer and @stream are advanced, evolving options for slow parts of a response.
  • Measure resolver time per field and per operation name before you tune.
  • The cache and timing code here is stand-in code; real servers use tracing and caching plugins.

Next: GraphQL over HTTP.