Open History to see the last commit
1---
2id: QueryCache
3title: QueryCache
4---
5β
6The `QueryCache` is the storage mechanism for TanStack Query. It stores all the data, meta information and state of queries it contains.
7β
8**Normally, you will not interact with the QueryCache directly and instead use the `QueryClient` for a specific cache.**
9β
10```tsx
11import { QueryCache } from '@tanstack/react-query'
12β
13const queryCache = new QueryCache({
14 onError: (error) => {
15 console.log(error)
16 },
17 onSuccess: (data) => {
18 console.log(data)
19 },
20 onSettled: (data, error) => {
21 console.log(data, error)
22 },
23})
24β
25const query = queryCache.find(['posts'])
26```
27β
28Its available methods are:
29β
30- [`queryCache.find`](#querycachefind)
31- [`queryCache.findAll`](#querycachefindall)
32- [`queryCache.subscribe`](#querycachesubscribe)
33- [`queryCache.clear`](#querycacheclear)
34- [Further reading](#further-reading)
35β
36**Options**
37β
38- `onError?: (error: unknown, query: Query) => void`
39 - Optional
40 - This function will be called if some query encounters an error.
41- `onSuccess?: (data: unknown, query: Query) => void`
42 - Optional
43 - This function will be called if some query is successful.
44- `onSettled?: (data: unknown | undefined, error: unknown | null, query: Query) => void`
45 - Optional
46 - This function will be called if some query is settled (either successful or errored).
47β
48## `queryCache.find`
49β
50`find` is a slightly more advanced synchronous method that can be used to get an existing query instance from the cache. This instance not only contains **all** the state for the query, but all of the instances, and underlying guts of the query as well. If the query does not exist, `undefined` will be returned.
51β
52> Note: This is not typically needed for most applications, but can come in handy when needing more information about a query in rare scenarios (eg. Looking at the query.state.dataUpdatedAt timestamp to decide whether a query is fresh enough to be used as an initial value)
53β
54```tsx
55const query = queryCache.find(queryKey)
56```
57β
58**Options**
59β
60- `filters?: QueryFilters`: [Query Filters](../framework/react/guides/filters#query-filters)
61β
62**Returns**
63β
64- `Query`
65 - The query instance from the cache
66β
67## `queryCache.findAll`
68β
69`findAll` is even more advanced synchronous method that can be used to get existing query instances from the cache that partially match query key. If queries do not exist, empty array will be returned.
70β
71> Note: This is not typically needed for most applications, but can come in handy when needing more information about a query in rare scenarios
72β
73```tsx
74const queries = queryCache.findAll(queryKey)
75```
76β
77**Options**
78β
79- `queryKey?: QueryKey`: [Query Keys](../framework/react/guides/query-keys.md)
80- `filters?: QueryFilters`: [Query Filters](../framework/react/guides/filters.md#query-filters)
81β
82**Returns**
83β
84- `Query[]`
85 - Query instances from the cache
86β
87## `queryCache.subscribe`
88β
89The `subscribe` method can be used to subscribe to the query cache as a whole and be informed of safe/known updates to the cache like query states changing or queries being updated, added or removed
90β
91```tsx
92const callback = (event) => {
93 console.log(event.type, event.query)
94}
95β
96const unsubscribe = queryCache.subscribe(callback)
97```
98β
99**Options**
100β
101- `callback: (event: QueryCacheNotifyEvent) => void`
102 - This function will be called with the query cache any time it is updated via its tracked update mechanisms (eg, `query.setState`, `queryClient.removeQueries`, etc). Out of scope mutations to the cache are not encouraged and will not fire subscription callbacks
103β
104**Returns**
105β
106- `unsubscribe: Function => void`
107 - This function will unsubscribe the callback from the query cache.
108β
109## `queryCache.clear`
110β
111The `clear` method can be used to clear the cache entirely and start fresh.
112β
113```tsx
114queryCache.clear()
115```
116β
117[//]: # 'Materials'
118β
119## Further reading
120β
121To get a better understanding how the QueryCache works internally, have a look at [the Inside React Query article by TkDodo](https://tkdodo.eu/blog/inside-react-query).
122β
123[//]: # 'Materials'