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 operation. 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:

1
const { loading, error, data } = useQuery(GET_DOGS, {
2
  fetchPolicy: "no-cache" 
3
});

Operations 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.

1
import AsyncStorage from '@react-native-async-storage/async-storage';
2
import { InMemoryCache } from '@apollo/client';
3
import { persistCache } from 'apollo3-cache-persist';
4

5
const cache = new InMemoryCache();
6

7
persistCache({
8
  cache,
9
  storage: AsyncStorage,
10
}).then(() => {
11
  // Continue setting up Apollo Client as usual.
12
})

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.

1
import { useQuery } from '@apollo/client';
2
function Profile() {
3
    const { data, client } = useQuery(PROFILE_QUERY);
4
    return (
5
      <Fragment>
6
        <p>Current user: {data?.currentUser}</p>
7
        <button onClick={async ()=>client.resetStore()}>
8
            Log out
9
        </button>
10
      </Fragment>
11
    );
12
}

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.

1
import { ApolloClient, InMemoryCache } from '@apollo/client';
2
import { withClientState } from 'apollo-link-state';
3

4
import { resolvers, defaults } from './resolvers';
5

6
const cache = new InMemoryCache();
7
const stateLink = withClientState({ cache, resolvers, defaults });
8

9
const client = new ApolloClient({
10
  cache,
11
  link: stateLink,
12
});
13

14
client.onResetStore(stateLink.writeDefaults);

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:

1
import { useApolloClient } from '@apollo/client';
2

3
function Foo (){
4
  const [reset, setReset] = useState(0);
5
  const client = useApolloClient();
6

7
  useEffect(() => {
8
    const unsubscribe = client.onResetStore(() =>
9
      new Promise(()=>setReset(reset + 1))
10
    );
11

12
    return () => {
13
      unsubscribe();
14
    };
15
  });
16

17
  return reset ? <div /> : <span />
18
}
19

20
export default Foo;

TypePolicy inheritance

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 schema, 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 field policies, which can be selectively overridden by subtypes that want something different.

• A single subtype can have multiple supertypes in a GraphQL schema, 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 schema knows nothing about those supertypes.

• The possibleTypes map is currently used only for fragment 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:

1
const cache = new InMemoryCache({
2
  possibleTypes: {
3
    Reptile: ["Snake", "Turtle"],
4
    Snake: ["Python", "Viper", "Cobra"],
5
    Viper: ["Cottonmouth", "DeathAdder"],
6
  },
7

8
  typePolicies: {
9
    Reptile: {
10
      // Suppose all our reptiles are captive, and have a tag with an ID.
11
      keyFields: ["tagId"],
12
      fields: {
13
        // Scientific name-related logic can be shared among Reptile subtypes.
14
        scientificName: {
15
          merge(_, incoming) {
16
            // Normalize all scientific names to lower case.
17
            return incoming.toLowerCase();
18
          },
19
        },
20
      },
21
    },
22

23
    Snake: {
24
      fields: {
25
        // Default to a truthy non-boolean value if we don't know
26
        // whether this snake is venomous.
27
        venomous(status = "unknown") {
28
          return status;
29
        },
30
      },
31
    },
32
  },
33
});

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 mutation doesn't return modified fields.

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

For details, see Refetching queries.

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:

1
query Books {
2
  books {
3
    id
4
    title
5
    abstract
6
  }
7
}

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

1
query Book($id: ID!) {
2
  book(id: $id) {
3
    id
4
    title
5
    abstract
6
  }
7
}

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 field policy read function for the book field:

1
import { ApolloClient, InMemoryCache } from '@apollo/client';
2

3
const client = new ApolloClient({
4
  cache: new InMemoryCache({
5
    typePolicies: {
6
      Query: {
7
        fields: {
8
          book: {
9
            read(_, { args, toReference }) {
10
              return toReference({
11
                __typename: 'Book',
12
                id: args.id,
13
              });
14
            }
15
          }
16
        }
17
      }
18
    }
19
  })
20
});

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 field, 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.

Pagination utilities

Pagination is a best practice in GraphQL for several reasons. Apollo Client enables fetching and caching paginated results using the Core pagination API. The API includes a few important utilities, including the fetchMore function and the @connection directive.

Incremental loading: fetchMore

You can use the fetchMore function to update a query's cached result with data returned by a follow-up 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

The @connection directive solves the problem of multiple copies of the same field in the cache. This can happen with paginated queries because the fetchMore function sends follow-up queries to fetch additional pages of results using arguments like offset and limit. These arguments inadvertently fragment data from different pagination requests across the cache.

The @connection directive lets you unify paginated results by specifying a custom, stable cache key for a field. It also lets you intentionally separate paginated results in the cache by fields that you specify.

@connection directive usage

1
const cache = new InMemoryCache({
2
  typePolicies: {
3
    Query: {
4
      fields: {
5
        feed: {
6
          keyArgs: ["type"]
7
        }
8
      }
9
    }
10
  }
11
})

To use the @connection directive, add it to the field you want a custom cache key for. The directive requires a key parameter to specify the custom cache key. You can optionally include the filter parameter, which takes an array of query argument names to include in the generated custom cache key.

1
const query = gql`
2
  query Feed($type: FeedType!, $offset: Int, $limit: Int) {
3
    feed(type: $type, offset: $offset, limit: $limit) @connection(key: "feed", filter: ["type"]) {
4
      ...FeedEntry
5
    }
6
  }
7
`

With the above query, even when multiple fetchMores queries are performed, each feed update always results in an update to the cache's feed key with the latest accumulated values. The example also uses the @connection directive's optional filter argument to include the type query argument in the cache key. This creates multiple cache values that accumulate queries from each type of feed.

With a stable cache key, you can use writeQuery to perform a cache update that clears out the feed.

1
client.writeQuery({
2
  query: gql`
3
    query Feed($type: FeedType!) {
4
      feed(type: $type) @connection(key: "feed", filter: ["type"]) {
5
        id
6
      }
7
    }
8
  `,
9
  variables: {
10
    type: "top",
11
  },
12
  data: {
13
    feed: [],
14
  },
15
});

Advanced @connection directive usage

The @connection directive is useful when using the same field in multiple queries, with no distinguishing arguments (for example, type) that keyArgs can use, and you want to keep that field's data separate in the cache.

For example, Apollo's Spotify showcase uses @connection to independently cache lists of playlists. One list is in the left sidebar, where you navigate between playlists. The other appears when you right-click a song to add it to a playlist.

Without caching the playlists separately, loading the next page of data from one list affects the other, negatively impacting the UX.

For code examples, see:

• The type policy
• Playlist sidebar query
• Add to playlist menu