ApolloClient

Launch Apollo Studio

The ApolloClient class encapsulates Apollo's core client-side API. It backs all available view-layer integrations (React, iOS, and so on).

The `ApolloClient` constructor

`constructor(options)`

(src/core/ApolloClient.ts, line 78)

Constructs an instance of ApolloClient.

The constructor for ApolloClient accepts an ApolloClientOptions object that supports the required and optional fields listed below. These fields make it easy to customize how Apollo works based on your application's needs.

Example constructor call

import { ApolloClient, InMemoryCache, createHttpLink } from '@apollo/client';

// Instantiate required constructor fields
const cache = new InMemoryCache();
const link = createHttpLink({
  uri: 'http://localhost:4000/',
});

const client = new ApolloClient({
  // Provide required constructor fields
  cache: cache,
  link: link,

  // Provide some optional constructor fields
  name: 'react-web-client',
  version: '1.3',
  queryDeduplication: false,
  defaultOptions: {
    watchQuery: {
      fetchPolicy: 'cache-and-network',
    },
  },
});

Required fields

Name	Description
`uri`	A URI pointing to the backend GraphQL endpoint that Apollo Client will communicate with. Note: One of `uri` or `link` is required; if both are specified, `link` will take precedence.
`link`	You can provide an Apollo Link instance to serve as Apollo Client's network layer. For more information, see the advanced HTTP networking section. Note: One of `uri` or `link` is required; if both are specified, `link` will take precedence.
`cache`	Apollo Client uses an Apollo Cache instance to handle its caching strategy. The recommended cache is `InMemoryCache` which is provided by the `@apollo/client` package. For more information, see Configuring the cache.

Optional fields

Name	Description
`name`	A custom name (e.g., `iOS`) that identifies this particular client among your set of clients. Apollo Server uses this property as part of its Client Awareness feature.
`version`	A custom version that identifies the current version of this particular client (e.g., `1.2`). Apollo Server uses this property as part of its Client Awareness feature. Note that this version string is not the version of Apollo Client that you are using, but rather any version string that helps you differentiate between versions of your client.
`ssrMode`	When using Apollo Client for server-side rendering, set this to `true` so that React Apollo's `getDataFromTree` function can work effectively.
`ssrForceFetchDelay`	Provide this to specify a time interval (in milliseconds) before Apollo Client force-fetches queries after a server-side render. This value is `0` by default.
`connectToDevTools`	Set this to `true` to allow the Apollo Client Devtools Chrome extension to connect to your application's Apollo Client in production. (This connection is allowed automatically in dev mode.)
`queryDeduplication`	Set this to `false` to force all created queries to be sent to the server, even if a query with completely identical parameters (query, variables, operationName) is already in flight.
`defaultOptions`	Provide this object to set application-wide default values for options you can provide to the `watchQuery`, `query`, and `mutate` functions. See below for an example object.

Example `defaultOptions` object

const defaultOptions = {
  watchQuery: {
    fetchPolicy: 'cache-and-network',
    errorPolicy: 'ignore',
  },
  query: {
    fetchPolicy: 'network-only',
    errorPolicy: 'all',
  },
  mutate: {
    errorPolicy: 'all',
  },
};

You can override any default option you specify in this object by providing a different value for the same option in individual function calls.

Note: The <Query /> React component uses Apollo Client's watchQuery function. To set defaultOptions when using the <Query /> component, make sure to set them under the defaultOptions.watchQuery property.

`ApolloClient` functions

`watchQuery(options): ObservableQuery<, >`

(src/core/ApolloClient.ts, line 279)

This watches the cache store 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 when the cache store changes.

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" | "network-only" | "cache-only" | "no-cache" | "standby" | "cache-and-network": Specifies the FetchPolicy to be used for this query.
nextFetchPolicy "cache-first" | "network-only" | "cache-only" | "no-cache" | "standby" | "cache-and-network": Specifies the FetchPolicy to be used after this query has completed.
notifyOnNetworkStatusChange any: Whether or not updates to the network status should trigger next on the observer of this query
partialRefetch any: If true, perform a query refetch if the query result is marked as being partial, and the returned data is reset to an empty Object by the Apollo Client QueryManager (due to a cache miss).
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.
returnPartialData any: Allow returning incomplete data from the cache when a larger query cannot be fully satisfied by the cache, instead of returning nothing.
variables TVariables: A map going from variable name to variable value, where the variables are used within the GraphQL query.

`query(options): Promise<ApolloQueryResult>`

