GraphQL Cache

Every remote in a shell reads from one Apollo cache. The shell builds one client with createApolloClient, and createPreparedInMemoryCache (packages/util-apollo/src/cache.ts) creates its InMemoryCache. That cache sets only possibleTypes, from the schema's introspection, so fragments on interfaces and unions match. There are no typePolicies or keyFields today, so every type uses Apollo's default identity.

The examples on this page are illustrative. Message, messageAdded, and resolveChatroom aren't in the vendored schema, and the real Chatroom.messages is a paginated connection rather than a plain list, so check names and shapes against packages/data-gql/src/schema.graphql before copying.

InMemoryCache stores each object that has a __typename and an id (or _id) once, under the key Typename:id, for example Chatroom:42. Every query, fragment, mutation, and subscription result that contains Chatroom:42 reads and writes that one entry. That is what makes updates show up everywhere without extra code.

useFragment reads a fragment for one entity straight from the cache. It returns complete: true only when every field of the fragment is there; otherwise complete is false, data is partial, and missing says which fields are absent. There is no error. A component that checks complete (as it must) renders nothing. The usual causes, in order:

missing names the absent fields. Read it in the debugger before guessing. Don't cast your way past complete. If the data can arrive later, useSuspenseFragment suspends until it is complete instead.

The cache APIs are never masked: readFragment, writeFragment, updateQuery, updateFragment, and modify see and write whole objects, whatever the components' fragments hide.

When a mutation or subscription returns an entity with its id and the fields that changed, Apollo writes the result to the cache and merges those fields into the existing entry. Every query and fragment that reads them re-renders. Subscriptions do this too: a useSubscription result is written to the cache before your component sees it (unless fetchPolicy is "no-cache").

Select every field the mutation changes. A field you leave out keeps its old value in the cache.

Apollo can't know that a new message belongs in Chatroom.messages, or that a deleted one has left it. Change the list field with cache.modify, and de-duplicate by reference. The same entity can arrive twice: from a subscription and from your own mutation, or from a refetch.

When the change is easier to describe as "this query's result, but different", updateQuery reads the cached result, passes it to your function, and writes back the new object you return. The data it passes is read-only, so build new objects rather than mutating it; return nothing to leave the cache as it is.

It changes only that query with those variables. To change a list wherever it appears, use modify on the owning entity's field. cache.updateFragment is the same tool for one entity's fragment.

writeFragment writes a fragment's fields for one entity, for example data that arrived outside GraphQL. Include __typename and id, or pass from (or id) to say which entity it is. It returns the entity's reference. A fragment used only for writeFragment is fine; it doesn't need a component.

refetchQueries sends the queries again and replaces their results. It costs a round trip, and the user waits for it, but it is right when the client can't compute the answer:

Pass the Documents, not their names as strings: a name with a typo refetches nothing, with only a development warning (Unknown query named …). Set awaitRefetchQueries: true when the mutation should stay loading until the refetch finishes. Prefer a cache update when the mutation already returns everything you need.

evict removes the entity. Lists that referenced it drop the dangling reference automatically when they're read, so you don't need to edit each list. A single (non-list) field that pointed at the entity becomes missing, and a cache-first query that reads it fetches again. cache.gc() then removes everything nothing can reach any more.

cache.evict({ id, fieldName: "messages" }) removes one field instead. Each active query that reads it fetches it again. That's a precise way to say "this list is stale" without refetching everything.

Apollo writes the optimistic result to a separate layer, renders it at once, and replaces it with the server's answer. If the mutation fails, it discards the layer and the UI goes back by itself. You still show the failure (see Error Handling). The optimistic object must have the shape of the mutation's whole result, including __typename and id. Masking doesn't apply to it. optimisticResponse can also be a function (variables, { IGNORE }) => …; return IGNORE to skip the optimistic update for that call. A mutation's update function runs for the optimistic result and again for the server's, so a list change made there must be idempotent: de-duplicate as above.

A type policy is configuration on InMemoryCache: keyFields for identity, and fields with read and merge functions per field. We have none. The rules if you need one:

renderWithApollo (from @prepared911/util-testing) builds a real client with createApolloClient, so tests use the same cache as the app: createPreparedInMemoryCache, possibleTypes, data masking, and cache-first queries.