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:

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

context any

Context to be passed to link execution chain

errorPolicy "none" | "ignore" | "all"

Specifies the ErrorPolicy to be used for this query

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

Specifies the FetchPolicy to be used for this query

fetchResults any

Whether or not to fetch results

metadata any

Arbitrary metadata stored in the store 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.

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

context any

Context to be passed to link execution chain

errorPolicy "none" | "ignore" | "all"

Specifies the ErrorPolicy to be used for this query

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

Specifies the FetchPolicy to be used for this query

fetchResults any

Whether or not to fetch results

metadata any

Arbitrary metadata stored in the store 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.

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

context any

Context to be passed to link execution chain

errorPolicy "none" | "ignore" | "all"

Specifies the ErrorPolicy to be used for this operation

mutation DocumentNode

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

optimisticResponse Object | Function

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, FetchResult<>) => 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]:(Record<,>, any) => Record<,><><>

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 any

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

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

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

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

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
fetchResults any

Types

Properties

cache ApolloCache<>
connectToDevTools any
defaultOptions DefaultOptions
link ApolloLink
queryDeduplication any
ssrForceFetchDelay any
ssrMode any

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

Edit on GitHub