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- [`find`](#querycachefind)
31- [`findAll`](#querycachefindall)
32- [`subscribe`](#querycachesubscribe)
33- [`clear`](#querycacheclear)
34β
35**Options**
36β
37- `onError?: (error: unknown, query: Query) => void`
38 - Optional
39 - This function will be called if some query encounters an error.
40- `onSuccess?: (data: unknown, query: Query) => void`
41 - Optional
42 - This function will be called if some query is successful.
43- `onSettled?: (data: unknown | undefined, error: unknown | null, query: Query) => void`
44 - Optional
45 - This function will be called if some query is settled (either successful or errored).
46β
47## `queryCache.find`
48β
49`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.
50β
51> 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)
52β
53```tsx
54const query = queryCache.find(queryKey)
55```
56β
57**Options**
58β
59- `filters?: QueryFilters`: [Query Filters](../../framework/react/guides/filters#query-filters)
60β
61**Returns**
62β
63- `Query`
64 - The query instance from the cache
65β
66## `queryCache.findAll`
67β
68`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.
69β
70> Note: This is not typically needed for most applications, but can come in handy when needing more information about a query in rare scenarios
71β
72```tsx
73const queries = queryCache.findAll(queryKey)
74```
75β
76**Options**
77β
78- `queryKey?: QueryKey`: [Query Keys](../../framework/react/guides/query-keys)
79- `filters?: QueryFilters`: [Query Filters](../../framework/react/guides/filters#query-filters)
80β
81**Returns**
82β
83- `Query[]`
84 - Query instances from the cache
85β
86## `queryCache.subscribe`
87β
88The `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
89β
90```tsx
91const callback = (event) => {
92 console.log(event.type, event.query)
93}
94β
95const unsubscribe = queryCache.subscribe(callback)
96```
97β
98**Options**
99β
100- `callback: (event: QueryCacheNotifyEvent) => void`
101 - 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
102β
103**Returns**
104β
105- `unsubscribe: Function => void`
106 - This function will unsubscribe the callback from the query cache.
107β
108## `queryCache.clear`
109β
110The `clear` method can be used to clear the cache entirely and start fresh.
111β
112```tsx
113queryCache.clear()
114```
115β
116[//]: # 'Materials'
117β
118## Further reading
119β
120To get a better understanding how the QueryCache works internally, have a look at [#18: Inside React Query
121](../../framework/react/community/tkdodos-blog#18-inside-react-query) from the Community Resources.
122β
123[//]: # 'Materials'