API Reference (apollo-client)

The API for the apollo-client package

ApolloClient

The ApolloClient class is the core API for Apollo, and the one you’ll need to use no matter which integration you are using:

Constructs an instance of ApolloClient.

Options

addTypename any
connectToDevTools any
customResolvers [typeName:undefined]:[fieldName:undefined]:(any, [argName:undefined]:any) => any
dataIdFromObject (Object) => any
fragmentMatcher FragmentMatcherInterface
initialState any
networkInterface NetworkInterface
queryDeduplication any
reduxRootSelector any
ssrForceFetchDelay any
ssrMode any

This watches the results of the query according to the options specified and returns an ObservableQuery. We can subscribe to this ObservableQuery and receive updated results through a GraphQL observer.

Note that this method is not an implementation of GraphQL subscriptions. Rather, it uses Apollo's store in order to reactively deliver updates to your query results.

For example, suppose you call watchQuery on a GraphQL query that fetches an person's first name and last name and this person has a particular object identifer, provided by dataIdFromObject. Later, a different query fetches that same person's first and last name and his/her first name has now changed. Then, any observers associated with the results of the first query will be updated with a new result object.

See here for a description of store reactivity.

Options

fetchPolicy "cache-first" | "cache-and-network" | "network-only" | "cache-only" | "standby"

Specifies the FetchPolicy to be used for this query

metadata any

Arbitrary metadata stored in Redux with this query. Designed for debugging, developer tools, etc.

notifyOnNetworkStatusChange any

Whether or not updates to the network status should trigger next on the observer of this query

pollInterval any

The time interval (in milliseconds) on which this query should be refetched from the server.

query DocumentNode

A GraphQL document that consists of a single query to be sent down to the server.

reducer (Object, QueryResultAction | QueryErrorAction | QueryInitAction | QueryResultClientAction | QueryStopAction | MutationInitAction | MutationResultAction | MutationErrorAction | UpdateQueryResultAction | StoreResetAction | SubscriptionResultAction | WriteAction, Object) => Object

A redux reducer that lets you update the result of this query in the store based on any action (including mutation and query results)

variables any

A map going from variable name to variable value, where the variables are used within the GraphQL query.

This resolves a single query according to the options specified and returns a Promise which is either resolved with the resulting data or rejected with an error.

Options

fetchPolicy "cache-first" | "cache-and-network" | "network-only" | "cache-only" | "standby"

Specifies the FetchPolicy to be used for this query

metadata any

Arbitrary metadata stored in Redux with this query. Designed for debugging, developer tools, etc.

notifyOnNetworkStatusChange any

Whether or not updates to the network status should trigger next on the observer of this query

pollInterval any

The time interval (in milliseconds) on which this query should be refetched from the server.

query DocumentNode

A GraphQL document that consists of a single query to be sent down to the server.

reducer (Object, QueryResultAction | QueryErrorAction | QueryInitAction | QueryResultClientAction | QueryStopAction | MutationInitAction | MutationResultAction | MutationErrorAction | UpdateQueryResultAction | StoreResetAction | SubscriptionResultAction | WriteAction, Object) => Object

A redux reducer that lets you update the result of this query in the store based on any action (including mutation and query results)

variables any

A map going from variable name to variable value, where the variables are used within the GraphQL query.

This resolves a single mutation according to the options specified and returns a Promise which is either resolved with the resulting data or rejected with an error.

Options

mutation DocumentNode

A GraphQL document, often created with gql from the graphql-tag package, that contains a single mutation inside of it.

optimisticResponse Object

An object that represents the result of this mutation that will be optimistically stored before the server has actually returned a result. This is most often used for optimistic UI, where we want to be able to see the result of a mutation immediately, and update the UI later if any errors appear.

refetchQueries any

A list of query names which will be refetched once this mutation has returned. This is often used if you have a set of queries which may be affected by a mutation and will have to update. Rather than writing a mutation query reducer (i.e. updateQueries) for this, you can simply refetch the queries that will be affected and achieve a consistent store once these queries return.

update (DataProxy, Object) => any

This function will be called twice over the lifecycle of a mutation. Once at the very beginning if an optimisticResponse was provided. The writes created from the optimistic data will be rolled back before the second time this function is called which is when the mutation has succesfully resolved. At that point update will be called with the actual mutation result and those writes will not be rolled back.

The reason a DataProxy is provided instead of the user calling the methods directly on ApolloClient is that all of the writes are batched together at the end of the update, and it allows for writes generated by optimistic data to be rolled back.

updateQueries [queryName:undefined]:(Object, any) => Object

A MutationQueryReducersMap, which is map from query names to mutation query reducers. Briefly, this map defines how to incorporate the results of the mutation into the results of queries that are currently being watched by your application.

variables Object

An object that maps from the name of a variable as used in the mutation GraphQL document to that variable's value.

Tries to read some data from the store in the shape of the provided GraphQL query without making a network request. This method will start at the root query. To start at a specific id returned by dataIdFromObject use readFragment.

Options

query DocumentNode

The 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 Object

Any variables that the GraphQL query may depend on.

Tries to read some data from the store in the shape of the provided GraphQL fragment without making a network request. This method will read a GraphQL fragment from any arbitrary id that is currently cached, unlike readQuery which will only read from the root query.

Options

