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## Global callbacks
48β
49The `onError`, `onSuccess` and `onSettled` callbacks on the QueryCache can be used to handle these events on a global level. They are different to `defaultOptions` provided to the QueryClient because:
50β
51- `defaultOptions` can be overridden by each Query - the global callbacks will **always** be called.
52- `defaultOptions` callbacks will be called once for each Observer, while the global callbacks will only be called once per Query.
53β
54## `queryCache.find`
55β
56`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.
57β
58> 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)
59β
60```tsx
61const query = queryCache.find(queryKey)
62```
63β
64**Options**
65β
66- `queryKey?: QueryKey`: [Query Keys](./framework/react/guides/query-keys)
67- `filters?: QueryFilters`: [Query Filters](./framework/react/guides/filters#query-filters)
68β
69**Returns**
70β
71- `Query`
72 - The query instance from the cache
73β
74## `queryCache.findAll`
75β
76`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.
77β
78> Note: This is not typically needed for most applications, but can come in handy when needing more information about a query in rare scenarios
79β
80```tsx
81const queries = queryCache.findAll(queryKey)
82```
83β
84**Options**
85β
86- `queryKey?: QueryKey`: [Query Keys](./framework/react/guides/query-keys)
87- `filters?: QueryFilters`: [Query Filters](./framework/react/guides/filters#query-filters)
88β
89**Returns**
90β
91- `Query[]`
92 - Query instances from the cache
93β
94## `queryCache.subscribe`
95β
96The `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
97β
98```tsx
99const callback = (event) => {
100 console.log(event.type, event.query)
101}
102β
103const unsubscribe = queryCache.subscribe(callback)
104```
105β
106**Options**
107β
108- `callback: (event: QueryCacheNotifyEvent) => void`
109 - 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
110β
111**Returns**
112β
113- `unsubscribe: Function => void`
114 - This function will unsubscribe the callback from the query cache.
115β
116## `queryCache.clear`
117β
118The `clear` method can be used to clear the cache entirely and start fresh.
119β
120```tsx
121queryCache.clear()
122```
123β
124[//]: # 'Materials'
125β
126## Further reading
127β
128To get a better understanding how the QueryCache works internally, have a look at [#18: Inside React Query
129](./framework/react/community/tkdodos-blog#18-inside-react-query) from the Community Resources.
130β
131[//]: # 'Materials'