/
Launch Apollo Studio

InMemoryCache

InMemoryCache API reference


readQuery

Run GraphQL queries directly against the cache.

For usage instructions, refer to Interacting with cached data: readQuery.

Method

src/cache/core/cache.ts
readQuery<QueryType, TVariables = any>(
  options: DataProxy.Query<TVariables>,
  optimistic: boolean = false,
): QueryType | null

Input

options

OptionTypeDescription
queryDocumentNodeThe GraphQL query shape to be used constructed using the gql template string tag from graphql-tag. The query will be used to determine the shape of the data to be read.
variables?TVariablesAny variables that the GraphQL query may depend on.
id?stringThe root id to be used. Defaults to ROOT_QUERY, which is the ID of the root query object.

optimistic

TypeDescription
booleanSet to true to allow readQuery to return optimistic results. Is false by default.

Output

Query result data object (optionally typed by QueryType) or null if no matching data can be found.

writeQuery

Write data in the shape of the provided GraphQL query, into the cache.

For usage instructions, refer to Interacting with cached data: writeQuery.

Method

src/cache/core/cache.ts
writeQuery<TData = any, TVariables = any>(
  options: Cache.WriteQueryOptions<TData, TVariables>,
): Reference | undefined

Input

options

OptionTypeDescription
queryDocumentNodeThe GraphQL query shape to be used constructed using the gql template string tag from graphql-tag. The query will be used to determine the shape of the data to be written.
variables?TVariablesAny variables that the GraphQL query may depend on.
id?stringThe root id to be used. Defaults to ROOT_QUERY, which is the ID of the root query object. This property makes writeQuery capable of writing data to any object in the cache, which renders writeFragment mostly useless.
dataTDataThe data you will be writing to the cache.
broadcast?booleanWhether to notify query watchers (default: true).

Output

Returns a Reference to the written object, or undefined if the write failed.

readFragment

Read data from the cache in the shape of the provided GraphQL fragment.

For usage instructions, refer to Interacting with cached data: readFragment.

Method

src/cache/core/cache.ts
readFragment<FragmentType, TVariables = any>(
  options: DataProxy.Fragment<TVariables>,
  optimistic: boolean = false,
): FragmentType | null

Input

options

OptionTypeDescription
id?stringThe root id to be used. If a value with your id does not exist in the cache, null will be returned.
fragmentDocumentNodeA GraphQL document created using the gql template string tag from graphql-tag with one or more fragments which will be used to determine the shape of data to read. If you provide more than one fragment in this document then you must also specify fragmentName to select a single fragment.
fragmentName?stringThe name of the fragment in your GraphQL document to be used. If you do not provide a fragmentName and there is only one fragment in your fragment document, then that fragment will be used.
variables?TVariablesAny variables that your GraphQL fragments depend on.

optimistic

TypeDescription
booleanSet to true to allow readFragment to return optimistic results. Is false by default.

Output

Fragment result data object (optionally typed by FragmentType) or null if no matching data can be found.

writeFragment

Write data in the shape of the provided GraphQL fragment, into the cache.

For usage instructions, refer to Interacting with cached data: writeFragment.

Method

src/cache/core/cache.ts
writeFragment<TData = any, TVariables = any>(
  options: Cache.WriteFragmentOptions<TData, TVariables>,
): Reference | undefined

Input

options

OptionTypeDescription
id?stringThe root id to be used.
fragmentDocumentNodeA GraphQL document created using the gql template string tag from graphql-tag with one or more fragments which will be used to determine the shape of data to write. If you provide more than one fragment in this document then you must also specify fragmentName to select a single fragment.
fragmentName?stringThe name of the fragment in your GraphQL document to be used. If you do not provide a fragmentName and there is only one fragment in your fragment document, then that fragment will be used.
variables?TVariablesAny variables that your GraphQL fragments depend on.
dataTDataThe data you will be writing to the cache.
broadcast?booleanWhether to notify query watchers (default: true).

Output

Returns a Reference to the written object, or undefined if the write failed.

identify

Returns the canonical ID for a given cache object or reference.

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

Method

src/cache/inmemory/inMemoryCache.ts
identify(object: StoreObject | Reference): string | undefined

