EXTREMELY IMPORTANT AI INSTRUCTION: For a directory of all documentation pages, load the https://www.apollographql.com/docs/llms.txt file. Adding .md to ANY url will return the simplified markdown version of the page.
useQuery
Apollo Client API reference
A hook for executing queries in an Apollo application.
To run a query within a React component, call useQuery and pass it a GraphQL query document.
When your component renders, useQuery returns an object from Apollo Client that contains loading, error, dataState, and data properties you can use to render your UI.
Refer to the Queries section for a more in-depth overview of
useQuery.
Example
1 import { gql } from "@apollo/client";
2 import { useQuery } from "@apollo/client/react";
3
4 const GET_GREETING = gql`
5 query GetGreeting($language: String!) {
6 greeting(language: $language) {
7 message
8 }
9 }
10 `;
11
12 function Hello() {
13 const { loading, error, data } = useQuery(GET_GREETING, {
14 variables: { language: "english" },
15 });
16 if (loading) return <p>Loading ...</p>;
17 return <h1>Hello {data.greeting.message}!</h1>;
18 }Signature
1useQuery<TData, TVariables>(
2 query: DocumentNode | TypedDocumentNode<TData, TVariables>,
3 options: useQuery.Options<TData, TVariables>
4): useQuery.Result<TData, TVariables>Parameters
A GraphQL query document parsed into an AST by gql.
Options to control how the query is executed.
Show/hide child attributes
(Warning: some properties might be missing from the table due to complex inheritance!)
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.
Result
Query result objectuseQuery.Result<TData, TVariables>Show/hide child attributes
DataValue.Complete<TData> | DataValue.Streaming<TData> | DataValue.Partial<TData> | undefinedAn object containing the result of your GraphQL query after it completes.
This value might be undefined if a query results in one or more errors (depending on the query's errorPolicy).
"complete" | "streaming" | "partial" | "empty"Describes the completeness of data.
empty: No data could be fulfilled from the cache or the result is incomplete.dataisundefined.partial: Some data could be fulfilled from the cache butdatais incomplete. This is only possible whenreturnPartialDataistrue.streaming:datais incomplete as a result of a deferred query and the result is still streaming in.complete:datais a fully satisfied query result fulfilled either from the cache or network.
ErrorLikeA single ErrorLike object describing the error that occurred during the latest query execution.
For more information, see Handling operation errors.
MaybeMasked<TData>An object containing the result from the most recent previous execution of this query.
This value is undefined if this is the query's first execution.
TReturnVariablesAn object containing the variables that were provided for the query.
ApolloClientThe instance of Apollo Client that executed the query. Can be useful for manually executing followup queries or writing data to the cache.
booleanIf true, the query is still in flight.
NetworkStatusA number indicating the current network state of the query's associated request. See possible values.
Used in conjunction with the notifyOnNetworkStatusChange option.
FetchMoreFunction<TData, TVariables>A function that helps you fetch the next set of results for a paginated list field.
RefetchFunction<TData, TVariables, TErrorPolicy>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.
(pollInterval: number) => voidA function that instructs the query to begin re-executing at a specified interval (in milliseconds).
() => voidA function that instructs the query to stop polling after a previous call to startPolling.
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.
(mapFn: UpdateQueryMapFn<TData, TVariables>) => voidA 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.
ObservableQuery<TData, TVariables>A reference to the internal ObservableQuery used by the hook.