Docs
Launch GraphOS Studio

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.

result

Example

Signature

function result(): Promise<ApolloQueryResult<TData>>

Result

Promise<ApolloQueryResult<TData>>
Show/hide child attributes
Other

data

TData
ApolloError

The single Error object that is passed to onError and use hooks, and is often thrown during manual client.query calls. This will contain both a NetworkError and any Errors. See https://www.apollographql.com/docs/react/data/error-handling/ for more information.

ReadonlyArray<GraphQLError>

A list of any errors that occurred during server-side execution of a . See https://www.apollographql.com/docs/react/data/error-handling/ for more information.

boolean
NetworkStatus

Example

Signature

function getCurrentResult(
saveAsLastResult?: boolean
): ApolloQueryResult<TData>

Parameters

Result

ApolloQueryResult<TData>
Show/hide child attributes
Other
TData
ApolloError

The single Error object that is passed to onError and use hooks, and is often thrown during manual client.query calls. This will contain both a NetworkError and any Errors. See https://www.apollographql.com/docs/react/data/error-handling/ for more information.

ReadonlyArray<GraphQLError>

A list of any errors that occurred during server-side execution of a . See https://www.apollographql.com/docs/react/data/error-handling/ for more information.

boolean
NetworkStatus

Update the of this observable , 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

Name / Type
Description

variables (optional)

Partial<TVariables>

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

Result

Promise<ApolloQueryResult<TData>>
Show/hide child attributes
Other
TData
ApolloError

The single Error object that is passed to onError and use hooks, and is often thrown during manual client.query calls. This will contain both a NetworkError and any Errors. See https://www.apollographql.com/docs/react/data/error-handling/ for more information.

ReadonlyArray<GraphQLError>

A list of any errors that occurred during server-side execution of a . See https://www.apollographql.com/docs/react/data/error-handling/ for more information.

boolean
NetworkStatus

Example

Signature

function setOptions(
newOptions: Partial<WatchQueryOptions<TVariables, TData>>
): Promise<ApolloQueryResult<TData>>

Parameters

Name / Type
Description

newOptions

Partial<WatchQueryOptions<TVariables, TData>>
Show/hide child attributes
Operation options

Specifies how the handles a response that returns both errors and partial results.

For details, see GraphQL error policies.

The default value is none, meaning that the result includes error details but not partial results.

DocumentNode | TypedDocumentNode<TData, TVariables>

A string parsed into an AST with the gql template literal.

An object containing all of the your requires to execute.

Each key in the object corresponds to a name, and that key's value corresponds to the variable value.

Networking options
DefaultContext

If 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 's associated component re-renders whenever the network status changes or a network error occurs.

The default value is false.

Specifies the interval (in milliseconds) at which the polls for updated results.

The default value is 0 (no polling).

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

Caching options
WatchQueryFetchPolicy

Specifies how the interacts with the 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.

WatchQueryFetchPolicy

Defaults to the initial value of options.fetchPolicy, but can be explicitly configured to specify the WatchFetchPolicy to revert back to whenever change (unless nextFetchPolicy intervenes).

WatchQueryFetchPolicy | ((this: WatchQueryOptions<TVariables, TData>, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext<TData, TVariables>) => WatchQueryFetchPolicy)

Specifies the FetchPolicy to be used after this has completed.

Specifies whether a NetworkStatus.refetch should merge incoming data with existing data, or overwrite the existing data. Overwriting is probably preferable, but merging is currently the default behavior, for backwards compatibility with 3.x.

If true, the can return partial results from the cache if the cache doesn't contain results for all queried .

The default value is false.

Other

⚠️ Deprecated

Using canonizeResults can result in memory leaks so we generally do not recommend using this option anymore. A future version of 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.

⚠️ Deprecated

Setting this option is unnecessary in 3, thanks to a more consistent application of fetch policies. It might be removed in a future release.

If true, causes a refetch if the query result is detected as partial.

The default value is false.

Result

Promise<ApolloQueryResult<TData>>
Show/hide child attributes
Other
TData
ApolloError

The single Error object that is passed to onError and use hooks, and is often thrown during manual client.query calls. This will contain both a NetworkError and any Errors. See https://www.apollographql.com/docs/react/data/error-handling/ for more information.

ReadonlyArray<GraphQLError>

A list of any errors that occurred during server-side execution of a . See https://www.apollographql.com/docs/react/data/error-handling/ for more information.

boolean
NetworkStatus

Update the of this observable , 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 have not changed or if the result is coming from cache.

Note: the promise will return the old results immediately if the have not changed.

Note: the promise will return null immediately if the is not active (there are no subscribers).

Signature

function setVariables(
variables: TVariables
): Promise<ApolloQueryResult<TData> | void>

Parameters

Name / Type
Description

variables

TVariables

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

Result

Promise<ApolloQueryResult<TData> | void>
Show/hide child attributes
Other
TData
ApolloError

The single Error object that is passed to onError and use hooks, and is often thrown during manual client.query calls. This will contain both a NetworkError and any Errors. See https://www.apollographql.com/docs/react/data/error-handling/ for more information.

ReadonlyArray<GraphQLError>

A list of any errors that occurred during server-side execution of a . See https://www.apollographql.com/docs/react/data/error-handling/ for more information.

boolean
NetworkStatus

A 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

Name / Type
Description

fetchMoreOptions

FetchMoreQueryOptions<TFetchVars, TFetchData> & { updateQuery?: (previousQueryResult: TData, options: { fetchMoreResult: TFetchData; variables: TFetchVars; }) => TData; }

Result

Promise<ApolloQueryResult<TFetchData>>
Show/hide child attributes
Other
TFetchData
ApolloError

The single Error object that is passed to onError and use hooks, and is often thrown during manual client.query calls. This will contain both a NetworkError and any Errors. See https://www.apollographql.com/docs/react/data/error-handling/ for more information.

ReadonlyArray<GraphQLError>

A list of any errors that occurred during server-side execution of a . See https://www.apollographql.com/docs/react/data/error-handling/ for more information.

boolean
NetworkStatus

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

See using updateQuery and updateFragment for additional information.

Signature

function updateQuery(
mapFn: (previousQueryResult: TData, options: Pick<WatchQueryOptions<TVars, TData>, "variables">) => TData
): void

Parameters

Name / Type
Description

mapFn

(previousQueryResult: TData, options: Pick<WatchQueryOptions<TVars, TData>, "variables">) => TData

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

Signature

function startPolling(
pollInterval: number
): void

Parameters

Name / Type
Description

A function that instructs the 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 that were included in the .

This function returns another function that you can call to terminate the .

Signature

function subscribeToMore(
options: SubscribeToMoreOptions<TData, TSubscriptionVariables, TSubscriptionData>
): () => void

Parameters

Name / Type
Description

options

SubscribeToMoreOptions<TData, TSubscriptionVariables, TSubscriptionData>

Result

() => void

Types

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

Enumeration Members

error

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

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

The 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 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 , and no errors happened. Everything is OK.

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

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

Properties

Name / Type
Description
Other
ApolloError

The single Error object that is passed to onError and use hooks, and is often thrown during manual client.query calls. This will contain both a NetworkError and any Errors. See https://www.apollographql.com/docs/react/data/error-handling/ for more information.

ReadonlyArray<GraphQLError>

A list of any errors that occurred during server-side execution of a . See https://www.apollographql.com/docs/react/data/error-handling/ for more information.

boolean
NetworkStatus
Previous
InMemoryCache
Next
Hooks
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company