useBackgroundQuery
Apollo Client API reference
For a detailed explanation of useBackgroundQuery, see the fetching with Suspense reference.
Example
1 import { Suspense } from "react";
2 import { ApolloClient, InMemoryCache, HttpLink } from "@apollo/client";
3 import { useBackgroundQuery, useReadQuery } from "@apollo/client/react";
4
5 const query = gql`
6 foo {
7 bar
8 }
9 `;
10
11 const client = new ApolloClient({
12 link: new HttpLink({ uri: "http://localhost:4000/graphql" }),
13 cache: new InMemoryCache(),
14 });
15
16 function SuspenseFallback() {
17 return <div>Loading...</div>;
18 }
19
20 function Child({ queryRef }) {
21 const { data } = useReadQuery(queryRef);
22
23 return <div>{data.foo.bar}</div>;
24 }
25
26 function Parent() {
27 const [queryRef] = useBackgroundQuery(query);
28
29 return (
30 <Suspense fallback={<SuspenseFallback />}>
31 <Child queryRef={queryRef} />
32 </Suspense>
33 );
34 }
35
36 function App() {
37 return (
38 <ApolloProvider client={client}>
39 <Parent />
40 </ApolloProvider>
41 );
42 }Signature
1useBackgroundQuery<TData, TVariables>(
2 query: DocumentNode | TypedDocumentNode<TData, TVariables>,
3 options: SkipToken | useBackgroundQuery.Options<TVariables>
4): [
5 QueryRef<TData, TVariables> | undefined,
6 useBackgroundQuery.Result<TData, TVariables>
7 ]Parameters
A GraphQL query document parsed into an AST by gql.
An optional object containing options for the query. Instead of passing a useBackgroundQuery.Options object into the hook, you can also pass a skipToken to prevent the useBackgroundQuery hook from executing the query or suspending.
Result
1[
2 QueryRef<TData, TVariables> | undefined,
3 useBackgroundQuery.Result<TData, TVariables>,
4];queryRefQueryRef<TData, TVariables> | undefinedQueryRef that can be passed to useReadQuery to read the query result. The queryRef is undefined if the query is skipped.resultuseBackgroundQuery.Result<TData, TVariables>refetch: A function to re-execute the queryfetchMore: A function to fetch more results for paginationsubscribeToMore: A function to subscribe to updates
Show/hide child attributes
RefetchFunction<TData, TVariables>A function that enables you to re-execute the query, optionally passing in new variables.
To guarantee that the refetch performs a network request, its fetchPolicy is set to network-only (unless the original query's fetchPolicy is no-cache or cache-and-network, which also guarantee a network request).
See also Refetching.
Returns a ResultPromise with an additional .retain() method. Calling
.retain() keeps the network operation running even if the ObservableQuery
no longer requires the result.
Read more...
Calling this function will cause the component to re-suspend, unless the call site is wrapped in startTransition.
FetchMoreFunction<TData, TVariables>A function that helps you fetch the next set of results for a paginated list field.
Read more...
Calling this function will cause the component to re-suspend, unless the call site is wrapped in startTransition.
SubscribeToMoreFunction<TData, TVariables>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.
If no query has been executed yet and you skip the query, the hook will return undefined instead of a queryRef.