Skip to content

Apollo Client: The Normalized Cache and Optimistic Updates

HTTP caching is possible with GraphQL too, but for client state it is often less direct. That is why Apollo normalizes objects and supports optimistic updates in the UI.

≈ 11 min readSoftwareGraphQLAPI

If you store whole GraphQL responses under a hashed query string, you haven’t built a cache but a collection of copies. When a user changes their name, these copies know nothing about each other: the list view keeps showing the old value, the detail view already shows the new one, and nobody notices until someone clicks back and forth. With GraphQL, the key under which a response is stored is the real problem – and the solution lies one level deeper than the response itself.

This post is exclusively about the cache in the browser, that is, the client. There is also server-side caching – request batching and deduplication with DataLoader, for example – but that is a completely different construction site with different goals. Here we are talking about the InMemoryCache of Apollo Client 3, about normalization, about optimistic updates, and about the one pitfall that can easily cost you half an hour of debugging.

Why the URL alone isn’t enough as a cache key#

With a classic REST API, caching is conceptually simple. Every resource has its own URL, and a GET /users/1 always returns the same slice. The browser, a CDN, or an HTTP cache layer can store the response under exactly that URL and return it on the next call. The key is the address.

With many GraphQL APIs, different queries share one endpoint, and they often run as POST /graphql. That doesn’t rule out classic HTTP caching: GET requests, the query body as part of the cache key, or persisted queries can make responses cacheable. For the state of an interactive application, though, a pure response cache stays unwieldy as soon as the same entity shows up in several queries and needs to be updated in a targeted way.

The case where this becomes visible: a list view loads all users, a detail view loads a single user. Both show the name of User:1. If this user changes their name, a response-based cache would have to invalidate both entries separately – and the cache would first have to know that the same object is inside both responses. That is exactly what a pure response cache can’t do.

Normalization: one object, once, with a stable identity#

Apollo’s answer to this is normalization. Instead of storing whole responses, the InMemoryCache breaks every response down into its individual objects and stores each object exactly once – flat, under a stable cache ID. By default, Apollo forms this ID from two fields: the __typename and the object’s primary key. The result looks like User:1 or Product:42.

By default, Apollo uses id as the key field, and if that doesn’t exist, _id. If both are missing and nothing else is configured, something important happens that I will come back to below: the object isn’t normalized but embedded inline in the parent object.

The effect of normalization is best shown with the case just mentioned. Two queries, one shared object:

graph TD
  QA["Query GET_USERS<br/>(Listenansicht)"] --> N["User:1<br/>{ name, email }"]
  QB["Query GET_USER<br/>(Detailansicht)"] --> N
  N --> S[("Normalisierter<br/>InMemoryCache")]

Both queries point to the same node User:1. The user is stored exactly once. If their name changes, it changes for all views that point to this node. That is the core everything else revolves around.

For this to work, every query has to select the identity fields as well. Apollo adds __typename automatically, but we have to request id ourselves:

query GET_USERS {
  users {
    id
    name
    email
  }
}

query GET_USER($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}

Setting up the cache itself is unspectacular. You instantiate an InMemoryCache and pass it to the ApolloClient:

import { ApolloClient, InMemoryCache, HttpLink } from "@apollo/client";

const client = new ApolloClient({
  link: new HttpLink({ uri: "/graphql" }),
  cache: new InMemoryCache(),
});

Here is how I sum up what normalization actually brings:

  • Every entity is stored exactly once in memory, no matter how many queries loaded it.
  • A field update in one place automatically propagates to every view that shows the same object – without manual invalidation.
  • The cache gets smaller and more consistent, because duplicate data collapses into one reference.
  • The UI can render data from the cache immediately and refetch in the background without different views drifting apart.

Field updates happen automatically, structural updates don’t#

This is where, in practice, what Apollo does for us separates from what we have to handle ourselves. The difference matters because it clears up the most common confusion.

If I change the value of a field on an object that is already cached, Apollo handles it automatically. A mutation that returns User:1 with a new name overwrites the field in the store, and every view updates. I don’t have to write anything for that – provided the mutation also returns id and __typename, so that Apollo knows which entry to hit.

const UPDATE_USER = gql`
  mutation UpdateUser($id: ID!, $name: String!) {
    updateUser(id: $id, name: $name) {
      id
      name
    }
  }
`;

// Apollo matches the response onto User:1 and updates
// every view that shows this user - no update function needed.
const [updateUser] = useMutation(UPDATE_USER);

It looks different when the structure changes, that is, when an element is added to a list or removed from it. If I create a new user via a mutation, Apollo dutifully normalizes the new object into the store – but it doesn’t know which list this user belongs to. Membership in a particular GET_USERS query isn’t a property of the object, and that is why Apollo can’t guess it. The result: the new object exists in the cache but doesn’t show up in the list view until you reload.

For these cases, there is the update function on the mutation. It receives the cache and the response and explicitly extends the list:

const ADD_USER = gql`
  mutation AddUser($name: String!) {
    addUser(name: $name) {
      id
      name
    }
  }
`;

const [addUser] = useMutation(ADD_USER, {
  update(cache, { data }) {
    const newUser = data.addUser;
    cache.modify({
      fields: {
        users(existingRefs = [], { toReference }) {
          return [...existingRefs, toReference(newUser)];
        },
      },
    });
  },
});

So the dividing line runs exactly here: Apollo handles value changes, we handle list membership.

