class InMemoryCache

API reference

Methods of the InMemoryCache class (the cache used by almost every instance of ApolloClient) are documented here.

Before reading about individual methods, see Caching in Apollo Client.

`readQuery`

Executes a GraphQL query directly against the cache and returns its result (or null if the query cannot be fulfilled):

1
// Query a cached Todo object with id 5
2
const { todo } = cache.readQuery({
3
  query: gql`
4
    query ReadTodo {
5
      todo(id: 5) {
6
        id
7
        text
8
        completed
9
      }
10
    }
11
  `,
12
});

For usage instructions, see Interacting with cached data: readQuery.

Accepts the following parameters:

Name / Type	Description
`options` `Object`	Required. Provides configuration options for the query, including the actual query to execute. Supported fields are listed below.
`optimistic` `Boolean`	If `true`, `readQuery` returns optimistic results. The default value is `false`.

Options

Name / Type	Description
`query` `DocumentNode`	Required. The GraphQL query to execute, created by wrapping a query string in the `gql` template literal.
`variables` `Object`	A map of any GraphQL variable names and values required by `query`.
`id` `String`	The root `id` to use for the query. The default value is `ROOT_QUERY`, which is the ID of the root query object. By specifying the ID of another cached object, you can query arbitrary cached data without conforming to the structure of your schema's supported queries. This enables `readQuery` to behave similarly to `readFragment`.
`canonizeResults` `Boolean`	⚠️ Deprecated: Using `canonizeResults` can result in memory leaks so we generally do not recommend using this option anymore. A future version of Apollo Client will contain a similar feature without the risk of memory leaks. If `true`, result objects read from the cache will be canonized, which means deeply-equal objects will also be `===` (literally the same object), allowing much more efficient comparison of past/present results. The default value is `false`.

Signature

src/cache/core/cache.ts

1
readQuery<QueryType, TVariables = any>(
2
  options: DataProxy.Query<TVariables>,
3
  optimistic: boolean = false,
4
): QueryType | null

`writeQuery`

Writes data to the cache in the shape of a provided GraphQL query. Returns a Reference to the written object or undefined if the write failed.

1
// Create or modify a cached Todo object with id 5
2
cache.writeQuery({
3
  query: gql`
4
    query ReadTodo($id: ID!) {
5
      todo(id: $id) {
6
        id
7
        text
8
        completed
9
      }
10
    }
11
  `,
12
  data: {
13
    todo: {
14
      __typename: 'Todo',
15
      id: 5,
16
      text: 'Buy grapes 🍇',
17
      completed: false
18
    },
19
  },
20
  variables: {
21
    id: 5
22
  }
23
});

For usage instructions, see Interacting with cached data: writeQuery.

Takes an options object as a parameter. Supported fields of this object are described below.

Options

Name / Type	Description
`query` `DocumentNode`	Required. The GraphQL query that defines the shape of the data to write. Created by wrapping a query string in the `gql` template literal.
`data` `Object`	Required. The data to write to the cache. This object's fields must conform to the shape defined by `query`.
`variables` `Object`	A map of any GraphQL variable names and values required by `query`.
`id` `String`	The `id` of the root object to use with `query`. The default value is `ROOT_QUERY`, which is the ID of the root query object. By specifying the ID of another cached object, you can modify arbitrary cached data without conforming to the structure of your schema's supported queries. This enables `writeQuery` to behave similarly to `writeFragment`.
`broadcast` `Boolean`	If `true`, automatically refresh all active queries that depend on at least one field that's modified by this call. If `false`, silences the broadcast of cache updates and prevents automatic query refresh. The default value is `true`.
`overwrite` `Boolean`	If `true`, ignore existing cache data when calling `merge` functions, allowing incoming data to replace existing data, without warnings about data loss. The default value is `false`.

Signature

src/cache/core/cache.ts

1
writeQuery<TData = any, TVariables = any>(
2
  options: Cache.WriteQueryOptions<TData, TVariables>,
3
): Reference | undefined

`updateQuery`
Since 3.5

Fetches data from the cache in the shape of a provided GraphQL query, then updates that cached data according to a provided update function.

Returns the updated result or null if the update failed.

1
// Fetches a Todo object with id 5 and flips its `completed` boolean
2
cache.updateQuery({ // options object
3
  query: gql`
4
    query ReadTodo($id: ID!) {
5
      todo(id: $id) {
6
        id
7
        text
8
        completed
9
      }
10
    }
11
  `,
12
  variables: {
13
    id: 5
14
  }
15
}, (data) => ({ // update function
16
  todo: {
17
    ...data.todo,
18
    completed: !data.todo.completed
19
  }
20
}));

Takes an options object and an update function as parameters (both described below).

Options