fragment DocumentNode

A 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 then one fragment in this document then you must also specify fragmentName to select a single.

fragmentName any

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

id any

The root id to be used. This id should take the same form as the value returned by your dataIdFromObject function. If a value with your id does not exist in the store, null will be returned.

variables Object

Any variables that your GraphQL fragments depend on.

Writes some data in the shape of the provided GraphQL query directly to the store. This method will start at the root query. To start at a a specific id returned by dataIdFromObject then use writeFragment.

Options

data any

The data you will be writing to the store.

query DocumentNode

The 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 Object

Any variables that the GraphQL query may depend on.

Writes some data in the shape of the provided GraphQL fragment directly to the store. This method will write to a GraphQL fragment from any arbitrary id that is currently cached, unlike writeQuery which will only write from the root query.

Options

data any

The data you will be writing to the store.

fragment DocumentNode

A 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 then one fragment in this document then you must also specify fragmentName to select a single.

fragmentName any

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

id any

The root id to be used. This id should take the same form as the value returned by your dataIdFromObject function.

variables Object

Any variables that your GraphQL fragments depend on.

The dataIdFromObject function used by this client instance.

The dataIdFromObject function used by this client instance.

This initializes the Redux store that we use as a reactive cache.

Resets your entire store by clearing out your cache and then re-executing all of your active queries. This makes it so that you may guarantee that there is no data left in your store from a time before you called this method.

ObservableQuery

The current value of the variables for this query. Can change.

Return the result of the query from the local cache as well as some fetching status loading and networkStatus allow to know if a request is in flight partial lets you know if the result from the local cache is complete or partial

Update the variables of this observable query, and fetch the new results if they've changed. If you want to force new results, use refetch.

Arguments

variables any
tryFetch any

ApolloError

Options

errorMessage any
extraInfo any
graphQLErrors any
networkError any

DataProxy

An interface to the normalized data in your store. ApolloClient implements this interface and so do various other objects you may receive when updating the store. A DataProxy is used in the update function on client.mutate to give you a window into your normalized data.

This interface is currently only used in the context of the update function provided to ApolloClient.mutate.

Reads a GraphQL query from the root query id.

Options

query DocumentNode

The 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 Object

Any variables that the GraphQL query may depend on.

Reads a GraphQL fragment from any arbitrary id. If there are more then one fragments in the provided document then a fragmentName must be provided to select the correct fragment.

Options

fragment DocumentNode

A 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 then one fragment in this document then you must also specify fragmentName to select a single.

fragmentName any

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

id any

The root id to be used. This id should take the same form as the value returned by your dataIdFromObject function. If a value with your id does not exist in the store, null will be returned.

variables Object

Any variables that your GraphQL fragments depend on.

Writes a GraphQL query to the root query id.

Options

data any

The data you will be writing to the store.

query DocumentNode

The 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 Object

Any variables that the GraphQL query may depend on.

Writes a GraphQL fragment to any arbitrary id. If there are more then one fragments in the provided document then a fragmentName must be provided to select the correct fragment.

Options

data any

The data you will be writing to the store.

fragment DocumentNode

A 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 then one fragment in this document then you must also specify fragmentName to select a single.

fragmentName any

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

id any

The root id to be used. This id should take the same form as the value returned by your dataIdFromObject function.

variables Object

Any variables that your GraphQL fragments depend on.

Utilities

Types

Properties

data any
loading any
networkStatus NetworkStatus
stale any

Properties

data any
error ApolloError
loading any
networkStatus NetworkStatus
partial any

This is an interface that describes the behavior of a Apollo store, which is currently implemented through redux.

Properties

dispatch (QueryResultAction | QueryErrorAction | QueryInitAction | QueryResultClientAction | QueryStopAction | MutationInitAction | MutationResultAction | MutationErrorAction | UpdateQueryResultAction | StoreResetAction | SubscriptionResultAction | WriteAction) => any
getState () => any

The current status of a query’s execution in our system.

Properties

[others:undefined] any
_afterwares any
_middlewares any
_opts RequestInit
_uri any
query (Request) => Promise<ExecutionResult>
use (any) => HTTPNetworkInterface
useAfter (any) => HTTPNetworkInterface

Properties

[others:undefined] any
batchQuery (any) => Promise<>
query (Request) => Promise<ExecutionResult>

This is a normalized representation of the Apollo query result cache. It consists of a flattened representation of query result trees.

Properties

[dataId:undefined] StoreObject

This is a normalized representation of the Apollo query result cache. It consists of a flattened representation of query result trees.

Properties

addTypename any
customResolvers [typeName:undefined]:[fieldName:undefined]:(any, [argName:undefined]:any) => any
dataIdFromObject (Object) => any
fragmentMatcher FragmentMatcher

This is an interface that describes an GraphQL document to be sent to the server.

Properties

[additionalKey:undefined] any

This is an interface that describes an GraphQL document to be sent to the server.

debugName any
operationName any
query DocumentNode
variables Object

Properties

[storeFieldKey:undefined] any
___typename any

This is an interface that describes a map from fragment names to fragment definitions.

Properties

[fragmentName:undefined] FragmentDefinitionNode

This is an interface that describes a map from fragment names to fragment definitions.

Properties

complete any
error any
next any

Properties

unsubscribe () => any
Edit on GitHub