Optimistic updates: the UI reacts before the server responds#

The second big topic is perceived speed. Every mutation goes over the network, and even 150 milliseconds feel sluggish for a toggle button. Optimistic updates solve this by writing the expected end state into the cache immediately – before the server has responded. The UI reacts without latency. When the real response arrives, it replaces the optimistic layer. If the mutation fails, Apollo automatically discards the optimistic layer and restores the previous state. That is the crucial point: you don’t have to write the rollback yourself.

The flow is easy to show as a sequence:

sequenceDiagram
  participant UI
  participant Cache
  participant Server
  UI->>Cache: optimistisches Ergebnis schreiben
  Cache-->>UI: sofort neu rendern
  UI->>Server: Mutation senden
  alt Erfolg
    Server-->>Cache: echtes Ergebnis schreiben
  else Fehler
    Server-->>Cache: optimistische Schicht verwerfen
    Cache-->>UI: vorigen Zustand wiederherstellen
  end

In code, it looks like this. A todo can be checked off, and we write the completed state optimistically:

const TOGGLE_TODO = gql`
  mutation ToggleTodo($id: ID!, $completed: Boolean!) {
    toggleTodo(id: $id, completed: $completed) {
      id
      completed
    }
  }
`;

const [toggleTodo] = useMutation(TOGGLE_TODO, {
  optimisticResponse: {
    toggleTodo: {
      __typename: "Todo",
      id: todo.id,
      completed: !todo.completed,
    },
  },
});

Two things are non-negotiable here. First, the optimisticResponse must have the same shape as the real server response – the same fields, the same nesting. Second, it must contain __typename and the key fields. Without __typename and id, Apollo can’t normalize the optimistic entry onto Todo:..., the merge hits the wrong target, and the rollback behaves unexpectedly. This is one of those bugs that happen silently: it looks almost right, but the UI flickers or jumps back.

If you like, you can also write optimisticResponse as a function that receives the variables – handy when the optimistic state is derived from the mutation arguments:

optimisticResponse: (vars) => ({
  toggleTodo: {
    __typename: "Todo",
    id: vars.id,
    completed: vars.completed,
  },
}),

fetchPolicy: how much say the cache has#

One detail that easily gets lost here is a query’s fetchPolicy. It controls the relationship between the cache and the network. The default is cache-first: Apollo looks in the cache first, and only if the data is missing does it go to the network. That is usually exactly right, and it is the reason why the second detail view of a user who has already been loaded gets by without a request.

The most important values you should know:

  • cache-first – default; cache first, network only when data is missing.
  • cache-and-network – renders from the cache immediately and fetches fresh data in parallel; good for lists that should be current but may show something right away.
  • network-only – ignores the cache when reading but writes the result to the cache.
  • no-cache – doesn’t read from or write to the cache at all; the data exists only within this query.
  • cache-only – cache only, never network; throws if nothing is there.

I leave the default in place until there is a concrete reason to change it. cache-and-network is the most common deliberate choice, because it combines the best of both: immediately visible and still fresh.

The pitfall: objects without a stable identity#

Now to the problem I announced above – one that goes unnoticed for a long time because it never reports itself. Normalization only works if Apollo can form a stable identity. If id and _id are missing and no alternative key field is configured, Apollo doesn’t normalize the object. Instead, it silently embeds it in the parent object. No error, no warning in the console – the app runs, but the cache doesn’t do what you expect.

The symptoms show up later and seem unrelated: the same entity is in the cache several times, an update hits only one copy, and two views show different values for the same thing. This happens especially often with computed or aggregated fields, with wrapper types from pagination, or with objects whose id you simply forgot to select in the query. If you work with cursor-based paging, you know wrapper types like these from practice – I covered the topic in more detail in GraphQL pagination.

There are two clean solutions. The simplest: just request the identity field as well. Often the id is there; it just wasn’t in the selection. If the type really has no id key but another unique field – an article number, say – you tell Apollo via typePolicies and keyFields:

const cache = new InMemoryCache({
  typePolicies: {
    Product: {
      keyFields: ["upc"],
    },
    Book: {
      keyFields: ["isbn"],
    },
  },
});

keyFields can be more than just a replacement field:

  • keyFields: ["upc"] – an alternative key field instead of id.
  • keyFields: ["name", "email"] – a composite key made up of several fields.
  • keyFields: [] – a singleton with exactly one entry per type (such as a global Settings type).
  • keyFields: false – deliberately turn off normalization for this type when embedding is what you want.

As a side note: in Apollo Client 2, you used dataIdFromObject for this. In version 3, it still exists to ease migration, but it is the old way. For new code, typePolicies with keyFields are the right choice, because they can be configured precisely and locally per type instead of globally through a single function.

A related case where identity decides things on the server is authorization: who may see which object at all doesn’t belong in the client cache but in the Resolver context. How I anchor that there is described in GraphQL auth in the context.

What should stick#

GraphQL can cache HTTP responses; in the browser, Apollo solves a different problem. The client normalizes entities at the object level so that several queries share the same instance and targeted field updates stay consistent. Structural changes to lists remain our job via the update function. Optimistic updates react immediately and roll back on errors, as long as the optimisticResponse has the right shape, including __typename. The most common silent bug remains an object without a stable identity that doesn’t get normalized. Consistent IDs and deliberately set keyFields save a lot of debugging here.

Further reading#

Revised and translated from German with the help of AI.