Name / Type	Description
`query` `DocumentNode`	Required. The GraphQL query that defines the shape of the data to fetch. Created by wrapping a query string in the `gql` template literal.
`variables` `Object`	A map of any GraphQL variable names and values required by `query`.
`id` `String`	The `id` of the root object to use with `query`. The default value is `ROOT_QUERY`, which is the ID of the root query object. By specifying the ID of another cached object, you can modify arbitrary cached data without conforming to the structure of your schema's supported queries. This enables `updateQuery` to behave similarly to `updateFragment`.
`broadcast` `Boolean`	If `true`, automatically refresh all active queries that depend on at least one field that's modified by this call. If `false`, silences the broadcast of cache updates and prevents automatic query refresh. The default value is `true`.
`overwrite` `Boolean`	If `true`, ignore existing cache data when calling `merge` functions, allowing incoming data to replace existing data, without warnings about data loss. The default value is `false`.

`updateQuery` update function

The update function of updateQuery takes a query's current cached value and returns the value that should replace it (or undefined if no change should be made).

The returned value is automatically passed to writeQuery, which modifies the cached data.

Please note the update function has to calculate the new value in an immutable way. You can read more about immutable updates in the React documentation.

Signature

src/cache/core/cache.ts

1
public updateQuery<TData = any, TVariables = any>(
2
  options: Cache.UpdateQueryOptions<TData, TVariables>,
3
  update: (data: TData | null) => TData | null | void,
4
): TData | null

`readFragment`

Reads data from the cache in the shape of a provided GraphQL fragment:

1
const todo = cache.readFragment({
2
  id: '5', // The value of the to-do item's unique identifier
3
  fragment: gql`
4
    fragment MyTodo on Todo {
5
      id
6
      text
7
      completed
8
    }
9
  `,
10
});

Returns the requested data or null if data is not available in the cache.

For usage instructions, see Interacting with cached data: readFragment.

Accepts the following parameters:

Name / Type	Description
`options` `Object`	Required. Provides configuration options, including the actual fragment to use. Supported fields are listed below.
`optimistic` `Boolean`	If `true`, `readFragment` returns optimistic results. The default value is `false`.

Options

Name / Type	Description
`id` `String`	Required. The ID of the cached object that this call is reading a fragment of. If the cache does not contain an object with the specified ID, `readFragment` returns `null`.
`fragment` `DocumentNode`	Required. A GraphQL document created with the `gql` template literal tag that includes the fragment to read. If the document includes more than one fragment, you must also provide `fragmentName` to indicate which to use.
`fragmentName` `String`	The name of the fragment defined in the `fragment` document to use in the call. You don't need to provide this value if the `fragment` document includes only one fragment.
`variables` `Object`	A map of any GraphQL variable names and values required by `fragment`.
`canonizeResults` `Boolean`	⚠️ Deprecated: Using `canonizeResults` can result in memory leaks so we generally do not recommend using this option anymore. A future version of Apollo Client will contain a similar feature without the risk of memory leaks. If `true`, result objects read from the cache will be canonized, which means deeply-equal objects will also be `===` (literally the same object), allowing much more efficient comparison of past/present results. The default value is `false`.

Signature

src/cache/core/cache.ts

1
readFragment<FragmentType, TVariables = any>(
2
  options: DataProxy.Fragment<TVariables>,
3
  optimistic: boolean = false,
4
): FragmentType | null

`writeFragment`

Writes data to the cache in the shape of the provided GraphQL fragment. Returns a Reference to the written object or undefined if the write failed.

1
client.writeFragment({
2
  id: 'Todo:5',
3
  fragment: gql`
4
    fragment MyTodo on Todo {
5
      completed
6
    }
7
  `,
8
  data: {
9
    completed: true,
10
  },
11
});

For usage instructions, see Interacting with cached data: writeFragment.

Takes an options object as a parameter. Supported fields of this object are described below.

Options

Name / Type	Description
`id` `String`	Required. The ID of the cached object that this call is writing a fragment to. If the cache does not contain an object with the specified ID, `writeFragment` returns `null`.
`fragment` `DocumentNode`	Required. A GraphQL document created with the `gql` template literal tag that includes the fragment to write. If the document includes more than one fragment, you must also provide `fragmentName` to indicate which to use.
`data` `Object`	Required. The data to write to the cache. This object's fields must conform to the shape defined by `fragment`.
`fragmentName` `String`	The name of the fragment defined in the `fragment` document to use in the call. You don't need to provide this value if the `fragment` document includes only one fragment.
`variables` `Object`	A map of any GraphQL variable names and values required by `fragment`.
`broadcast` `Boolean`	If `true`, automatically refresh all active queries that depend on at least one field that's modified by this call. If `false`, silences the broadcast of cache updates and prevents automatic query refresh. The default value is `true`.
`overwrite` `Boolean`	If `true`, ignore existing cache data when calling `merge` functions, allowing incoming data to replace existing data, without warnings about data loss. The default value is `false`.

