@apollo/client

constructor

constructor(options: ApolloClient.Options);

• Constructs an instance of ApolloClient.

  Example 1

  import { ApolloClient, InMemoryCache, HttpLink } from "@apollo/client";
  
  const cache = new InMemoryCache();
  const link = new HttpLink({ uri: "http://localhost:4000/" });
  
  const client = new ApolloClient({
    // Provide required constructor fields
    cache: cache,
    link: link,
  
    // Provide some optional constructor fields
    clientAwareness: {
      name: "react-web-client",
      version: "1.3",
    },
    queryDeduplication: false,
  });

property cache

cache: ApolloCache;

property defaultContext

readonly defaultContext: Partial<DefaultContext>;

property defaultOptions

defaultOptions: DefaultOptions;

property devtoolsConfig

readonly devtoolsConfig: ApolloClient.DevtoolsOptions;

property disableNetworkFetches

disableNetworkFetches: never;

• Deprecated

  disableNetworkFetches has been renamed to prioritizeCacheValues.

property documentTransform

readonly documentTransform: DocumentTransform;

• The DocumentTransform used to modify GraphQL documents before a request is made. If a custom DocumentTransform is not provided, this will be the default document transform.

property getMemoryInternals

getMemoryInternals?: any;

• This is not a stable API - it is used in development builds to expose information to the DevTools. Use at your own risk! For more details, see [Memory Management](https://www.apollographql.com/docs/react/caching/memory-management/#measuring-cache-usage)

  Example 1

  console.log(client.getMemoryInternals());

  Logs output in the following JSON format:

  Example 2

  {
    "limits": {
      "canonicalStringify": 1000,
      "print": 2000,
      "documentTransform.cache": 2000,
      "queryManager.getDocumentInfo": 2000,
      "PersistedQueryLink.persistedQueryHashes": 2000,
      "fragmentRegistry.transform": 2000,
      "fragmentRegistry.lookup": 1000,
      "fragmentRegistry.findFragmentSpreads": 4000,
      "cache.fragmentQueryDocuments": 1000,
      "removeTypenameFromVariables.getVariableDefinitions": 2000,
      "inMemoryCache.maybeBroadcastWatch": 5000,
      "inMemoryCache.executeSelectionSet": 10000,
      "inMemoryCache.executeSubSelectedArray": 5000
    },
    "sizes": {
      "canonicalStringify": 4,
      "print": 14,
      "addTypenameDocumentTransform": [
        {
          "cache": 14
        }
      ],
      "queryManager": {
        "getDocumentInfo": 14,
        "documentTransforms": [
          {
            "cache": 14
          },
          {
            "cache": 14
          }
        ]
      },
      "fragmentRegistry": {
        "findFragmentSpreads": 34,
        "lookup": 20,
        "transform": 14
      },
      "cache": {
        "fragmentQueryDocuments": 22
      },
      "inMemoryCache": {
        "executeSelectionSet": 4345,
        "executeSubSelectedArray": 1206,
        "maybeBroadcastWatch": 32
      },
      "links": [
        {
          "PersistedQueryLink": {
            "persistedQueryHashes": 14
          }
        },
        {
          "removeTypenameFromVariables": {
            "getVariableDefinitions": 14
          }
        }
      ]
    }
  }

  Modifiers

  • @experimental

property link

link: ApolloLink;

property localState

localState: any;

• The configured LocalState instance used to enable the use of @client fields.

property mutate

mutate: ApolloClient.mutate.Signature;

• 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. In some cases both data and errors might be undefined, for example when errorPolicy is set to 'ignore'.

  It takes options as an object with the following keys and values:

property prioritizeCacheValues

prioritizeCacheValues: boolean;

• Whether to prioritize cache values over network results when query or watchQuery is called. This will essentially turn a "network-only" or "cache-and-network" fetchPolicy into a "cache-first" fetchPolicy, but without influencing the fetchPolicy of the created ObservableQuery long-term.

  This can e.g. be used to prioritize the cache during the first render after SSR.

property query

query: ApolloClient.query.Signature;

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

  Parameter options

  An object of type QueryOptions that allows us to describe how this query should be treated e.g. whether it should hit the server at all or just resolve from the cache, etc.

property queryDeduplication

queryDeduplication: boolean;

property refetchEventManager

readonly refetchEventManager: RefetchEventManager;

property reFetchObservableQueries

reFetchObservableQueries: (
    includeStandby?: boolean
) => Promise<ApolloClient.QueryResult<any>[]>;

• Refetches all of your active queries.

  reFetchObservableQueries() is useful if you want to bring the client back to proper state in case of a network outage

  It is important to remember that reFetchObservableQueries() _will_ refetch any active queries. This means that any components that might be mounted will execute their queries again using your network interface. If you do not want to re-execute any queries then you should make sure to stop watching any active queries. Takes optional parameter includeStandby which will include queries in standby-mode when refetching.

  Note: cache-only queries are not refetched by this function.

  Deprecated

  Please use refetchObservableQueries instead.

property version

version: string;

method clearStore

clearStore: () => Promise<any[]>;

• Remove all data from the store. Unlike resetStore, clearStore will not refetch any active queries.

method extract

extract: (optimistic?: boolean) => unknown;

• Exposes the cache's complete state, in a serializable format for later restoration.

  Parameter optimistic

  Determines whether the result contains data from the optimistic layer

  Remarks

  This can be useful for debugging in order to inspect the full state of the cache.

method getObservableQueries

getObservableQueries: (
    include?: RefetchQueriesInclude
) => Set<ObservableQuery<any>>;

• Get all currently active ObservableQuery objects, in a Set.

  An "active" query is one that has observers and a fetchPolicy other than "standby" or "cache-only".

  You can include all ObservableQuery objects (including the inactive ones) by passing "all" instead of "active", or you can include just a subset of active queries by passing an array of query names or DocumentNode objects.

  Note: This method only returns queries that have active subscribers. Queries without subscribers are not tracked by the client.

method onClearStore

onClearStore: (cb: () => Promise<any>) => () => void;

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

method onResetStore

onResetStore: (cb: () => Promise<any>) => () => void;

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

method readFragment

readFragment: {
    <
        TData = unknown,
        TVariables extends OperationVariables = OperationVariables
    >(
        options: ApolloClient.ReadFragmentOptions<TData, TVariables>
    ): Unmasked<TData> | null;
    <
        TData = unknown,
        TVariables extends OperationVariables = OperationVariables
    >(
        options: any,
        optimistic: boolean
    ): any;
};

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

  You must pass in a GraphQL document with a single fragment or a document with multiple fragments that represent what you are reading. If you pass in a document with multiple fragments then you must also specify a fragmentName.

  Parameter optimistic

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

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

  You must pass in a GraphQL document with a single fragment or a document with multiple fragments that represent what you are reading. If you pass in a document with multiple fragments then you must also specify a fragmentName.

  Parameter optimistic

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

  Deprecated

  Pass the optimistic argument as part of the first argument instead of passing it as a separate option.

method readQuery

readQuery: {
    <
        TData = unknown,
        TVariables extends OperationVariables = OperationVariables
    >(
        options: ApolloClient.ReadQueryOptions<TData, TVariables>
    ): Unmasked<TData> | null;
    <
        TData = unknown,
        TVariables extends OperationVariables = OperationVariables
    >(
        options: any,
        optimistic: boolean
    ): any;
};

• 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 cache.identify use readFragment.

  Parameter optimistic

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

• 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 cache.identify use readFragment.

  Parameter optimistic

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

  Deprecated

  Pass the optimistic argument as part of the first argument instead of passing it as a separate option.

method refetchObservableQueries

refetchObservableQueries: (
    includeStandby?: boolean
) => Promise<ApolloClient.QueryResult<any>[]>;

• Refetches all of your active queries.

  refetchObservableQueries() is useful if you want to bring the client back to proper state in case of a network outage

  It is important to remember that refetchObservableQueries() _will_ refetch any active queries. This means that any components that might be mounted will execute their queries again using your network interface. If you do not want to re-execute any queries then you should make sure to stop watching any active queries. Takes optional parameter includeStandby which will include queries in standby-mode when refetching.

  Note: cache-only queries are not refetched by this function.

method refetchQueries

refetchQueries: <
    TCache extends ApolloCache = ApolloCache,
    TResult = Promise<{ data: any; error?: ErrorLike }>
>(
    options: ApolloClient.RefetchQueriesOptions<TCache, TResult>
) => ApolloClient.RefetchQueriesResult<TResult>;

• Refetches specified active queries. Similar to "refetchObservableQueries()" but with a specific list of queries.

  refetchQueries() is useful for use cases to imperatively refresh a selection of queries.

  It is important to remember that refetchQueries() _will_ refetch specified active queries. This means that any components that might be mounted will execute their queries again using your network interface. If you do not want to re-execute any queries then you should make sure to stop watching any active queries.

method resetStore

resetStore: () => Promise<ApolloClient.QueryResult<any>[] | null>;

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

  resetStore() is useful when your user just logged out. You’ve removed the user session, and you now want to make sure that any references to data you might have fetched while the user session was active is gone.

  It is important to remember that resetStore() _will_ refetch any active queries. This means that any components that might be mounted will execute their queries again using your network interface. If you do not want to re-execute any queries then you should make sure to stop watching any active queries.

method restore

restore: (serializedState: unknown) => ApolloCache;

• Replaces existing state in the cache (if any) with the values expressed by serializedState.

  Called when hydrating a cache (server side rendering, or offline storage), and also (potentially) during hot reloads.

method setLink

setLink: (newLink: ApolloLink) => void;

• Define a new ApolloLink (or link chain) that Apollo Client will use.

method stop

stop: () => void;

• Call this method to terminate any active client processes, making it safe to dispose of this ApolloClient instance.

  This method performs aggressive cleanup to prevent memory leaks:

  - Unsubscribes all active ObservableQuery instances by emitting a completed event - Rejects all currently running queries with "QueryManager stopped while query was in flight" - Removes all queryRefs from the suspense cache - Disconnects the RefetchEventManager if configured.

method subscribe

subscribe: <
    TData = unknown,
    TVariables extends OperationVariables = OperationVariables
>(
    options: ApolloClient.SubscribeOptions<TData, TVariables>
) => SubscriptionObservable<ApolloClient.SubscribeResult<MaybeMasked<TData>>>;

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

method watchFragment

watchFragment: {
    <
        TData = unknown,
        TVariables extends OperationVariables = OperationVariables
    >(
        options: ApolloClient.WatchFragmentOptions<TData, TVariables> & {
            from: Array<ApolloCache.FromOptionValue<TData>>;
        }
    ): ApolloClient.ObservableFragment<Array<TData>>;
    <
        TData = unknown,
        TVariables extends OperationVariables = OperationVariables
    >(
        options: any
    ): ApolloClient.ObservableFragment<null[]>;
    <
        TData = unknown,
        TVariables extends OperationVariables = OperationVariables
    >(
        options: any
    ): ApolloClient.ObservableFragment<TData[]>;
    <
        TData = unknown,
        TVariables extends OperationVariables = OperationVariables
    >(
        options: any
    ): ApolloClient.ObservableFragment<null>;
    <
        TData = unknown,
        TVariables extends OperationVariables = OperationVariables
    >(
        options: any
    ): ApolloClient.ObservableFragment<TData>;
    <
        TData = unknown,
        TVariables extends OperationVariables = OperationVariables
    >(
        options: ApolloCache.WatchFragmentOptions<TData, TVariables>
    ): ApolloClient.ObservableFragment<TData>;
};

• Watches the cache store of the fragment according to the options specified and returns an Observable. We can subscribe to this Observable and receive updated results through an observer when the cache store changes.

  You must pass in a GraphQL document with a single fragment or a document with multiple fragments that represent what you are reading. If you pass in a document with multiple fragments then you must also specify a fragmentName.

  3.10.0

  Parameter options

  An object of type WatchFragmentOptions that allows the cache to identify the fragment and optionally specify whether to react to optimistic updates.

• Watches the cache store of the fragment according to the options specified and returns an Observable. We can subscribe to this Observable and receive updated results through an observer when the cache store changes.

  You must pass in a GraphQL document with a single fragment or a document with multiple fragments that represent what you are reading. If you pass in a document with multiple fragments then you must also specify a fragmentName.

  3.10.0

  Parameter options

  An object of type WatchFragmentOptions that allows the cache to identify the fragment and optionally specify whether to react to optimistic updates.

method watchQuery

watchQuery: <
    TData = unknown,
    TVariables extends OperationVariables = OperationVariables
>(
    options: ApolloClient.WatchQueryOptions<TData, TVariables>
) => ObservableQuery<TData, TVariables>;

• 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 an observer when the cache store changes.

  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 a person's first and last name and this person has a particular object identifier, provided by cache.identify. Later, a different query fetches that same person's first and last name and the first name has now changed. Then, any observers associated with the results of the first query will be updated with a new result object.

  Note that if the cache does not change, the subscriber will _not_ be notified.

  See [here](https://medium.com/apollo-stack/the-concepts-of-graphql-bc68bd819be3#.3mb0cbcmc) for a description of store reactivity.

method writeFragment

writeFragment: <
    TData = unknown,
    TVariables extends OperationVariables = OperationVariables
>(
    options: ApolloClient.WriteFragmentOptions<TData, TVariables>
) => Reference | undefined;

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

  You must pass in a GraphQL document with a single fragment or a document with multiple fragments that represent what you are writing. If you pass in a document with multiple fragments then you must also specify a fragmentName.

method writeQuery

writeQuery: <
    TData = unknown,
    TVariables extends OperationVariables = OperationVariables
>(
    options: ApolloClient.WriteQueryOptions<TData, TVariables>
) => Reference | undefined;

• 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 cache.identify then use writeFragment.

constructor

constructor({
    queryManager,
    options,
    transformedQuery,
}: {
    queryManager: QueryManager;
    options: ApolloClient.WatchQueryOptions<TData, TVariables>;
    transformedQuery?: DocumentNode | TypedDocumentNode<TData, TVariables>;
    queryId?: string;
});

property ["@@observable"]

['@@observable']: () => Subscribable<
    ObservableQuery.Result<
        MaybeMasked<TData>,
        'empty' | 'complete' | 'streaming' | 'partial'
    >
>;

property [Symbol.observable]

[Symbol.observable]: () => Subscribable<
    ObservableQuery.Result<
        MaybeMasked<TData>,
        'empty' | 'complete' | 'streaming' | 'partial'
    >
>;

property options

readonly options: ObservableQuery.Options<TData, TVariables>;

property pipe

pipe: Observable<
    ObservableQuery.Result<
        MaybeMasked<TData>,
        'empty' | 'complete' | 'streaming' | 'partial'
    >
>;

• Used to stitch together functional operators into a chain.

  Returns

  The Observable result of all the operators having been called in the order they were passed in.

  Example 1

  import { filter, map } from 'rxjs';
  
  observableQuery
    .pipe(
      filter(...),
      map(...),
    )
    .subscribe(x => console.log(x));

property query

readonly query: TypedDocumentNode<TData, TVariables>;

property queryName

readonly queryName?: string;

property subscribe

subscribe: (observerOrNext: any) => Subscription;

• Subscribes to the ObservableQuery.

  Parameter observerOrNext

  Either an RxJS Observer with some or all callback methods, or the next handler that is called for each value emitted from the subscribed Observable.

  Returns

  A subscription reference to the registered handlers.

property variables

readonly variables: OperationVariables;

• An object containing the variables that were provided for the query.

method fetchMore

fetchMore: <
    TFetchData = TData,
    TFetchVars extends OperationVariables = TVariables
>(
    options: ObservableQuery.FetchMoreOptions<
        TData,
        TVariables,
        TFetchData,
        TFetchVars
    >
) => Promise<ApolloClient.QueryResult<TFetchData>>;

• A function that helps you fetch the next set of results for a [paginated list field](https://www.apollographql.com/docs/react/pagination/core-api/).

method getCurrentResult

getCurrentResult: () => ObservableQuery.Result<MaybeMasked<TData>>;

method hasObservers

hasObservers: () => boolean;

method refetch

refetch: (
    variables?: Partial<TVariables>
) => ObservableQuery.ResultPromise<ApolloClient.QueryResult<TData>>;

• Update the variables of this observable query, and fetch the new results. This method should be preferred over setVariables in most use cases.

  Returns a ResultPromise with an additional .retain() method. Calling .retain() keeps the network operation running even if the ObservableQuery no longer requires the result.

  Note: refetch() guarantees that a value will be emitted from the observable, even if the result is deep equal to the previous value.

  Parameter variables

  The new set of variables. If there are missing variables, the previous values of those variables will be used.

method reobserve

reobserve: (
    newOptions?: Partial<ObservableQuery.Options<TData, TVariables>>
) => ObservableQuery.ResultPromise<ApolloClient.QueryResult<MaybeMasked<TData>>>;

• Reevaluate the query, optionally against new options. New options will be merged with the current options when given.

  Note: variables can be reset back to their defaults (typically empty) by calling reobserve with variables: undefined.

method setVariables

setVariables: (
    variables: TVariables
) => Promise<ApolloClient.QueryResult<TData>>;

• Update the variables of this observable query, and fetch the new results if they've changed. Most users should prefer refetch instead of setVariables in order to to be properly notified of results even when they come from the cache.

  Note: setVariables() guarantees that a value will be emitted from the observable, even if the result is deeply equal to the previous value.

  Note: the promise will resolve with the last emitted result when either the variables match the current variables or there are no subscribers to the query.

  Parameter variables

  The new set of variables. If there are missing variables, the previous values of those variables will be used.

method startPolling

startPolling: (pollInterval: number) => void;

• A function that instructs the query to begin re-executing at a specified interval (in milliseconds).

method stop

stop: () => void;

• Tears down the ObservableQuery and stops all active operations by sending a complete notification.

method stopPolling

stopPolling: () => void;

• A function that instructs the query to stop polling after a previous call to startPolling.

method subscribeToMore

subscribeToMore: <
    TSubscriptionData = TData,
    TSubscriptionVariables extends OperationVariables = TVariables
>(
    options: ObservableQuery.SubscribeToMoreOptions<
        TData,
        TSubscriptionVariables,
        TSubscriptionData,
        TVariables
    >
) => () => void;

• A function that enables you to execute a [subscription](https://www.apollographql.com/docs/react/data/subscriptions/), usually to subscribe to specific fields that were included in the query.

  This function returns _another_ function that you can call to terminate the subscription.

method updateQuery

updateQuery: (mapFn: UpdateQueryMapFn<TData, TVariables>) => void;

• A function that enables you to update the query's cached result without executing a followup GraphQL operation.

  See [using updateQuery and updateFragment](https://www.apollographql.com/docs/react/caching/cache-interaction/#using-updatequery-and-updatefragment) for additional information.

constructor

constructor(options?: RefetchEventManager.Options);

method connect

connect: (client: ApolloClient) => void;

• Connects the client to this refetch event manager. Connecting a client calls each configured source function so they can begin listening for events.

method disconnect

disconnect: (client?: ApolloClient) => void;

• Disconnects the client from this refetch event manager and calls the cleanup function for each event source.

method emit

emit: <TSource extends keyof RefetchEvents>(
    source: TSource,
    ...args: RefetchEvents[TSource] extends void | never
        ? []
        : undefined extends RefetchEvents[TSource]
        ? [payload?: RefetchEvents[TSource]]
        : [payload: RefetchEvents[TSource]]
) => void;

• Manually triggers a refetch for the provided event.

  Remarks

  This method warns and does not refetch if the refetch event manager is not connected to a client or a source is not configured for the event.

method hasSource

hasSource: (source: keyof RefetchEvents) => boolean;

• Returns whether a source is configured.

method removeEventSource

removeEventSource: (event: keyof RefetchEvents) => void;

• Removes the configured source for an event and runs its cleanup function.

method setDefaultEventHandler

setDefaultEventHandler: (
    handler: RefetchEventManager.EventHandler<keyof RefetchEvents>
) => void;

• Replaces the default event handler with the provided handler.

method setEventHandler

setEventHandler: <TSource extends keyof RefetchEvents>(
    source: TSource,
    handler: RefetchEventManager.EventHandler<TSource>
) => void;

• Replaces the handler for an event.

method setEventSource

setEventSource: <TSource extends keyof RefetchEvents>(
    name: TSource,
    source: RefetchEventManager.EventSource<RefetchEvents[TSource]>
) => void;

• Replaces the source for an event. If a source was previously configured for the event, its cleanup function is called before the new source is registered.

property clientAwareness

clientAwareness?: ClientAwarenessLink.ClientAwarenessOptions;

property queryDeduplication

queryDeduplication?: boolean;

• Indicates whether queryDeduplication was enabled for the request.

property message

message: string;

property name

name: string;

property stack

stack?: string;

property include

include?: InternalRefetchQueriesInclude;

property removeOptimistic

removeOptimistic?: string;

property online

online: Event;

property windowFocus

windowFocus: Event;

call signature

<
    TSubscriptionData = TData,
    TSubscriptionVariables extends OperationVariables = TVariables
>(
    options: ObservableQuery.SubscribeToMoreOptions<
        TData,
        TSubscriptionVariables,
        TSubscriptionData,
        TVariables
    >
): () => void;

property restart

restart: () => void;

• Used to restart the connection to the link chain. Calling this on a deduplicated subscription will restart the connection for all observables that share the request.

  Example 1

  const observable = client.subscribe({ query: subscription });
  observable.subscribe((value) => {
    // ...
  });
  
  observable.restart();

call signature

(
    /**
     * @deprecated This value is not type-safe and may contain partial data. This
     * argument will be removed in Apollo Client v5. Use `options.previousData`
     * instead for a more type-safe value.
     */
    unsafePreviousData: DeepPartial<Unmasked<TData>>,
    options: UpdateQueryOptions<TData, TVariables>
): Unmasked<TData> | void;

member error

error = 8

• No request is in flight for this query, but one or more errors were detected.

member fetchMore

fetchMore = 3

• Indicates that fetchMore was called on this query and that the query created is currently in flight.

member loading

loading = 1

• The query has never been run before and the query is now currently running. A query will still have this network status even if a partial data result was returned from the cache, but a query was dispatched anyway.

member poll

poll = 6

• Indicates that a polling query is currently in flight. So for example if you are polling a query every 10 seconds then the network status will switch to poll every 10 seconds whenever a poll request has been sent but not resolved.

member ready

ready = 7

• No request is in flight for this query, and no errors happened. Everything is OK.

member refetch

refetch = 4

• Similar to the setVariables network status. It means that refetch was called on a query and the refetch request is currently in flight.

member setVariables

setVariables = 2

• If setVariables was called and a query was fired because of that then the network status will be setVariables until the result of that query comes back.

member streaming

streaming = 9

• Indicates that a @defer query has received at least the first chunk of the result but the full result has not yet been fully streamed to the client.