ObservableQuery
API reference
ObservableQuery functions
ApolloClient Observables extend the Observables implementation provided by zen-observable. Refer to the zen-observable documentation for additional context and API options.
Example
Signature
function result(): Promise<ApolloQueryResult<TData>>
Result
Promise<ApolloQueryResult<TData>>
Show/hide child attributes
TDataApolloErrorThe single Error object that is passed to onError and useQuery hooks, and is often thrown during manual client.query calls. This will contain both a NetworkError field and any GraphQLErrors. See https://www.apollographql.com/docs/react/data/error-handling/ for more information.
ReadonlyArray<GraphQLFormattedError>A list of any errors that occurred during server-side execution of a GraphQL operation. See https://www.apollographql.com/docs/react/data/error-handling/ for more information.
booleanNetworkStatusbooleanExample
Signature
function getCurrentResult(saveAsLastResult?: boolean): ApolloQueryResult<TData>
Parameters
Result
ApolloQueryResult<TData>
Show/hide child attributes
TDataApolloErrorThe single Error object that is passed to onError and useQuery hooks, and is often thrown during manual client.query calls. This will contain both a NetworkError field and any GraphQLErrors. See https://www.apollographql.com/docs/react/data/error-handling/ for more information.
ReadonlyArray<GraphQLFormattedError>A list of any errors that occurred during server-side execution of a GraphQL operation. See https://www.apollographql.com/docs/react/data/error-handling/ for more information.
booleanNetworkStatusbooleanUpdate the variables of this observable query, and fetch the new results. This method should be preferred over setVariables in most use cases.
Signature
function refetch(variables?: Partial<TVariables>): Promise<ApolloQueryResult<TData>>
Parameters
variables (optional)
Partial<TVariables>The new set of variables. If there are missing variables, the previous values of those variables will be used.
Result
Promise<ApolloQueryResult<TData>>
Show/hide child attributes
TDataApolloErrorThe single Error object that is passed to onError and useQuery hooks, and is often thrown during manual client.query calls. This will contain both a NetworkError field and any GraphQLErrors. See https://www.apollographql.com/docs/react/data/error-handling/ for more information.
ReadonlyArray<GraphQLFormattedError>A list of any errors that occurred during server-side execution of a GraphQL operation. See https://www.apollographql.com/docs/react/data/error-handling/ for more information.
booleanNetworkStatusbooleanExample
Signature
function setOptions(newOptions: Partial<WatchQueryOptions<TVariables, TData>>): Promise<ApolloQueryResult<TData>>
Parameters
newOptions
Partial<WatchQueryOptions<TVariables, TData>>Show/hide child attributes
ErrorPolicySpecifies how the query handles a response that returns both GraphQL errors and partial results.
For details, see GraphQL error policies.
The default value is none, meaning that the query result includes error details but not partial results.
DocumentNode | TypedDocumentNode<TData, TVariables>A GraphQL query string parsed into an AST with the gql template literal.
TVariablesAn object containing all of the GraphQL variables your query requires to execute.
Each key in the object corresponds to a variable name, and that key's value corresponds to the variable value.
DefaultContextIf you're using Apollo Link, this object is the initial value of the context object that's passed along your link chain.
If true, the in-progress query's associated component re-renders whenever the network status changes or a network error occurs.
The default value is false.
numberSpecifies the interval (in milliseconds) at which the query polls for updated results.
The default value is 0 (no polling).
() => booleanA callback function that's called whenever a refetch attempt occurs while polling. If the function returns true, the refetch is skipped and not reattempted until the next poll interval.
WatchQueryFetchPolicySpecifies how the query interacts with the Apollo Client cache during execution (for example, whether it checks the cache for results before sending a request to the server).
For details, see Setting a fetch policy.
The default value is cache-first.
WatchQueryFetchPolicyDefaults to the initial value of options.fetchPolicy, but can be explicitly configured to specify the WatchQueryFetchPolicy to revert back to whenever variables change (unless nextFetchPolicy intervenes).
WatchQueryFetchPolicy | ((this: WatchQueryOptions<TVariables, TData>, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext<TData, TVariables>) => WatchQueryFetchPolicy)Specifies the FetchPolicy to be used after this query has completed.
RefetchWritePolicySpecifies whether a NetworkStatus.refetch operation should merge incoming field data with existing data, or overwrite the existing data. Overwriting is probably preferable, but merging is currently the default behavior, for backwards compatibility with Apollo Client 3.x.
booleanIf true, the query can return partial results from the cache if the cache doesn't contain results for all queried fields.
The default value is false.
boolean⚠️ Deprecated
Using canonizeResults can result in memory leaks so we generally do not recommend using this option anymore. A future version of Apollo Client will contain a similar feature without the risk of memory leaks.
Whether to canonize cache results before returning them. Canonization takes some extra time, but it speeds up future deep equality comparisons. Defaults to false.
boolean⚠️ Deprecated
Setting this option is unnecessary in Apollo Client 3, thanks to a more consistent application of fetch policies. It might be removed in a future release.
If true, causes a query refetch if the query result is detected as partial.
The default value is false.
Result
Promise<ApolloQueryResult<TData>>
Show/hide child attributes
TDataApolloErrorThe single Error object that is passed to onError and useQuery hooks, and is often thrown during manual client.query calls. This will contain both a NetworkError field and any GraphQLErrors. See https://www.apollographql.com/docs/react/data/error-handling/ for more information.
ReadonlyArray<GraphQLFormattedError>A list of any errors that occurred during server-side execution of a GraphQL operation. See https://www.apollographql.com/docs/react/data/error-handling/ for more information.
booleanNetworkStatusbooleanUpdate 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: the next callback will not fire if the variables have not changed or if the result is coming from cache.
Note: the promise will return the old results immediately if the variables have not changed.
Note: the promise will return null immediately if the query is not active (there are no subscribers).
Signature
function setVariables(variables: TVariables): Promise<ApolloQueryResult<TData> | void>
Parameters
variables
TVariablesThe new set of variables. If there are missing variables, the previous values of those variables will be used.
Result
Promise<ApolloQueryResult<TData> | void>
Show/hide child attributes
TDataApolloErrorThe single Error object that is passed to onError and useQuery hooks, and is often thrown during manual client.query calls. This will contain both a NetworkError field and any GraphQLErrors. See https://www.apollographql.com/docs/react/data/error-handling/ for more information.
ReadonlyArray<GraphQLFormattedError>A list of any errors that occurred during server-side execution of a GraphQL operation. See https://www.apollographql.com/docs/react/data/error-handling/ for more information.
booleanNetworkStatusbooleanA function that helps you fetch the next set of results for a paginated list field.
Signature
function fetchMore(fetchMoreOptions: FetchMoreQueryOptions<TFetchVars, TFetchData> & {updateQuery?: (previousQueryResult: TData, options: {fetchMoreResult: TFetchData;variables: TFetchVars;}) => TData;}): Promise<ApolloQueryResult<TFetchData>>
Parameters
fetchMoreOptions
FetchMoreQueryOptions<TFetchVars, TFetchData> & {
updateQuery?: (previousQueryResult: TData, options: {
fetchMoreResult: TFetchData;
variables: TFetchVars;
}) => TData;
}Result
Promise<ApolloQueryResult<TFetchData>>
Show/hide child attributes
TFetchDataApolloErrorThe single Error object that is passed to onError and useQuery hooks, and is often thrown during manual client.query calls. This will contain both a NetworkError field and any GraphQLErrors. See https://www.apollographql.com/docs/react/data/error-handling/ for more information.
ReadonlyArray<GraphQLFormattedError>A list of any errors that occurred during server-side execution of a GraphQL operation. See https://www.apollographql.com/docs/react/data/error-handling/ for more information.
booleanNetworkStatusbooleanA function that enables you to update the query's cached result without executing a followup GraphQL operation.
See using updateQuery and updateFragment for additional information.
Signature
function updateQuery(mapFn: (previousQueryResult: TData, options: Pick<WatchQueryOptions<TVars, TData>, "variables">) => TData): void
Parameters
mapFn
(previousQueryResult: TData, options: Pick<WatchQueryOptions<TVars, TData>, "variables">) => TDataA function that instructs the query to begin re-executing at a specified interval (in milliseconds).
Signature
function startPolling(pollInterval: number): void
Parameters
A function that instructs the query to stop polling after a previous call to startPolling.
Signature
function stopPolling(): void
A function that enables you to execute a subscription, 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.
Signature
function subscribeToMore(options: SubscribeToMoreOptions<TData, TSubscriptionVariables, TSubscriptionData>): () => void
Parameters
options
SubscribeToMoreOptions<TData, TSubscriptionVariables, TSubscriptionData>Result
() => void
Types
The current status of a query’s execution in our system.
Enumeration Members
No request is in flight for this query, but one or more errors were detected.
Indicates that fetchMore was called on this query and that the query created is currently in flight.
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.
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.
No request is in flight for this query, and no errors happened. Everything is OK.
Similar to the setVariables network status. It means that refetch was called on a query and the refetch request is currently in flight.
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.
Properties
TApolloErrorThe single Error object that is passed to onError and useQuery hooks, and is often thrown during manual client.query calls. This will contain both a NetworkError field and any GraphQLErrors. See https://www.apollographql.com/docs/react/data/error-handling/ for more information.
ReadonlyArray<GraphQLFormattedError>A list of any errors that occurred during server-side execution of a GraphQL operation. See https://www.apollographql.com/docs/react/data/error-handling/ for more information.
booleanNetworkStatusboolean