(src/core/ApolloClient.ts, line 307)

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" | "network-only" | "cache-only" | "no-cache" | "standby": Specifies the FetchPolicy to be used for this query
query DocumentNode: A GraphQL document that consists of a single query to be sent down to the server.
variables TVariables: A map going from variable name to variable value, where the variables are used within the GraphQL query.

`mutate(options): Promise<FetchResult>`

(src/core/ApolloClient.ts, line 336)

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

awaitRefetchQueries any

By default, refetchQueries does not wait for the refetched queries to be completed, before resolving the mutation Promise. This ensures that query refetching does not hold up mutation response handling (query refetching is handled asynchronously). Set awaitRefetchQueries to true if you would like to wait for the refetched queries to complete, before the mutation can be marked as resolved.

context any

The context to be passed to the link execution chain. This context will only be used with the mutation. It will not be used with refetchQueries. Refetched queries use the context they were initialized with (since the intitial context is stored as part of the ObservableQuery instance). If a specific context is needed when refetching queries, make sure it is configured (via the query context option) when the query is first initialized/run.

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

Specifies the ErrorPolicy to be used for this operation

fetchPolicy Extract<"cache-first" | "network-only" | "cache-only" | "no-cache" | "standby", "no-cache">

Specifies the FetchPolicy to be used for this query. Mutations only support a 'no-cache' fetchPolicy. If you don't want to disable the cache, remove your fetchPolicy setting to proceed with the default mutation behavior.

mutation DocumentNode

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

optimisticResponse any

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 (ApolloCache<>, 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.

Note that since this function is intended to be used to update the store, it cannot be used with a no-cache fetch policy. If you're interested in performing some action after a mutation has completed, and you don't need to update the store, use the Promise returned from client.mutate instead.

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 TVariables

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

`subscribe(options): Observable<FetchResult>`

(src/core/ApolloClient.ts, line 349)

This subscribes to a graphql subscription according to the options specified and returns an Observable which either emits received data or an error.

Options

context Record<, >: Context object to be passed through the link execution chain.
fetchPolicy "cache-first" | "network-only" | "cache-only" | "no-cache" | "standby": Specifies the FetchPolicy to be used for this subscription.
query DocumentNode: A GraphQL document, often created with gql from the graphql-tag package, that contains a single subscription inside of it.
variables TVariables: An object that maps from the name of a variable as used in the subscription GraphQL document to that variable's value.

`readQuery(options, optimistic): any`

(src/core/ApolloClient.ts, line 364)

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.

Arguments

optimistic any: Set to true to allow readQuery to return optimistic results. Is false by default.

`readFragment(options, optimistic): any`

(src/core/ApolloClient.ts, line 385)

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.

Arguments

optimistic any: Set to true to allow readFragment to return optimistic results. Is false by default.

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 than 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 TVariables: Any variables that your GraphQL fragments depend on.

`writeQuery(options): any`

(src/core/ApolloClient.ts, line 397)

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 specific id returned by dataIdFromObject then use writeFragment.

Options

broadcast any: Whether to notify query watchers (default: true).
data any: The data you will be writing to the store.
id any: The 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.
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 TVariables: Any variables that the GraphQL query may depend on.

`writeFragment(options): any`

(src/core/ApolloClient.ts, line 415)

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

broadcast any: Whether to notify query watchers (default: true).
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 read. If you provide more than 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 TVariables: Any variables that your GraphQL fragments depend on.

`resetStore(): Promise<>`

(src/core/ApolloClient.ts, line 446)

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.

`onResetStore(cb): () => any`

(src/core/ApolloClient.ts, line 468)

Allows callbacks to be registered that are executed when the store is reset. onResetStore returns an unsubscribe function that can be used to remove registered callbacks.

Arguments

cb () => Promise<>

Arguments

cb () => Promise<>

`stop(): any`

Arguments

includeStandby any

Properties

assumeImmutableResults any
cache ApolloCache<>
connectToDevTools any
credentials any
defaultOptions DefaultOptions
fragmentMatcher (any, any, any) => any
headers Record<, >
link ApolloLink
name any
queryDeduplication any
resolvers any
ssrForceFetchDelay any
ssrMode any
typeDefs any
uri any
version any

`DefaultOptions`

(src/core/ApolloClient.ts, line 32)

Properties

mutate Partial<MutationOptions>
query Partial<QueryOptions>
watchQuery Partial<WatchQueryOptions>

ApolloClient

ApolloClient API reference

.css-2inqlj{padding:0 !important;background:none !important;}constructor(options)

Options

Options

Options

Options

Arguments

Arguments

Options

Options

Options

Arguments

Arguments

Arguments

Properties

Properties

Apollo Platform

`constructor(options)`