Signature

src/cache/core/cache.ts

1
writeFragment<TData = any, TVariables = any>(
2
  options: Cache.WriteFragmentOptions<TData, TVariables>,
3
): Reference | undefined

Watches the cache store of the fragment according to the options specified and returns an Observable. We can subscribe to this Observable and receive updated results through an observer when the cache store changes.

You must pass in a GraphQL document with a single fragment or a document with multiple fragments that represent what you are reading. If you pass in a document with multiple fragments then you must also specify a fragmentName.

Signature

1
function watchFragment(
2
  options: WatchFragmentOptions<TFragmentData, TVariables>
3
): Observable<WatchFragmentResult<TFragmentData>>

Parameters

Name / Type

Description

options

WatchFragmentOptions<TFragmentData, TVariables>

An object of type WatchFragmentOptions that allows the cache to identify the fragment and optionally specify whether to react to optimistic updates.

Show/hide child attributes

Required options

fragment

DocumentNode | TypedDocumentNode<TFragmentData, TVariables>

A GraphQL fragment document parsed into an AST with the gql template literal.

from

StoreObject | Reference | FragmentType<NoInfer<TFragmentData>> | string

An object containing a __typename and primary key fields (such as id) identifying the entity object from which the fragment will be retrieved, or a { __ref: "..." } reference, or a string ID (uncommon).

Cache options

fragmentName (optional)

string

The name of the fragment defined in the fragment document.

Required if the fragment document includes more than one fragment, optional otherwise.

optimistic (optional)

boolean

If true, watchFragment returns optimistic results.

The default value is true.

variables (optional)

TVariables

Any variables that the GraphQL fragment may depend on.

Result

1
Observable<WatchFragmentResult<TFragmentData>>

`updateFragment`
Since 3.5

Fetches data from the cache in the shape of a provided GraphQL fragment, then updates that cached data according to a provided update function.

Returns the updated result or null if the update failed.

1
// Fetches a Todo object with id 5 and sets its `completed` boolean to true
2
const todo = cache.updateFragment({ // options object
3
  id: '5', // The value of the to-do item's unique identifier
4
  fragment: gql`
5
    fragment MyTodo on Todo {
6
      completed
7
    }
8
  `,
9
}, (data) => ({ ...data, completed: true }) // update function
10
);

Takes an options object and an update function as parameters (both described below).

Options

Name / Type	Description
`id` `String`	Required. The ID of the cached object that this call is reading a fragment of. If the cache does not contain an object with the specified ID, `updateFragment` returns `null`.
`fragment` `DocumentNode`	Required. A GraphQL document created with the `gql` template literal tag that includes the fragment to read. If the document includes more than one fragment, you must also provide `fragmentName` to indicate which to use.
`fragmentName` `String`	The name of the fragment defined in the `fragment` document to use in the call. You don't need to provide this value if the `fragment` document includes only one fragment.
`variables` `Object`	A map of any GraphQL variable names and values required by `fragment`.
`broadcast` `Boolean`	If `true`, automatically refresh all active queries that depend on at least one field that's modified by this call. If `false`, silences the broadcast of cache updates and prevents automatic query refresh. The default value is `true`.
`overwrite` `Boolean`	If `true`, ignore existing cache data when calling `merge` functions, allowing incoming data to replace existing data, without warnings about data loss. The default value is `false`.

`updateFragment` update function

The update function of updateFragment takes a fragment's current cached value and returns the value that should replace it (or undefined if no change should be made).

The returned value is automatically passed to writeFragment, which modifies the cached data.

Please note the update function has to calculate the new value in an immutable way. You can read more about immutable updates in the React documentation.

Signature

src/cache/core/cache.ts

1
public updateFragment<TData = any, TVariables = any>(
2
  options: Cache.UpdateFragmentOptions<TData, TVariables>,
3
  update: (data: TData | null) => TData | null | void,
4
): TData | null

`identify`

Returns the canonical ID for a specified cached object.

You can provide either an object or an object reference to this function:

If you provide an object, identify returns the object's string-based ID (e.g., Car:1).
If you provide a reference, identify return the reference's __ref ID string.

For usage instructions, see Interacting with cached data: Identify cached entities.

Accepts the following parameters:

Name / Type	Description
`object` `StoreObject` or `Reference`	Required. The cached object (or object reference) to obtain the canonical ID for.

Signature

src/cache/inmemory/inMemoryCache.ts

1
identify(object: StoreObject | Reference): string | undefined

`modify`

