Options

When you execute an operation, certain options control how the query is executed.

These options can be set globally on the ApolloClient or per operation, on ApolloRequest. When set globally, they apply to all requests executed by that client, unless overridden by per-request options.

fetchPolicy

The fetch policy controls how and if the cache is used. The default is CacheFirst.

CacheFirst (default)

Emit the response from the cache first, and if there was an exception on the response (e.g. a cache miss or a cached server error), emits the response(s) from the network.

This is the default behavior.

CacheOnly

Emit the response(s) from the network first, and if there was a network error, emit the response from the cache.

NetworkFirst

Emit the response(s) from the network first, and if there was a network error, emit the response from the cache.

NetworkOnly

Emit the response(s) from the network only.

CacheAndNetwork

Emit the response from the cache first, and then emit the response(s) from the network.

Warning: this policy can emit multiple successful responses, therefore ApolloCall.execute() should not be used with this policy. Use only with ApolloCall.toFlow() or ApolloCall.watch().

refetchPolicy

The refetch policy controls how the cache is used when watchers are notified of changes in the cache. The default is CacheOnly.

serverErrorsAsException

Sets whether GraphQL errors in the cache should be exposed as an exception. When true (the default), if any field is an Error in the cache, the returned response will have a null data and a non-null exception of type ApolloGraphQLException.

Set this to false to allow partial responses from the cache, where errors are included in the response's errors.

cacheMissesAsException

Sets whether missing fields from the cache should be exposed as an exception. When true (the default), if any field is missing in the cache, the returned response will have a null data and a non-null exception of type CacheMissException.

Set this to false to allow partial responses from the cache, where some or all of the fields may be missing, and Errors are included in the response's errors to represent cache misses.

maxStale

If stale fields are acceptable up to a certain value, you can set a maximum staleness duration. This duration is the maximum time that a stale field will be resolved without resulting in a cache miss. To set this duration, call .maxStale(Duration) either globally on your client, or per operation:

1val response = client.query(MyQuery())
2  .fetchPolicy(FetchPolicy.CacheOnly)
3  .maxStale(1.hours)
4  .execute()

isStale

With maxStale, it is possible to get data from the cache even if it is stale. To know if the response contains stale fields, you can check CacheInfo.isStale:

1if (response.cacheInfo?.isStale == true) {
2  // The response contains at least one stale field
3}