Open History to see the last commit
1---
2id: QueryClient
3title: QueryClient
4---
5β
6## `QueryClient`
7β
8The `QueryClient` can be used to interact with a cache:
9β
10```tsx
11import { QueryClient } from '@tanstack/react-query'
12β
13const queryClient = new QueryClient({
14 defaultOptions: {
15 queries: {
16 staleTime: Infinity,
17 },
18 },
19})
20β
21await queryClient.prefetchQuery({ queryKey: ['posts'], queryFn: fetchPosts })
22```
23β
24Its available methods are:
25β
26- [`queryClient.fetchQuery`](#queryclientfetchquery)
27- [`queryClient.fetchInfiniteQuery`](#queryclientfetchinfinitequery)
28- [`queryClient.prefetchQuery`](#queryclientprefetchquery)
29- [`queryClient.prefetchInfiniteQuery`](#queryclientprefetchinfinitequery)
30- [`queryClient.getQueryData`](#queryclientgetquerydata)
31- [`queryClient.ensureQueryData`](#queryclientensurequerydata)
32- [`queryClient.getQueriesData`](#queryclientgetqueriesdata)
33- [`queryClient.setQueryData`](#queryclientsetquerydata)
34- [`queryClient.getQueryState`](#queryclientgetquerystate)
35- [`queryClient.setQueriesData`](#queryclientsetqueriesdata)
36- [`queryClient.invalidateQueries`](#queryclientinvalidatequeries)
37- [`queryClient.refetchQueries`](#queryclientrefetchqueries)
38- [`queryClient.cancelQueries`](#queryclientcancelqueries)
39- [`queryClient.removeQueries`](#queryclientremovequeries)
40- [`queryClient.resetQueries`](#queryclientresetqueries)
41- [`queryClient.isFetching`](#queryclientisfetching)
42- [`queryClient.isMutating`](#queryclientismutating)
43- [`queryClient.getDefaultOptions`](#queryclientgetdefaultoptions)
44- [`queryClient.setDefaultOptions`](#queryclientsetdefaultoptions)
45- [`queryClient.getQueryDefaults`](#queryclientgetquerydefaults)
46- [`queryClient.setQueryDefaults`](#queryclientsetquerydefaults)
47- [`queryClient.getMutationDefaults`](#queryclientgetmutationdefaults)
48- [`queryClient.setMutationDefaults`](#queryclientsetmutationdefaults)
49- [`queryClient.getQueryCache`](#queryclientgetquerycache)
50- [`queryClient.getMutationCache`](#queryclientgetmutationcache)
51- [`queryClient.clear`](#queryclientclear)
52- [`queryClient.resumePausedMutations`](#queryclientresumepausedmutations)
53β
54**Options**
55β
56- `queryCache?: QueryCache`
57 - Optional
58 - The query cache this client is connected to.
59- `mutationCache?: MutationCache`
60 - Optional
61 - The mutation cache this client is connected to.
62- `defaultOptions?: DefaultOptions`
63 - Optional
64 - Define defaults for all queries and mutations using this queryClient.
65β
66## `queryClient.fetchQuery`
67β
68`fetchQuery` is an asynchronous method that can be used to fetch and cache a query. It will either resolve with the data or throw with the error. Use the `prefetchQuery` method if you just want to fetch a query without needing the result.
69β
70If the query exists and the data is not invalidated or older than the given `staleTime`, then the data from the cache will be returned. Otherwise it will try to fetch the latest data.
71β
72> The difference between using `fetchQuery` and `setQueryData` is that `fetchQuery` is async and will ensure that duplicate requests for this query are not created with `useQuery` instances for the same query are rendered while the data is fetching.
73β
74```tsx
75try {
76 const data = await queryClient.fetchQuery({ queryKey, queryFn })
77} catch (error) {
78 console.log(error)
79}
80```
81β
82Specify a `staleTime` to only fetch when the data is older than a certain amount of time:
83β
84```tsx
85try {
86 const data = await queryClient.fetchQuery({
87 queryKey,
88 queryFn,
89 staleTime: 10000,
90 })
91} catch (error) {
92 console.log(error)
93}
94```
95β
96**Options**
97β
98The options for `fetchQuery` are exactly the same as those of [`useQuery`](./framework/react/reference/useQuery), except the following: `enabled, refetchInterval, refetchIntervalInBackground, refetchOnWindowFocus, refetchOnReconnect, refetchOnMount, notifyOnChangeProps, throwOnError, select, suspense, placeholderData`; which are strictly for useQuery and useInfiniteQuery. You can check the [source code](https://github.com/TanStack/query/blob/7cd2d192e6da3df0b08e334ea1cf04cd70478827/packages/query-core/src/types.ts#L119) for more clarity.
99β
100**Returns**
101β
102- `Promise<TData>`
103β
104## `queryClient.fetchInfiniteQuery`
105β
106`fetchInfiniteQuery` is similar to `fetchQuery` but can be used to fetch and cache an infinite query.
107β
108```tsx
109try {
110 const data = await queryClient.fetchInfiniteQuery({ queryKey, queryFn })
111 console.log(data.pages)
112} catch (error) {
113 console.log(error)
114}
115```
116β
117**Options**
118β
119The options for `fetchInfiniteQuery` are exactly the same as those of [`fetchQuery`](#queryclientfetchquery).
120β
121**Returns**
122β
123- `Promise<InfiniteData<TData, TPageParam>>`
124β
125## `queryClient.prefetchQuery`
126β
127`prefetchQuery` is an asynchronous method that can be used to prefetch a query before it is needed or rendered with `useQuery` and friends. The method works the same as `fetchQuery` except that it will not throw or return any data.
128β
129```tsx
130await queryClient.prefetchQuery({ queryKey, queryFn })
131```
132β
133You can even use it with a default queryFn in your config!
134β
135```tsx
136await queryClient.prefetchQuery({ queryKey })
137```
138β
139**Options**
140β
141The options for `prefetchQuery` are exactly the same as those of [`fetchQuery`](#queryclientfetchquery).
142β
143**Returns**
144β
145- `Promise<void>`
146 - A promise is returned that will either immediately resolve if no fetch is needed or after the query has been executed. It will not return any data or throw any errors.
147β
148## `queryClient.prefetchInfiniteQuery`
149β
150`prefetchInfiniteQuery` is similar to `prefetchQuery` but can be used to prefetch and cache an infinite query.
151β
152```tsx
153await queryClient.prefetchInfiniteQuery({ queryKey, queryFn })
154```
155β
156**Options**
157β
158The options for `prefetchInfiniteQuery` are exactly the same as those of [`fetchQuery`](#queryclientfetchquery).
159β
160**Returns**
161β
162- `Promise<void>`
163 - A promise is returned that will either immediately resolve if no fetch is needed or after the query has been executed. It will not return any data or throw any errors.
164β
165## `queryClient.getQueryData`
166β
167`getQueryData` is a synchronous function that can be used to get an existing query's cached data. If the query does not exist, `undefined` will be returned.
168β
169```tsx
170const data = queryClient.getQueryData(queryKey)
171```
172β
173**Options**
174β
175- `queryKey: QueryKey`: [Query Keys](./framework/react/guides/query-keys)
176β
177**Returns**
178β
179- `data: TQueryFnData | undefined`
180 - The data for the cached query, or `undefined` if the query does not exist.
181β
182## `queryClient.ensureQueryData`
183β
184`ensureQueryData` is an asynchronous function that can be used to get an existing query's cached data. If the query does not exist, `queryClient.fetchQuery` will be called and its results returned.
185β
186```tsx
187const data = await queryClient.ensureQueryData({ queryKey, queryFn })
188```
189β
190**Options**
191β
192- The options for `ensureQueryData` are exactly the same as those of [`fetchQuery`](#queryclientfetchquery) except that `queryKey` is required.
193β
194**Returns**
195β
196- `Promise<TData>`
197β
198## `queryClient.getQueriesData`
199β
200`getQueriesData` is a synchronous function that can be used to get the cached data of multiple queries. Only queries that match the passed queryKey or queryFilter will be returned. If there are no matching queries, an empty array will be returned.
201β
202```tsx
203const data = queryClient.getQueriesData(filters)
204```
205β
206**Options**
207β
208- `filters: QueryFilters`: [Query Filters](./framework/react/guides/filters#query-filters)
209 - if a filter is passed, the data with queryKeys matching the filter will be returned
210β
211**Returns**
212β
213- `[queryKey: QueryKey, data: TQueryFnData | undefined][]`
214 - An array of tuples for the matched query keys, or `[]` if there are no matches. The tuples are the query key and its associated data.
215β
216**Caveats**
217β
218Because the returned data in each tuple can be of varying structures (i.e. using a filter to return "active" queries can return different data types), the `TData` generic defaults to `unknown`. If you provide a more specific type to `TData` it is assumed that you are certain each tuple's data entry is all the same type.
219β
220This distinction is more a "convenience" for ts devs that know which structure will be returned.
221β
222## `queryClient.setQueryData`
223β
224`setQueryData` is a synchronous function that can be used to immediately update a query's cached data. If the query does not exist, it will be created. **If the query is not utilized by a query hook in the default `gcTime` of 5 minutes, the query will be garbage collected**. To update multiple queries at once and match query keys partially, you need to use [`queryClient.setQueriesData`](#queryclientsetqueriesdata) instead.
225β
226> The difference between using `setQueryData` and `fetchQuery` is that `setQueryData` is sync and assumes that you already synchronously have the data available. If you need to fetch the data asynchronously, it's suggested that you either refetch the query key or use `fetchQuery` to handle the asynchronous fetch.
227β
228```tsx
229queryClient.setQueryData(queryKey, updater)
230```
231β
232**Options**
233β
234- `queryKey: QueryKey`: [Query Keys](./framework/react/guides/query-keys)
235- `updater: TQueryFnData | undefined | ((oldData: TQueryFnData | undefined) => TQueryFnData | undefined)`
236 - If non-function is passed, the data will be updated to this value
237 - If a function is passed, it will receive the old data value and be expected to return a new one.
238β
239**Using an updater value**
240β
241```tsx
242setQueryData(queryKey, newData)
243```
244β
245If the value is `undefined`, the query data is not updated.
246β
247**Using an updater function**
248β
249For convenience in syntax, you can also pass an updater function which receives the current data value and returns the new one:
250β
251```tsx
252setQueryData(queryKey, (oldData) => newData)
253```
254β
255If the updater function returns `undefined`, the query data will not be updated. If the updater function receives `undefined` as input, you can return `undefined` to bail out of the update and thus _not_ create a new cache entry.
256β
257**Immutability**
258β
259Updates via `setQueryData` must be performed in an _immutable_ way. **DO NOT** attempt to write directly to the cache by mutating `oldData` or data that you retrieved via `getQueryData` in place.
260β
261## `queryClient.getQueryState`
262β
263`getQueryState` is a synchronous function that can be used to get an existing query's state. If the query does not exist, `undefined` will be returned.
264β
265```tsx
266const state = queryClient.getQueryState(queryKey)
267console.log(state.dataUpdatedAt)
268```
269β
270**Options**
271β
272- `queryKey: QueryKey`: [Query Keys](./framework/react/guides/query-keys)
273β
274## `queryClient.setQueriesData`
275β
276`setQueriesData` is a synchronous function that can be used to immediately update cached data of multiple queries by using filter function or partially matching the query key. Only queries that match the passed queryKey or queryFilter will be updated - no new cache entries will be created. Under the hood, [`setQueryData`](#queryclientsetquerydata) is called for each existing query.
277β
278```tsx
279queryClient.setQueriesData(filters, updater)
280```
281β
282**Options**
283β
284- `filters: QueryFilters`: [Query Filters](./framework/react/guides/filters#query-filters)
285 - if a filter is passed, queryKeys matching the filter will be updated
286- `updater: TQueryFnData | (oldData: TQueryFnData | undefined) => TQueryFnData`
287 - the [setQueryData](#queryclientsetquerydata) updater function or new data, will be called for each matching queryKey
288β
289## `queryClient.invalidateQueries`
290β
291The `invalidateQueries` method can be used to invalidate and refetch single or multiple queries in the cache based on their query keys or any other functionally accessible property/state of the query. By default, all matching queries are immediately marked as invalid and active queries are refetched in the background.
292β
293- If you **do not want active queries to refetch**, and simply be marked as invalid, you can use the `refetchType: 'none'` option.
294- If you **want inactive queries to refetch** as well, use the `refetchType: 'all'` option
295β
296```tsx
297await queryClient.invalidateQueries(
298 {
299 queryKey: ['posts'],
300 exact,
301 refetchType: 'active',
302 },
303 { throwOnError, cancelRefetch },
304)
305```
306β
307**Options**
308β
309- `filters?: QueryFilters`: [Query Filters](./framework/react/guides/filters#query-filters)
310 - `queryKey?: QueryKey`: [Query Keys](./framework/react/guides/query-keys)
311 - `refetchType?: 'active' | 'inactive' | 'all' | 'none'`
312 - Defaults to `'active'`
313 - When set to `active`, only queries that match the refetch predicate and are actively being rendered via `useQuery` and friends will be refetched in the background.
314 - When set to `inactive`, only queries that match the refetch predicate and are NOT actively being rendered via `useQuery` and friends will be refetched in the background.
315 - When set to `all`, all queries that match the refetch predicate will be refetched in the background.
316 - When set to `none`, no queries will be refetched, and those that match the refetch predicate will be marked as invalid only.
317- `options?: InvalidateOptions`:
318 - `throwOnError?: boolean`
319 - When set to `true`, this method will throw if any of the query refetch tasks fail.
320 - `cancelRefetch?: boolean`
321 - Defaults to `true`
322 - Per default, a currently running request will be cancelled before a new request is made
323 - When set to `false`, no refetch will be made if there is already a request running.
324β
325## `queryClient.refetchQueries`
326β
327The `refetchQueries` method can be used to refetch queries based on certain conditions.
328β
329Examples:
330β
331```tsx
332// refetch all queries:
333await queryClient.refetchQueries()
334β
335// refetch all stale queries:
336await queryClient.refetchQueries({ stale: true })
337β
338// refetch all active queries partially matching a query key:
339await queryClient.refetchQueries({ queryKey: ['posts'], type: 'active' })
340β
341// refetch all active queries exactly matching a query key:
342await queryClient.refetchQueries({
343 queryKey: ['posts', 1],
344 type: 'active',
345 exact: true,
346})
347```
348β
349**Options**
350β
351- `filters?: QueryFilters`: [Query Filters](./framework/react/guides/filters#query-filters)
352- `options?: RefetchOptions`:
353 - `throwOnError?: boolean`
354 - When set to `true`, this method will throw if any of the query refetch tasks fail.
355 - `cancelRefetch?: boolean`
356 - Defaults to `true`
357 - Per default, a currently running request will be cancelled before a new request is made
358 - When set to `false`, no refetch will be made if there is already a request running.
359β
360**Returns**
361β
362This function returns a promise that will resolve when all of the queries are done being refetched. By default, it **will not** throw an error if any of those queries refetches fail, but this can be configured by setting the `throwOnError` option to `true`
363β
364## `queryClient.cancelQueries`
365β
366The `cancelQueries` method can be used to cancel outgoing queries based on their query keys or any other functionally accessible property/state of the query.
367β
368This is most useful when performing optimistic updates since you will likely need to cancel any outgoing query refetches so they don't clobber your optimistic update when they resolve.
369β
370```tsx
371await queryClient.cancelQueries({ queryKey: ['posts'], exact: true })
372```
373β
374**Options**
375β
376- `filters?: QueryFilters`: [Query Filters](./framework/react/guides/filters#query-filters)
377β
378**Returns**
379β
380This method does not return anything
381β
382## `queryClient.removeQueries`
383β
384The `removeQueries` method can be used to remove queries from the cache based on their query keys or any other functionally accessible property/state of the query.
385β
386```tsx
387queryClient.removeQueries({ queryKey, exact: true })
388```
389β
390**Options**
391β
392- `filters?: QueryFilters`: [Query Filters](./framework/react/guides/filters#query-filters)
393β
394**Returns**
395β
396This method does not return anything
397β
398## `queryClient.resetQueries`
399β
400The `resetQueries` method can be used to reset queries in the cache to their
401initial state based on their query keys or any other functionally accessible
402property/state of the query.
403β
404This will notify subscribers — unlike `clear`, which removes all
405subscribers — and reset the query to its pre-loaded state — unlike
406`invalidateQueries`. If a query has `initialData`, the query's data will be
407reset to that. If a query is active, it will be refetched.
408β
409```tsx
410queryClient.resetQueries({ queryKey, exact: true })
411```
412β
413**Options**
414β
415- `filters?: QueryFilters`: [Query Filters](./framework/react/guides/filters#query-filters)
416- `options?: ResetOptions`:
417 - `throwOnError?: boolean`
418 - When set to `true`, this method will throw if any of the query refetch tasks fail.
419 - `cancelRefetch?: boolean`
420 - Defaults to `true`
421 - Per default, a currently running request will be cancelled before a new request is made
422 - When set to `false`, no refetch will be made if there is already a request running.
423β
424**Returns**
425β
426This method returns a promise that resolves when all active queries have been refetched.
427β
428## `queryClient.isFetching`
429β
430This `isFetching` method returns an `integer` representing how many queries, if any, in the cache are currently fetching (including background-fetching, loading new pages, or loading more infinite query results)
431β
432```tsx
433if (queryClient.isFetching()) {
434 console.log('At least one query is fetching!')
435}
436```
437β
438TanStack Query also exports a handy [`useIsFetching`](./framework/react/reference/useIsFetching) hook that will let you subscribe to this state in your components without creating a manual subscription to the query cache.
439β
440**Options**
441β
442- `filters?: QueryFilters`: [Query Filters](./framework/react/guides/filters#query-filters)
443β
444**Returns**
445β
446This method returns the number of fetching queries.
447β
448## `queryClient.isMutating`
449β
450This `isMutating` method returns an `integer` representing how many mutations, if any, in the cache are currently fetching.
451β
452```tsx
453if (queryClient.isMutating()) {
454 console.log('At least one mutation is fetching!')
455}
456```
457β
458TanStack Query also exports a handy [`useIsMutating`](./framework/react/reference/useIsMutating) hook that will let you subscribe to this state in your components without creating a manual subscription to the mutation cache.
459β
460**Options**
461β
462- `filters: MutationFilters`: [Mutation Filters](./framework/react/guides/filters#mutation-filters)
463β
464**Returns**
465β
466This method returns the number of fetching mutations.
467β
468## `queryClient.getDefaultOptions`
469β
470The `getDefaultOptions` method returns the default options which have been set when creating the client or with `setDefaultOptions`.
471β
472```tsx
473const defaultOptions = queryClient.getDefaultOptions()
474```
475β
476## `queryClient.setDefaultOptions`
477β
478The `setDefaultOptions` method can be used to dynamically set the default options for this queryClient. Previously defined default options will be overwritten.
479β
480```tsx
481queryClient.setDefaultOptions({
482 queries: {
483 staleTime: Infinity,
484 },
485})
486```
487β
488## `queryClient.getQueryDefaults`
489β
490The `getQueryDefaults` method returns the default options which have been set for specific queries:
491β
492```tsx
493const defaultOptions = queryClient.getQueryDefaults(['posts'])
494```
495β
496> Note that if several query defaults match the given query key, the **first** matching one is returned.
497> This could lead to unexpected behaviours. See [`setQueryDefaults`](#queryclientsetquerydefaults).
498β
499## `queryClient.setQueryDefaults`
500β
501`setQueryDefaults` can be used to set default options for specific queries:
502β
503```tsx
504queryClient.setQueryDefaults(['posts'], { queryFn: fetchPosts })
505β
506function Component() {
507 const { data } = useQuery({ queryKey: ['posts'] })
508}
509```
510β
511**Options**
512β
513- `queryKey: QueryKey`: [Query Keys](./framework/react/guides/query-keys)
514- `options: QueryOptions`
515β
516> As stated in [`getQueryDefaults`](#queryclientgetquerydefaults), the order of registration of query defaults does matter.
517> Since the **first** matching defaults are returned by `getQueryDefaults`, the registration should be made in the following order: from the **least generic key** to the **most generic one**. This way, in case of specific key, the first matching one would be the expected one.
518β
519## `queryClient.getMutationDefaults`
520β
521The `getMutationDefaults` method returns the default options which have been set for specific mutations:
522β
523```tsx
524const defaultOptions = queryClient.getMutationDefaults(['addPost'])
525```
526β
527## `queryClient.setMutationDefaults`
528β
529`setMutationDefaults` can be used to set default options for specific mutations:
530β
531```tsx
532queryClient.setMutationDefaults(['addPost'], { mutationFn: addPost })
533β
534function Component() {
535 const { data } = useMutation({ mutationKey: ['addPost'] })
536}
537```
538β
539**Options**
540β
541- `mutationKey: unknown[]`
542- `options: MutationOptions`
543β
544> Similar to [`setQueryDefaults`](#queryclientsetquerydefaults), the order of registration does matter here.
545β
546## `queryClient.getQueryCache`
547β
548The `getQueryCache` method returns the query cache this client is connected to.
549β
550```tsx
551const queryCache = queryClient.getQueryCache()
552```
553β
554## `queryClient.getMutationCache`
555β
556The `getMutationCache` method returns the mutation cache this client is connected to.
557β
558```tsx
559const mutationCache = queryClient.getMutationCache()
560```
561β
562## `queryClient.clear`
563β
564The `clear` method clears all connected caches.
565β
566```tsx
567queryClient.clear()
568```
569β
570## `queryClient.resumePausedMutations`
571β
572Can be used to resume mutations that have been paused because there was no network connection.
573β
574```tsx
575queryClient.resumePausedMutations()
576```