Modifies one or more field values of a cached object. Must provide a modifier function for each field to modify. A modifier function takes a cached field's current value and returns the value that should replace it.

Returns true if the cache was modified successfully and false otherwise.

For usage instructions, see Using cache.modify.

Takes an options object as a parameter. Supported fields of this object are described below.

Options

Name / Type	Description
`fields` `Object`	Required. A map that specifies the modifier function to call for each modified field of the cached object. See Modifier function API below.
`id` `string`	The ID of the cached object to modify. The default value is `ROOT_QUERY` (the ID of the root query singleton object).
`optimistic` `Boolean`	If `true`, also modifies the optimistically cached values for included fields. The default value is `false`.
`broadcast` `Boolean`	If `true`, automatically refresh all active queries that depend on at least one field that's modified by this call. If `false`, silences the broadcast of cache updates and prevents automatic query refresh. The default value is `true`.

Modifier function API

A modifier function takes a cached field's current value and returns the value that should replace it, or the DELETE sentinel object to delete the field entirely.

The first parameter passed to a modifier function is the current cached value of the field being modified.

The second parameter is a helper object that contains the following utilities:

Name / Type	Description
`fieldName` `String`	The name of the field being modified.
`storeFieldName` `String`	The full key for the field used internally, including serialized key arguments.
`readField` `Function`	A helper function for reading other fields on the object passed to the modifier function as the first parameter.
`canRead` `Function`	A helper function that returns `true` for non-normalized `StoreObject`s and non-dangling `Reference`s. This indicates that `readField(name, objOrRef)` has a chance of working. Useful for filtering dangling references out of lists.
`isReference` `Function`	A helper function that returns `true` if a particular object is a reference to a cached entity.
`DELETE` `Object`	A sentinel object that you can return from a modifier function to indicate that the field should be deleted entirely.

Signature

src/cache/inmemory/inMemoryCache.ts

1
modify(options: Cache.ModifyOptions): boolean

`gc`

Performs garbage collection of unreachable normalized objects in the cache:

1
cache.gc();

Returns an array containing the IDs of all objects removed from the cache.

For usage instructions, see cache.gc.

Signature

src/cache/inmemory/inMemoryCache.ts

1
gc()

`evict`

Either removes a normalized object from the cache or removes a specific field from a normalized object in the cache:

1
cache.evict({ id: 'my-object-id', fieldName: 'myFieldName' });

Returns true if data was removed from the cache, false otherwise.

For usage instructions, see cache.evict.

Takes an options object as a parameter. Supported fields of this object are described below.

Options

Name / Type	Description
`id` `String`	The ID of the cached object to remove (or remove a field from). The default value is `ROOT_QUERY`, which is the ID of the root query object.
`fieldName` `String`	The name of the field to remove from the cached object. Omit this option if you are removing the entire object.
`args` `Record<string, any>`	If provided with `fieldName`, only instances of the field with the specified arguments are removed from the cache. Otherwise, all instances of the field are removed for the cached object.
`broadcast` `Boolean`	If `true`, automatically refresh all active queries that depend on at least one field that's removed by this call. If `false`, silences the broadcast of cache updates and prevents automatic query refresh. The default value is `true`.

Signature

src/cache/inmemory/inMemoryCache.ts

1
evict(options: Cache.EvictOptions): boolean

`extract`

Returns a serialized representation of the cache's current contents as a NormalizedCacheObject.

Accepts the following parameters:

Name / Type	Description
`optimistic` `Boolean`	If `true`, optimistic data is included in the serialization. The default value is `false`.

Signature

src/cache/inmemory/inMemoryCache.ts

1
extract(optimistic: boolean = false): NormalizedCacheObject

`restore`

Restores the cache's state from a serialized NormalizedCacheObject (such as one returned by extract). This removes all existing data from the cache.

Returns the InMemoryCache instance it's called on.

Accepts the following parameters:

Name / Type	Description
`data` `NormalizedCacheObject`	Required. The serialization to restore the cache from.

Signature

src/cache/inmemory/inMemoryCache.ts

1
restore(data: NormalizedCacheObject): this

`makeVar`

Creates a reactive variable with an optional initial value:

1
const cartItems = makeVar([]);

Returns the reactive variable function you use to read or modify the variable's value.

For usage instructions, see Reactive variables.

Accepts the following parameters:

Name / Type	Description
`value` Any	The reactive variable's initial value.

Signature

src/cache/inmemory/inMemoryCache.ts

1
makeVar<T>(value: T): ReactiveVar<T>

ApolloClient

ObservableQuery

class InMemoryCache

API reference

watchFragmentSince 3.10.0

updateFragmentSince 3.5

`watchFragment`
Since 3.10.0

`updateFragment`
Since 3.5