Configuring the Apollo Client cache

This article describes cache setup and configuration. To learn how to interact with cached data, see Reading and writing data to the cache.

Initialization

Create an InMemoryCache object and provide it to the ApolloClient constructor, like so:

1import { InMemoryCache, ApolloClient } from '@apollo/client';
2
3const client = new ApolloClient({
4  // ...other arguments...
5  cache: new InMemoryCache(options)
6});

The InMemoryCache constructor accepts a variety of configuration options.

Configuration options

You can configure the cache's behavior to better suit your application. For example, you can:

• Customize the format of a particular type's cache ID

• Customize the storage and retrieval of individual fields

• Define polymorphic type relationships for fragment matching

• Define patterns for pagination

• Manage client-side local state

To customize cache behavior, you provide a configuration object to the InMemoryCache constructor. This object supports the following fields:

Customizing cache IDs

You can customize how the InMemoryCache generates cache IDs for individual types in your schema (see the default behavior). This is helpful especially if a type uses a field (or fields!) besides id or _id as its unique identifier.

To accomplish this, you define a TypePolicy for each type you want to customize. You specify all of your cache's typePolicies in the options object you provide to the InMemoryCache constructor.

Include a keyFields field in relevant TypePolicy objects, like so:

1const cache = new InMemoryCache({
2  typePolicies: {
3    Product: {
4      // In an inventory management system, products might be identified
5      // by their UPC.
6      keyFields: ["upc"],
7    },
8    Person: {
9      // In a user account system, the combination of a person's name AND email
10      // address might uniquely identify them.
11      keyFields: ["name", "email"],
12    },
13    Book: {
14      // If one of the keyFields is an object with fields of its own, you can
15      // include those nested keyFields by using a nested array of strings:
16      keyFields: ["title", "author", ["name"]],
17    },
18    AllProducts: {
19      // Singleton types that have no identifying field can use an empty
20      // array for their keyFields.
21      keyFields: [],
22    },
23  },
24});

This example shows a variety of typePolicies with different keyFields:

• The Product type uses its upc field as its identifying field.

• The Person type uses the combination of both its name and email fields.

• The Book type includes a subfield as part of its cache ID.

  • The ["name"] item indicates that the name field of the previous field in the array (author) is part of the cache ID. The Book's author field must be an object that includes a name field for this to be valid.

  • A valid cache ID for the Book type has the following structure:

    Text

    copy

    1Book:{"title":"Fahrenheit 451","author":{"name":"Ray Bradbury"}}

• The AllProducts type illustrates a special strategy for a singleton type. If the cache will only ever contain one AllProducts object and that object has no identifying fields, you can provide an empty array for its keyFields.

If an object has multiple keyFields, the cache ID always lists those fields in the same order to ensure uniqueness.

Note that these keyFields strings always refer to the canonical field names defined in the schema. This means that ID computation is not sensitive to field aliases.

Calculating an object's cache ID

If you define a custom cache ID that uses multiple fields, it can be challenging to calculate and provide that ID to methods that require it (such as cache.readFragment).

To help with this, you can use the cache.identify method to calculate the cache ID for any normalized object you fetch from your cache. See Obtaining an object's custom ID.

Customizing identifier generation globally

If you need to define a single fallback keyFields function that isn't specific to any particular __typename, you can use the dataIdFromObject function that was introduced in Apollo Client 2.x:

1import { defaultDataIdFromObject } from '@apollo/client';
2
3const cache = new InMemoryCache({
4  dataIdFromObject(responseObject) {
5    switch (responseObject.__typename) {
6      case 'Product': return `Product:${responseObject.upc}`;
7      case 'Person': return `Person:${responseObject.name}:${responseObject.email}`;
8      default: return defaultDataIdFromObject(responseObject);
9    }
10  }
11});

The dataIdFromObject API is included in Apollo Client 3 to ease the transition from Apollo Client 2.x.

Notice that the above function still uses different logic to generate keys based on an object's __typename. In a case like this, you should almost always define keyFields arrays for the Product and Person types via typePolicies.

This code also has the following drawbacks:

• It's sensitive to aliasing mistakes.

• It does nothing to protect against undefined object properties.

• Accidentally using different key fields at different times can cause inconsistencies in the cache.

Customizing Type Policies

After creating an InMemoryCache instance, you can use the addTypePolicies method to add or modify type policies.