Input

object

TypeDescription
StoreObject | ReferenceEither a cache object (an object with a __typename and any primary key fields required to identify entities of that type) or a Reference (an object with a __ref property).

Output

If object is a StoreObject, identify will return its string based ID (e.g. Car:1). If object a Reference object, identify will return its __ref ID string.

modify

Takes an entity ID and an object mapping field names to modifier functions. For the specified entity, each field modifier function is called with the current value or references of the field, and should return a new value for the field to be written into the cache.

For usage instructions, see cache.modify.

Method

src/cache/inmemory/inMemoryCache.ts
modify(options: Cache.ModifyOptions): boolean

Input

options

OptionTypeDescription
id?stringID of the cache object to be modified.
fieldsModifiers | Modifier<any>Map of field names to one or more Modifier functions, that are to be run for each field, returning a new value for the field that is then written into the cache. The Modifier function API is explained below.
optimistic?booleanSet to true to modify optimistic data. Is false by default.
broadcast?booleanWhether to notify query watchers (default: true).
Modifier functions

E.g. A Modifier function for an author field:

// ...
fields: {
  author(author: Reference, { readField }) {
    // ...
    return author;
  }
}
// ...

The first parameter of a modifier function is the current value of the field being modified (author in the example above). The second parameter is a helper object that contains several utilities:

PropertyTypeDescription
fieldNamestringThe name of the field being modified.
storeFieldNamestringThe full field key used internally, including serialized key arguments.
readFieldReadFieldFunctionA helper function for reading other fields within the current object.
canReadCanReadFunctionReturns true for non-normalized StoreObjects and non-dangling References, indicating that readField(name, objOrRef) has a chance of working. Useful for filtering out dangling references from lists.
isReferencebooleanUtility to check if an object is a { __ref } object.
DELETEanySentinel object that can be returned from a modifier function to delete the field being modified.
INVALIDATEanySentinel object that can be returned from a modifier function to invalidate the field, causing affected queries to rerun, without changing or deleting the field value.

Modifier functions should return the value that is to be written into the cache for the field being modified, or a DELETE sentinel to remove the field.

Output

cache.modify returns true if the cache was modified successfully, false otherwise.

gc

Request the garbage collection of unreachable normalized entities.

For usage instructions, see cache.gc.

Method

src/cache/inmemory/inMemoryCache.ts
gc()

Input

None

Output

Returns an array of ID strings that were removed from the cache, if any.

evict

Remove whole objects from the cache by passing options.id, or specific fields by passing options.field and/or options.args. If no options.args are provided, all fields matching options.field (even those with arguments) will be removed.

For usage instructions, see `cache.evict.

Method

src/cache/inmemory/inMemoryCache.ts
evict(options: Cache.EvictOptions): boolean

Input

options

OptionTypeDescription
id?stringID of object to remove from the cache.
fieldName?stringSpecific field of an object to remove from the cache.
args?Record<string, any>Ensure only fields with these arguments are removed from the cache.
broadcast?booleanWhether to notify query watchers (default: true).

Output

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

extract

Get a serialized representation of the cache's current state.

Method

src/cache/inmemory/inMemoryCache.ts
extract(optimistic: boolean = false): NormalizedCacheObject

Input

ParamTypeDescription
optimisticbooleanSet to true to include optimistic data in the extract. Is false by default.

Output

Returns a serialized representation of all cache contents (NormalizedCacheObject).

restore

Replaces existing state in the cache (if any).

Method

src/cache/inmemory/inMemoryCache.ts
restore(data: NormalizedCacheObject): this

Input

ParamTypeDescription
dataNormalizedCacheObjectNew cache state that will overwrite the existing cache state.

Output

Returns the current InMemoryCache instance.

makeVar

Create/update/read reactive variables.

For usage instructions, refer to Local state: Reactive variables.

Method

src/cache/inmemory/inMemoryCache.ts
makeVar<T>(value: T): ReactiveVar<T>

Input

ParamTypeDescription
valueTNew or updated value of the reactive variable.

Output

Returns a reactive variable function. Calling the function will return the value of the current reactive variable.

Edit on GitHub