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.ensureInfiniteQueryData`](#queryclientensureinfinitequerydata)
33- [`queryClient.getQueriesData`](#queryclientgetqueriesdata)
34- [`queryClient.setQueryData`](#queryclientsetquerydata)
35- [`queryClient.getQueryState`](#queryclientgetquerystate)
36- [`queryClient.setQueriesData`](#queryclientsetqueriesdata)
37- [`queryClient.invalidateQueries`](#queryclientinvalidatequeries)
38- [`queryClient.refetchQueries`](#queryclientrefetchqueries)
39- [`queryClient.cancelQueries`](#queryclientcancelqueries)
40- [`queryClient.removeQueries`](#queryclientremovequeries)
41- [`queryClient.resetQueries`](#queryclientresetqueries)
42- [`queryClient.isFetching`](#queryclientisfetching)
43- [`queryClient.isMutating`](#queryclientismutating)
44- [`queryClient.getDefaultOptions`](#queryclientgetdefaultoptions)
45- [`queryClient.setDefaultOptions`](#queryclientsetdefaultoptions)
46- [`queryClient.getQueryDefaults`](#queryclientgetquerydefaults)
47- [`queryClient.setQueryDefaults`](#queryclientsetquerydefaults)
48- [`queryClient.getMutationDefaults`](#queryclientgetmutationdefaults)
49- [`queryClient.setMutationDefaults`](#queryclientsetmutationdefaults)
50- [`queryClient.getQueryCache`](#queryclientgetquerycache)
51- [`queryClient.getMutationCache`](#queryclientgetmutationcache)
52- [`queryClient.clear`](#queryclientclear)
53- [`queryClient.resumePausedMutations`](#queryclientresumepausedmutations)
54β
55**Options**
56β
57- `queryCache?: QueryCache`
58 - Optional
59 - The query cache this client is connected to.
60- `mutationCache?: MutationCache`
61 - Optional
62 - The mutation cache this client is connected to.
63- `defaultOptions?: DefaultOptions`
64 - Optional
65 - Define defaults for all queries and mutations using this queryClient.
66 - You can also define defaults to be used for [hydration](../framework/react/reference/hydration.md)
67β
68## `queryClient.fetchQuery`
69β
70`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.
71β
72If 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.
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.md), 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.md)
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 same options as [`fetchQuery`](#queryclientfetchquery)
193- `revalidateIfStale: boolean`
194 - Optional
195 - Defaults to `false`
196 - If set to `true`, stale data will be refetched in the background, but cached data will be returned immediately.
197β
198**Returns**
199β
200- `Promise<TData>`
201β
202## `queryClient.ensureInfiniteQueryData`
203β
204`ensureInfiniteQueryData` is an asynchronous function that can be used to get an existing infinite query's cached data. If the query does not exist, `queryClient.fetchInfiniteQuery` will be called and its results returned.
205β
206```tsx
207const data = await queryClient.ensureInfiniteQueryData({
208 queryKey,
209 queryFn,
210 initialPageParam,
211 getNextPageParam,
212})
213```
214β
215**Options**
216β
217- the same options as [`fetchInfiniteQuery`](#queryclientfetchinfinitequery)
218- `revalidateIfStale: boolean`
219 - Optional
220 - Defaults to `false`
221 - If set to `true`, stale data will be refetched in the background, but cached data will be returned immediately.
222β
223**Returns**
224β
225- `Promise<InfiniteData<TData, TPageParam>>`
226β
227## `queryClient.getQueriesData`
228β
229`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.
230β
231```tsx
232const data = queryClient.getQueriesData(filters)
233```
234β
235**Options**
236β
237- `filters: QueryFilters`: [Query Filters](../framework/react/guides/filters.md#query-filters)
238 - if a filter is passed, the data with queryKeys matching the filter will be returned
239β
240**Returns**
241β
242- `[queryKey: QueryKey, data: TQueryFnData | undefined][]`
243 - 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.
244β
245**Caveats**
246β
247Because 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.
248β
249This distinction is more a "convenience" for ts devs that know which structure will be returned.
250β
251## `queryClient.setQueryData`
252β
253`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 within the default `gcTime`, the query will be garbage collected. If the default `gcTime` has not been configured, it defaults to 5 minutes.** To update multiple queries at once and match query keys partially, you need to use [`queryClient.setQueriesData`](#queryclientsetqueriesdata) instead.
254β
255> 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.
256β
257```tsx
258queryClient.setQueryData(queryKey, updater)
259```
260β
261**Options**
262β
263- `queryKey: QueryKey`: [Query Keys](../framework/react/guides/query-keys.md)
264- `updater: TQueryFnData | undefined | ((oldData: TQueryFnData | undefined) => TQueryFnData | undefined)`
265 - If non-function is passed, the data will be updated to this value
266 - If a function is passed, it will receive the old data value and be expected to return a new one.
267β
268**Using an updater value**
269β
270```tsx
271setQueryData(queryKey, newData)
272```
273β
274If the value is `undefined`, the query data is not updated.
275β
276**Using an updater function**
277β
278For convenience in syntax, you can also pass an updater function which receives the current data value and returns the new one:
279β
280```tsx
281setQueryData(queryKey, (oldData) => newData)
282```
283β
284If 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.
285β
286**Immutability**
287β
288Updates 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.
289β
290## `queryClient.getQueryState`
291β
292`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.
293β
294```tsx
295const state = queryClient.getQueryState(queryKey)
296console.log(state.dataUpdatedAt)
297```
298β
299**Options**
300β
301- `queryKey: QueryKey`: [Query Keys](../framework/react/guides/query-keys.md)
302β
303## `queryClient.setQueriesData`
304β
305`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.
306β
307```tsx
308queryClient.setQueriesData(filters, updater)
309```
310β
311**Options**
312β
313- `filters: QueryFilters`: [Query Filters](../framework/react/guides/filters.md#query-filters)
314 - if a filter is passed, queryKeys matching the filter will be updated
315- `updater: TQueryFnData | (oldData: TQueryFnData | undefined) => TQueryFnData`
316 - the [setQueryData](#queryclientsetquerydata) updater function or new data, will be called for each matching queryKey
317β
318## `queryClient.invalidateQueries`
319β
320The `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.
321β
322- If you **do not want active queries to refetch**, and simply be marked as invalid, you can use the `refetchType: 'none'` option.
323- If you **want inactive queries to refetch** as well, use the `refetchType: 'all'` option
324- For refetching, [queryClient.refetchQueries](#queryclientrefetchqueries) is called.
325β
326```tsx
327await queryClient.invalidateQueries(
328 {
329 queryKey: ['posts'],
330 exact,
331 refetchType: 'active',
332 },
333 { throwOnError, cancelRefetch },
334)
335```
336β
337**Options**
338β
339- `filters?: QueryFilters`: [Query Filters](../framework/react/guides/filters.md#query-filters)
340 - `queryKey?: QueryKey`: [Query Keys](../framework/react/guides/query-keys.md)
341 - `refetchType?: 'active' | 'inactive' | 'all' | 'none'`
342 - Defaults to `'active'`
343 - 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.
344 - 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.
345 - When set to `all`, all queries that match the refetch predicate will be refetched in the background.
346 - When set to `none`, no queries will be refetched, and those that match the refetch predicate will be marked as invalid only.
347- `options?: InvalidateOptions`:
348 - `throwOnError?: boolean`
349 - When set to `true`, this method will throw if any of the query refetch tasks fail.
350 - `cancelRefetch?: boolean`
351 - Defaults to `true`
352 - Per default, a currently running request will be cancelled before a new request is made
353 - When set to `false`, no refetch will be made if there is already a request running.
354β
355**Notes**
356β
357- Unlike [`refetchQueries`](#queryclientrefetchqueries), `invalidateQueries` marks matching queries as invalidated and then refetches `active` queries (unless otherwise specified with the `refetchType` option).
358- Unlike [`removeQueries`](#queryclientremovequeries), `invalidateQueries` keeps matching queries in the cache.
359β
360## `queryClient.refetchQueries`
361β
362The `refetchQueries` method can be used to refetch queries based on certain conditions.
363β
364Examples:
365β
366```tsx
367// refetch all queries:
368await queryClient.refetchQueries()
369β
370// refetch all stale queries:
371await queryClient.refetchQueries({ stale: true })
372β
373// refetch all active queries partially matching a query key:
374await queryClient.refetchQueries({ queryKey: ['posts'], type: 'active' })
375β
376// refetch all active queries exactly matching a query key:
377await queryClient.refetchQueries({
378 queryKey: ['posts', 1],
379 type: 'active',
380 exact: true,
381})
382```
383β
384**Options**
385β
386- `filters?: QueryFilters`: [Query Filters](../framework/react/guides/filters.md#query-filters)
387- `options?: RefetchOptions`:
388 - `throwOnError?: boolean`
389 - When set to `true`, this method will throw if any of the query refetch tasks fail.
390 - `cancelRefetch?: boolean`
391 - Defaults to `true`
392 - Per default, a currently running request will be cancelled before a new request is made
393 - When set to `false`, no refetch will be made if there is already a request running.
394β
395**Returns**
396β
397This 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`
398β
399**Notes**
400β
401- Queries that are "disabled" because they only have disabled Observers will never be refetched.
402- Queries that are "static" because they only have Observers with a Static StaleTime will never be refetched.
403- Unlike [`invalidateQueries`](#queryclientinvalidatequeries), `refetchQueries` refetches all matching queries.
404β
405## `queryClient.cancelQueries`
406β
407The `cancelQueries` method can be used to cancel outgoing queries based on their query keys or any other functionally accessible property/state of the query.
408β
409This 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.
410β
411```tsx
412await queryClient.cancelQueries(
413 { queryKey: ['posts'], exact: true },
414 { silent: true },
415)
416```
417β
418**Options**
419β
420- `filters?: QueryFilters`: [Query Filters](../framework/react/guides/filters.md#query-filters)
421- `cancelOptions?: CancelOptions`: [Cancel Options](../framework/react/guides/query-cancellation.md#cancel-options)
422β
423**Returns**
424β
425This method does not return anything
426β
427## `queryClient.removeQueries`
428β
429The `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.
430β
431```tsx
432queryClient.removeQueries({ queryKey, exact: true })
433```
434β
435**Options**
436β
437- `filters?: QueryFilters`: [Query Filters](../framework/react/guides/filters.md#query-filters)
438β
439**Returns**
440β
441This method does not return anything
442β
443**Notes**
444β
445- Unlike [`invalidateQueries`](#queryclientinvalidatequeries) or [`refetchQueries`](#queryclientrefetchqueries), `removeQueries` removes matching queries from the cache instead of refetching them.
446β
447## `queryClient.resetQueries`
448β
449The `resetQueries` method can be used to reset queries in the cache to their
450initial state based on their query keys or any other functionally accessible
451property/state of the query.
452β
453This will notify subscribers — unlike `clear`, which removes all
454subscribers — and reset the query to its pre-loaded state — unlike
455`invalidateQueries`. If a query has `initialData`, the query's data will be
456reset to that. If a query is active, it will be refetched.
457β
458```tsx
459queryClient.resetQueries({ queryKey, exact: true })
460```
461β
462**Options**
463β
464- `filters?: QueryFilters`: [Query Filters](../framework/react/guides/filters.md#query-filters)
465- `options?: ResetOptions`:
466 - `throwOnError?: boolean`
467 - When set to `true`, this method will throw if any of the query refetch tasks fail.
468 - `cancelRefetch?: boolean`
469 - Defaults to `true`
470 - Per default, a currently running request will be cancelled before a new request is made
471 - When set to `false`, no refetch will be made if there is already a request running.
472β
473**Returns**
474β
475This method returns a promise that resolves when all active queries have been refetched.
476β
477## `queryClient.isFetching`
478β
479This `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)
480β
481```tsx
482if (queryClient.isFetching()) {
483 console.log('At least one query is fetching!')
484}
485```
486β
487TanStack Query also exports a handy [`useIsFetching`](../framework/react/reference/useIsFetching.md) hook that will let you subscribe to this state in your components without creating a manual subscription to the query cache.
488β
489**Options**
490β
491- `filters?: QueryFilters`: [Query Filters](../framework/react/guides/filters.md#query-filters)
492β
493**Returns**
494β
495This method returns the number of fetching queries.
496β
497## `queryClient.isMutating`
498β
499This `isMutating` method returns an `integer` representing how many mutations, if any, in the cache are currently fetching.
500β
501```tsx
502if (queryClient.isMutating()) {
503 console.log('At least one mutation is fetching!')
504}
505```
506β
507TanStack Query also exports a handy [`useIsMutating`](../framework/react/reference/useIsMutating.md) hook that will let you subscribe to this state in your components without creating a manual subscription to the mutation cache.
508β
509**Options**
510β
511- `filters: MutationFilters`: [Mutation Filters](../framework/react/guides/filters.md#mutation-filters)
512β
513**Returns**
514β
515This method returns the number of fetching mutations.
516β
517## `queryClient.getDefaultOptions`
518β
519The `getDefaultOptions` method returns the default options which have been set when creating the client or with `setDefaultOptions`.
520β
521```tsx
522const defaultOptions = queryClient.getDefaultOptions()
523```
524β
525## `queryClient.setDefaultOptions`
526β
527The `setDefaultOptions` method can be used to dynamically set the default options for this queryClient. Previously defined default options will be overwritten.
528β
529```tsx
530queryClient.setDefaultOptions({
531 queries: {
532 staleTime: Infinity,
533 },
534})
535```
536β
537## `queryClient.getQueryDefaults`
538β
539The `getQueryDefaults` method returns the default options which have been set for specific queries:
540β
541```tsx
542const defaultOptions = queryClient.getQueryDefaults(['posts'])
543```
544β
545> Note that if several query defaults match the given query key, they will be merged together based on the order of registration.
546> See [`setQueryDefaults`](#queryclientsetquerydefaults).
547β
548## `queryClient.setQueryDefaults`
549β
550`setQueryDefaults` can be used to set default options for specific queries:
551β
552```tsx
553queryClient.setQueryDefaults(['posts'], { queryFn: fetchPosts })
554β
555function Component() {
556 const { data } = useQuery({ queryKey: ['posts'] })
557}
558```
559β
560**Options**
561β
562- `queryKey: QueryKey`: [Query Keys](../framework/react/guides/query-keys.md)
563- `options: QueryOptions`
564β
565> As stated in [`getQueryDefaults`](#queryclientgetquerydefaults), the order of registration of query defaults does matter.
566> Since the matching defaults are merged by `getQueryDefaults`, the registration should be made in the following order: from the **most generic key** to the **least generic one** .
567> This way, more specific defaults will override more generic defaults.
568β
569## `queryClient.getMutationDefaults`
570β
571The `getMutationDefaults` method returns the default options which have been set for specific mutations:
572β
573```tsx
574const defaultOptions = queryClient.getMutationDefaults(['addPost'])
575```
576β
577## `queryClient.setMutationDefaults`
578β
579`setMutationDefaults` can be used to set default options for specific mutations:
580β
581```tsx
582queryClient.setMutationDefaults(['addPost'], { mutationFn: addPost })
583β
584function Component() {
585 const { data } = useMutation({ mutationKey: ['addPost'] })
586}
587```
588β
589**Options**
590β
591- `mutationKey: unknown[]`
592- `options: MutationOptions`
593β
594> Similar to [`setQueryDefaults`](#queryclientsetquerydefaults), the order of registration does matter here.
595β
596## `queryClient.getQueryCache`
597β
598The `getQueryCache` method returns the query cache this client is connected to.
599β
600```tsx
601const queryCache = queryClient.getQueryCache()
602```
603β
604## `queryClient.getMutationCache`
605β
606The `getMutationCache` method returns the mutation cache this client is connected to.
607β
608```tsx
609const mutationCache = queryClient.getMutationCache()
610```
611β
612## `queryClient.clear`
613β
614The `clear` method clears all connected caches.
615β
616```tsx
617queryClient.clear()
618```
619β
620## `queryClient.resumePausedMutations`
621β
622Can be used to resume mutations that have been paused because there was no network connection.
623β
624```tsx
625queryClient.resumePausedMutations()
626```