Join us for GraphQL Summit, October 10-12 in San Diego. Use promo code ODYSSEY for $400 off your pass.
Launch GraphOS Studio

Advanced topics on caching in Apollo Client

This article describes special cases and considerations when using the Apollo Client cache.

Bypassing the cache

Sometimes you shouldn't use the cache for a particular GraphQL . For example, a query's response might be a token that's only used once. In cases like this, use the no-cache fetch policy:

const { loading, error, data } = useQuery(GET_DOGS, {
fetchPolicy: "no-cache"

s that use this fetch policy don't write their result to the cache, and they also don't check the cache for data before sending a request to your server. See all available fetch policies.

Persisting the cache

You can persist and rehydrate the InMemoryCache from a storage provider like AsyncStorage or localStorage. To do so, use the apollo3-cache-persist library. This library works with a variety of storage providers.

To get started, pass your cache and a storage provider to persistCache. By default, the contents of your cache are immediately restored asynchronously, and they're persisted on every write to the cache with a short configurable debounce interval.

Note: The persistCache method is async and returns a Promise.

import AsyncStorage from '@react-native-async-storage/async-storage';
import { InMemoryCache } from '@apollo/client';
import { persistCache } from 'apollo3-cache-persist';
const cache = new InMemoryCache();
storage: AsyncStorage,
}).then(() => {
// Continue setting up Apollo Client as usual.

For advanced usage and additional configuration options, see the README of apollo3-cache-persist.

Resetting the cache

Sometimes, you might want to reset the cache entirely, such as when a user logs out. To accomplish this, call client.resetStore. This method is asynchronous, because it also refetches any of your active queries.

import { useQuery } from '@apollo/client';
function Profile() {
const { data, client } = useQuery(PROFILE_QUERY);
return (
<p>Current user: {data?.currentUser}</p>
<button onClick={async ()=>client.resetStore()}>
Log out

To reset the cache without refetching active queries, use client.clearStore() instead of client.resetStore().

Responding to cache resets

You can register callback functions that execute whenever client.resetStore is called. To do so, call client.onResetStore and pass in your callback. To register multiple callbacks, call client.onResetStore multiple times. All of your callbacks are added to an array and are executed concurrently whenever the cache is reset.

In this example, we use client.onResetStore to write default values to the cache. This is useful when using Apollo Client's local state management features and calling client.resetStore anywhere in your application.

import { ApolloClient, InMemoryCache } from '@apollo/client';
import { withClientState } from 'apollo-link-state';
import { resolvers, defaults } from './resolvers';
const cache = new InMemoryCache();
const stateLink = withClientState({ cache, resolvers, defaults });
const client = new ApolloClient({
link: stateLink,

You can also call client.onResetStore from your React components. This can be useful if you want to force your UI to rerender after the cache is reset.

The client.onResetStore method's return value is a function you can call to unregister your callback:

import { useApolloClient } from '@apollo/client';
function Foo (){
const [reset, setReset] = useState(0);
const client = useApolloClient();
useEffect(() => {
const unsubscribe = client.onResetStore(() =>
new Promise(()=>setReset(reset + 1))
return () => {
return reset ? <div /> : <span />
export default Foo;

TypePolicy inheritence

JavaScript developers will be familiar with the idea of inheritance from the extends clause of class declarations, or possibly from dealing with prototype chains created by Object.create.

Inheritance is a powerful code-sharing tool, and it works well with Apollo Client for several reasons:

  • InMemoryCache already knows about the supertype-subtype relationships (interfaces and unions) in your , thanks to possibleTypes, so no additional configuration is necessary to provide that information.

  • Inheritance allows a supertype to provide default configuration values to all its subtypes, including keyFields and individual policies, which can be selectively overridden by subtypes that want something different.

  • A single subtype can have multiple supertypes in a GraphQL , which is difficult to model using the single inheritance model of classes or prototypes. In other words, supporting multiple inheritance in JavaScript requires building a system something like this one, rather than just reusing built-in language features.

  • Developers can add their own client-only supertypes to the possibleTypes map, as a way of reusing behavior across types, even if their knows nothing about those supertypes.

  • The possibleTypes map is currently used only for matching purposes, which is an important but fairly small part of what the client does. Inheritance adds another compelling use for possibleTypes, and should drastically reduce repetition of typePolicies when used effectively.

Here's how type policy inheritance works for InMemoryCache, considering the example below:

const cache = new InMemoryCache({
possibleTypes: {
Reptile: ["Snake", "Turtle"],
Snake: ["Python", "Viper", "Cobra"],
Viper: ["Cottonmouth", "DeathAdder"],
typePolicies: {
Reptile: {
// Suppose all our reptiles are captive, and have a tag with an ID.
keyFields: ["tagId"],
fields: {
// Scientific name-related logic can be shared among Reptile subtypes.
scientificName: {
merge(_, incoming) {
// Normalize all scientific names to lower case.
return incoming.toLowerCase();
Snake: {
fields: {
// Default to a truthy non-boolean value if we don't know
// whether this snake is venomous.
venomous(status = "unknown") {
return status;

Refetching queries after a mutation

In certain cases, writing an update function to update the cache after a mutation can be complex, or even impossible if the doesn't return modified s.

In these cases, you can provide a refetchQueries option to the useMutation hook to automatically rerun certain queries after the completes.

For details, see Refetching queries.

Note that although refetchQueries can be faster to implement than an update function, it also requires additional network requests that are usually undesirable. For more information, see this blog post.

Cache redirects

In some cases, a query requests data that already exists in the cache under a different reference. For example, your UI might have a list view and a detail view that both use the same data.

The list view might run the following query:

query Books {
books {

When a specific book is selected, the detail view might display an individual item using this query:

query Book($id: ID!) {
book(id: $id) {

In a case like this, we know that the second query's data might already be in the cache, but because that data was fetched by a different query, Apollo Client doesn't know that. To tell Apollo Client where to look for the cached Book object, we can define a policy read function for the book :

import { ApolloClient, InMemoryCache } from '@apollo/client';
const client = new ApolloClient({
cache: new InMemoryCache({
typePolicies: {
Query: {
fields: {
book: {
read(_, { args, toReference }) {
return toReference({
__typename: 'Book',

This read function uses the toReference helper utility to generate and return a cache reference for a Book object, based on its __typename and id.

Now whenever a query includes the book , the read function above executes and returns a reference to a Book object. Apollo Client uses this reference to look up the object in its cache and return it if it's present. If it isn't present, Apollo Client knows it needs to execute the query over the network.

⚠️ Note: To avoid a network request, all of a query's requested s must already be present in the cache. If the detail view's query fetches any Book that the list view's query didn't, Apollo Client considers the cache hit to be incomplete, and it executes the full query over the network.

Pagination utilities

Incremental loading: fetchMore

You can use the fetchMore function to update a query's cached result with data returned by a followup query. Most often, fetchMore is used to handle infinite-scroll pagination and other situations where you're loading more data when you already have some.

For details, see The fetchMore function.

The @connection directive

Fundamentally, paginated queries are the same as any other query with the exception that calls to fetchMore update the same cache key. Because these queries are cached by both the initial query and their parameters, a problem arises when later retrieving or updating paginated queries in the cache. We don't care about pagination s such as limits, offsets, or cursors outside of the need to fetchMore, nor do we want to provide them simply for accessing cached data.

To solve this, you can use the @connection to specify a custom cache key for results. A connection allows us to set the cache key for a and to filter which s actually alter the query.

To use the @connection , add it to the segment of the query you want a custom store key for and provide the key parameter to specify the store key. In addition to the key parameter, you can also include the optional filter parameter, which takes an array of query names to include in the generated custom store key.

const query = gql`
query Feed($type: FeedType!, $offset: Int, $limit: Int) {
feed(type: $type, offset: $offset, limit: $limit) @connection(key: "feed", filter: ["type"]) {

With the above query, even with multiple fetchMores, the results of each feed update will always result in the feed key in the store being updated with the latest accumulated values. In this example, we also use the @connection 's optional filter to include the type query in the store key, which results in multiple store values that accumulate queries from each type of feed.

Now that we have a stable store key, we can easily use writeQuery to perform a store update, in this case clearing out the feed.

query: gql`
query Feed($type: FeedType!) {
feed(type: $type) @connection(key: "feed", filter: ["type"]) {
variables: {
type: "top",
data: {
feed: [],

Note that because we are only using the type in the store key, we don't have to provide offset or limit.

Customizing field behavior
Edit on GitHubEditForumsDiscord