QueryClient.getMutationDefaults method
getMutationDefaults returns the default options which have been set for specific mutations. Takes a mutationKey parameter.
TanStack Query · Reference · all subjects
queryclient
34 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
QueryClient constructor and defaultOptions
The QueryClient constructor accepts an object with the following optional properties: queryCache (QueryCache), mutationCache (MutationCache), and defaultOptions (DefaultOptions). The defaultOptions parameter defines defaults for all queries and mutations using this queryClient and can also define defaults for hydration. Example: new QueryClient({ defaultOptions: { queries: { staleTime: Infinity } } })
QueryClient.fetchQuery method
fetchQuery is an asynchronous method that fetches and caches a query, resolving with the data or throwing with the error. If the query exists and the data is not invalidated or older than the given staleTime, it returns cached data. Otherwise it fetches the latest data. Options are the same as useQuery except: enabled, refetchInterval, refetchIntervalInBackground, refetchOnWindowFocus, refetchOnReconnect, refetchOnMount, notifyOnChangeProps, throwOnError, select, suspense, and placeholderData. Returns Promise<TData>.
QueryClient.fetchInfiniteQuery method
fetchInfiniteQuery is similar to fetchQuery but is used to fetch and cache an infinite query. It has the same options as fetchQuery. Returns Promise<InfiniteData<TData, TPageParam>>.
QueryClient.prefetchQuery method
prefetchQuery is an asynchronous method that prefetches a query before it is needed or rendered with useQuery. It works the same as fetchQuery except it will not throw or return any data. Returns Promise<void> that will either immediately resolve if no fetch is needed or after the query has been executed.
QueryClient.prefetchInfiniteQuery method
prefetchInfiniteQuery is similar to prefetchQuery but is used to prefetch and cache an infinite query. It has the same options as fetchQuery. Returns Promise<void>.
QueryClient.getQueryData method
getQueryData is a synchronous function that gets an existing query's cached data. Takes a queryKey parameter (Query Keys). If the query does not exist, returns undefined. Returns data (TQueryFnData | undefined).
QueryClient.ensureInfiniteQueryData method
ensureInfiniteQueryData is an asynchronous function that gets an existing infinite query's cached data. If the query does not exist, queryClient.fetchInfiniteQuery is called and its results are returned. Options include all fetchInfiniteQuery options plus revalidateIfStale (boolean, optional, defaults to false). If revalidateIfStale is true, stale data will be refetched in the background but cached data is returned immediately. Returns Promise<InfiniteData<TData, TPageParam>>.
QueryClient.getQueriesData method
getQueriesData is a synchronous function that gets the cached data of multiple queries. Only queries matching the passed queryKey or queryFilter are returned. Takes filters parameter (QueryFilters). If there are no matching queries, returns an empty array. Returns [queryKey: QueryKey, data: TQueryFnData | undefined][] - an array of tuples for matched query keys with their associated data.
QueryClient.setQueryData method
setQueryData is a synchronous function that immediately updates a query's cached data. If the query does not exist, it is created. If the query is not utilized by a query hook within the default gcTime, it will be garbage collected (defaults to 5 minutes if not configured). Takes queryKey (Query Keys) and updater (TQueryFnData | undefined | ((oldData: TQueryFnData | undefined) => TQueryFnData | undefined)). If a non-function is passed, data is updated to that value. If a function is passed, it receives old data and returns new data. Updates must be performed immutably - do not mutate oldData directly.
QueryClient.getQueryState method
getQueryState is a synchronous function that gets an existing query's state. Takes a queryKey parameter (Query Keys). If the query does not exist, returns undefined. The returned state object contains properties like dataUpdatedAt.
QueryClient.setQueriesData method
setQueriesData is a synchronous function that immediately updates cached data of multiple queries using a filter function or partially matching the query key. Only queries matching the passed queryKey or queryFilter are updated - no new cache entries are created. Takes filters (QueryFilters) and updater (TQueryFnData | (oldData: TQueryFnData | undefined) => TQueryFnData). Internally calls setQueryData for each existing query.
QueryClient.invalidateQueries method
invalidateQueries invalidates and refetches single or multiple queries in the cache based on their query keys or other accessible properties. By default, all matching queries are immediately marked as invalid and active queries are refetched in the background. Takes filters (QueryFilters with queryKey and refetchType options) and options (InvalidateOptions). refetchType options: 'active' (default, only active queries refetch), 'inactive' (only inactive queries refetch), 'all' (all matching queries refetch), 'none' (no refetch, only mark invalid). InvalidateOptions: throwOnError (boolean), cancelRefetch (boolean, defaults to true - cancels running requests before new requests).
QueryClient.refetchQueries method
refetchQueries refetches queries based on certain conditions. Takes filters (QueryFilters) and options (RefetchOptions). RefetchOptions: throwOnError (boolean, when true throws if any refetch fails), cancelRefetch (boolean, defaults to true - cancels running requests before new requests). Returns a promise that resolves when all queries are done refetching. By default, does not throw if any query refetch fails unless throwOnError is true. Queries that are disabled or static will never be refetched.
QueryClient.cancelQueries method
cancelQueries cancels outgoing queries based on their query keys or other accessible properties. Most useful for optimistic updates to cancel outgoing query refetches so they don't overwrite the optimistic update. Takes filters (QueryFilters) and cancelOptions (Cancel Options). Does not return anything.
QueryClient.removeQueries method
removeQueries removes queries from the cache based on their query keys or other accessible properties. Takes filters (QueryFilters). Does not return anything. Unlike invalidateQueries or refetchQueries, removeQueries removes matching queries from the cache instead of refetching them.
QueryClient.resetQueries method
resetQueries resets queries in the cache to their initial state based on their query keys or other accessible properties. Notifies subscribers (unlike clear which removes all subscribers) and resets the query to its pre-loaded state (unlike invalidateQueries). If a query has initialData, the query's data is reset to that. If a query is active, it will be refetched. Takes filters (QueryFilters) and options (ResetOptions). ResetOptions: throwOnError (boolean), cancelRefetch (boolean, defaults to true). Returns a promise that resolves when all active queries have been refetched.
QueryClient.isFetching method
isFetching returns an integer representing how many queries in the cache are currently fetching (including background-fetching, loading new pages, or loading more infinite query results). Takes optional filters parameter (QueryFilters). Returns the number of fetching queries.
QueryClient.isMutating method
isMutating returns an integer representing how many mutations in the cache are currently fetching. Takes filters parameter (MutationFilters). Returns the number of fetching mutations.
QueryClient.getDefaultOptions method
getDefaultOptions returns the default options which have been set when creating the client or with setDefaultOptions.
QueryClient.setDefaultOptions method
setDefaultOptions dynamically sets the default options for the queryClient. Previously defined default options are overwritten. Accepts an object with queries and mutations default options.
QueryClient.getQueryDefaults method
getQueryDefaults returns the default options which have been set for specific queries. If several query defaults match the given query key, they are merged together based on the order of registration.
QueryClient.setQueryDefaults method
setQueryDefaults sets default options for specific queries. Takes queryKey (Query Keys) and options (QueryOptions). The order of registration matters - registration should be from the most generic key to the least generic one so more specific defaults will override more generic defaults.
QueryClient.setMutationDefaults method
setMutationDefaults sets default options for specific mutations. Takes mutationKey (unknown[]) and options (MutationOptions). The order of registration matters - more specific defaults override more generic defaults.
QueryClient.getQueryCache method
getQueryCache returns the query cache this client is connected to.
QueryClient.getMutationCache method
getMutationCache returns the mutation cache this client is connected to.
QueryClient.clear method
clear clears all connected caches.
QueryClient.resumePausedMutations method
resumePausedMutations resumes mutations that have been paused because there was no network connection.
streamedQuery helper function overview
streamedQuery is a helper function to create a query function that streams data from an AsyncIterable. Data will be an Array of all the chunks received. The query will be in a pending state until the first chunk of data is received, but will go to success after that. The query will stay in fetchStatus fetching until the stream ends. streamedQuery is currently marked as experimental.
streamedQuery import
streamedQuery is imported from @tanstack/react-query as experimental_streamedQuery. The function is used within queryOptions to define a queryFn.
streamedQuery options: streamFn
streamFn is a required option for streamedQuery. It has type (context: QueryFunctionContext) => Promise<AsyncIterable<TData>>. The function returns a Promise of an AsyncIterable with data to stream in and receives a QueryFunctionContext.
streamedQuery options: refetchMode
refetchMode is an optional option for streamedQuery with type 'append' | 'reset' | 'replace'. It defines how refetches are handled and defaults to 'reset'. When set to 'reset', the query will erase all data and go back into pending state. When set to 'append', data will be appended to existing data. When set to 'replace', all data will be written to the cache once the stream ends.
streamedQuery options: reducer
reducer is an optional option for streamedQuery with type (accumulator: TData, chunk: TQueryFnData) => TData. It reduces streamed chunks (TQueryFnData) into the final data shape (TData). Default behavior appends each chunk to the end of the accumulator when TData is an array. If TData is not an array, a custom reducer must be provided.
streamedQuery options: initialValue
initialValue is an optional option for streamedQuery with type TData = TQueryFnData. It defines the initial data to be used while the first chunk is being fetched, and it is also returned when the stream yields no values. It is mandatory when a custom reducer is provided. Defaults to an empty array.