Skip to content
Source
Sign inSign up
TanStack/query
Open History to see the last commit

QueryCache.md

115 lines3.8 KB

1---
2id: QueryCache
3title: QueryCache
4---
5​
6The `QueryCache` is the storage mechanism for React 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```js
11import { QueryCache } from 'react-query'
12​
13const queryCache = new QueryCache({
14 onError: error => {
15 console.log(error)
16 },
17 onSuccess: data => {
18 console.log(data)
19 }
20})
21​
22const query = queryCache.find('posts')
23```
24​
25Its available methods are:
26​
27- [`find`](#querycachefind)
28- [`findAll`](#querycachefindall)
29- [`subscribe`](#querycachesubscribe)
30- [`clear`](#querycacheclear)
31​
32**Options**
33​
34- `onError?: (error: unknown, query: Query) => void`
35 - Optional
36 - This function will be called if some query encounters an error.
37- `onSuccess?: (data: unknown, query: Query) => void`
38 - Optional
39 - This function will be called if some query is successful.
40​
41## Global callbacks
42​
43The `onError` and `onSuccess` 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:
44- `defaultOptions` can be overridden by each Query - the global callbacks will **always** be called.
45- `defaultOptions` callbacks will be called once for each Observer, while the global callbacks will only be called once per Query.
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```js
54const query = queryCache.find(queryKey)
55```
56​
57**Options**
58​
59- `queryKey?: QueryKey`: [Query Keys](../guides/query-keys)
60- `filters?: QueryFilters`: [Query Filters](../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```js
74const queries = queryCache.findAll(queryKey)
75```
76​
77**Options**
78​
79- `queryKey?: QueryKey`: [Query Keys](../guides/query-keys)
80- `filters?: QueryFilters`: [Query Filters](../guides/filters#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```js
92const callback = event => {
93 console.log(event.type, event.query)
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```js
114queryCache.clear()
115```