Here is an example of how to use the addTypePolicies method:

1const cache = new InMemoryCache({
2  typePolicies: {
3    Person: {
4      fields: {
5        name: {
6          read(name = "UNKNOWN NAME") {
7            return name.toUpperCase();
8          }
9        },
10      },
11    },
12  },
13});
14
15// Add a type policy to the cache.
16cache.policies.addTypePolicies({
17  Person: {
18    fields: {
19      email: {
20        read(email = "unknown@example.com") {
21          return email;
22        },
23      },
24    },
25  },
26});

The code creates an InMemoryCache with a custom type policy for the Person type. The type policy specifies that if the name field is not available in the cache, it should return a default value of "UNKNOWN NAME" and converts it to uppercase.

Then, the code adds an additional type policy to the cache using cache.policies.addTypePolicies. This new type policy is related to the Person type and its email field. The custom read function specifies that if the email field is not available in the cache, it should return a default value of "unknown@example.com".

Overall, the code sets up caching behaviors for the Person type, ensuring that default values are provided for the name and email fields if they are not present in the cache.

Disabling normalization

You can instruct the InMemoryCache not to normalize objects of a particular type. This can be useful for metrics and other transient data that's identified by a timestamp and never receives updates.

To disable normalization for a type, define a TypePolicy for the type (as shown in Customizing cache IDs) and set the policy's keyFields field to false.

Objects that are not normalized are instead embedded within their parent object in the cache. You can't access these objects directly, but you can access them via their parent.

TypePolicy fields

To customize how the cache interacts with specific types in your schema, you can pass the InMemoryCache constructor an object that maps __typename strings to TypePolicy objects.

A TypePolicy object can include the following fields:

1type TypePolicy = {
2  // Allows defining the primary key fields for this type, either using an
3  // array of field names, a function that returns an arbitrary string, or
4  // false to disable normalization for objects of this type.
5  keyFields?: KeySpecifier | KeyFieldsFunction | false;
6
7  // If your schema uses a custom __typename for any of the root Query,
8  // Mutation, and/or Subscription types (rare), set the corresponding
9  // field below to true to indicate that this type serves as that type.
10  queryType?: true,
11  mutationType?: true,
12  subscriptionType?: true,
13
14  fields?: {
15    [fieldName: string]:
16      | FieldPolicy<StoreValue>
17      | FieldReadFunction<StoreValue>;
18  }
19};
20
21// Recursive type aliases are coming in TypeScript 3.7, so this isn't the
22// actual type we use, but it's what it should be:
23type KeySpecifier = (string | KeySpecifier)[];
24
25type KeyFieldsFunction = (
26  object: Readonly<StoreObject>,
27  context: {
28    typename: string;
29    selectionSet?: SelectionSetNode;
30    fragmentMap?: FragmentMap;
31  },
32) => string | null | void;

Overriding root operation types (uncommon)

In addition to keyFields, a TypePolicy can indicate that its type represents the root query, mutation, or subscription type by setting queryType, mutationType, or subscriptionType to true:

1const cache = new InMemoryCache({
2  typePolicies: {
3    UnconventionalRootQuery: {
4      // The RootQueryFragment can only match if the cache knows the __typename
5      // of the root query object.
6      queryType: true,
7    },
8  },
9});
10
11const result = cache.readQuery({
12  query: gql`
13    query MyQuery {
14      ...RootQueryFragment
15    }
16    fragment RootQueryFragment on UnconventionalRootQuery {
17      field1
18      field2 {
19        subfield
20      }
21    }
22  `,
23});
24
25const equivalentResult = cache.readQuery({
26  query: gql`
27    query MyQuery {
28      field1
29      field2 {
30        subfield
31      }
32    }
33  `,
34});

The cache usually obtains __typename information by adding the __typename field to every query selection set it sends to the server. It could technically use this same method for the outermost selection set of every operation, but the __typenames of the root query and mutation are almost always "Query" and "Mutation", so the cache assumes those common defaults unless instructed otherwise in a TypePolicy.

For most objects in a graph, the __typename field is vital for proper identification and normalization. For the root query and mutation types, the __typename is not nearly as useful or important, because those types are singletons with only one instance per client.

The fields property

The final property within TypePolicy is the fields property, which enables you to customize the behavior of individual cached fields.