Open History to see the last commit
1---
2id: QueryCache
3title: QueryCache
4redirect_from:
5 - reference/QueryCache
6 - framework/react/reference/QueryCache
7---
8β
9<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
10β
11Defined in: [packages/query-core/src/queryCache.ts:140](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryCache.ts#L140)
12β
13The `QueryCache` is the storage mechanism for TanStack Query. It stores all the data, meta
14information, and state of the queries it contains.
15β
16Normally, you will not interact with the `QueryCache` directly and instead use a `QueryClient`
17for a specific cache. You can subscribe to it (inherited from `Subscribable`) to be informed of
18safe/known updates to the cache, such as queries being added, removed, or updated β updates made
19outside of the cache's own tracked mechanisms (e.g. mutating a query's state object directly) do
20not notify subscribers.
21β
22## Example
23β
24```ts
25const unsubscribe = queryCache.subscribe((event) => {
26 console.log(event.type, event.query)
27})
28```
29β
30## Extends
31β
32- `Subscribable`\<`QueryCacheListener`\>
33β
34## Constructors
35β
36### Constructor
37β
38```ts
39new QueryCache(config?: QueryCacheConfig): QueryCache;
40```
41β
42Defined in: [packages/query-core/src/queryCache.ts:143](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryCache.ts#L143)
43β
44#### Parameters
45β
46##### config?
47β
48[`QueryCacheConfig`](../interfaces/QueryCacheConfig.md) = `{}`
49β
50#### Returns
51β
52`QueryCache`
53β
54#### Overrides
55β
56```ts
57Subscribable<QueryCacheListener>.constructor
58```
59β
60## Properties
61β
62### config
63β
64```ts
65config: QueryCacheConfig = {};
66```
67β
68Defined in: [packages/query-core/src/queryCache.ts:143](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryCache.ts#L143)
69β
70## Methods
71β
72### build()
73β
74```ts
75build<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(
76 client: QueryClient,
77 options: WithRequired<QueryOptions<TQueryFnData, TError, TData, TQueryKey, never>, "queryKey">,
78 state?: QueryState<TData, TError>
79): Query<TQueryFnData, TError, TData, TQueryKey>;
80```
81β
82Defined in: [packages/query-core/src/queryCache.ts:169](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryCache.ts#L169)
83β
84Returns the existing `Query` instance for the given options' `queryKey`/`queryHash`, or
85builds and adds a new one to the cache if none exists yet. Used by framework adapters and
86plugins (e.g. broadcast/persistence) that need to get-or-create a `Query` directly, bypassing
87the reactive `QueryObserver` machinery.
88β
89#### Type Parameters
90β
91##### TQueryFnData
92β
93`TQueryFnData` = `unknown`
94β
95##### TError
96β
97`TError` = `Error`
98β
99##### TData
100β
101`TData` = `TQueryFnData`
102β
103##### TQueryKey
104β
105`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
106β
107#### Parameters
108β
109##### client
110β
111[`QueryClient`](QueryClient.md)
112β
113The client the query belongs to, used to default its options.
114β
115##### options
116β
117[`WithRequired`](../type-aliases/WithRequired.md)\<[`QueryOptions`](../interfaces/QueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `never`\>, `"queryKey"`\>
118β
119The query options, including the `queryKey`. A new query is created with the
120options defaulted by [QueryClient#defaultQueryOptions](QueryClient.md#defaultqueryoptions).
121β
122##### state?
123β
124[`QueryState`](../interfaces/QueryState.md)\<`TData`, `TError`\>
125β
126The initial state of a newly created query, e.g. when hydrating. Ignored if the
127query already exists.
128β
129#### Returns
130β
131[`Query`](Query.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
132β
133The existing or newly created query.
134β
135#### Example
136β
137```ts
138const queryCache = queryClient.getQueryCache()
139β
140const query = queryCache.build(queryClient, {
141 queryKey: ['posts'],
142 queryFn: fetchPosts,
143})
144```
145β
146***
147β
148### clear()
149β
150```ts
151clear(): void;
152```
153β
154Defined in: [packages/query-core/src/queryCache.ts:254](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryCache.ts#L254)
155β
156Removes all queries from the cache.
157β
158#### Returns
159β
160`void`
161β
162#### Example
163β
164```ts
165const queryCache = queryClient.getQueryCache()
166β
167queryCache.clear()
168```
169β
170***
171β
172### find()
173β
174```ts
175find<TQueryFnData = unknown, TError = Error, TData = TQueryFnData>(filters: WithRequired<QueryFilters<readonly unknown[]>, "queryKey">):
176 | Query<TQueryFnData, TError, TData, readonly unknown[]>
177 | undefined;
178```
179β
180Defined in: [packages/query-core/src/queryCache.ts:324](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryCache.ts#L324)
181β
182A slightly more advanced method that can be used to get an existing query instance from the
183cache. This instance not only contains all the state for the query, but all of the instances,
184and underlying guts of the query as well. If the query does not exist, `undefined` is
185returned.
186β
187This is not typically needed for most applications, but can come in handy when needing more
188information about a query in rare scenarios (e.g. looking at `query.state.dataUpdatedAt` to
189decide whether a query is fresh enough to be used as an initial value).
190β
191#### Type Parameters
192β
193##### TQueryFnData
194β
195`TQueryFnData` = `unknown`
196β
197##### TError
198β
199`TError` = `Error`
200β
201##### TData
202β
203`TData` = `TQueryFnData`
204β
205#### Parameters
206β
207##### filters
208β
209[`WithRequired`](../type-aliases/WithRequired.md)\<[`QueryFilters`](../interfaces/QueryFilters.md)\<readonly `unknown`[]\>, `"queryKey"`\>
210β
211The filters to match, including the required `queryKey`. `exact` defaults to
212`true`.
213β
214#### Returns
215β
216 \| [`Query`](Query.md)\<`TQueryFnData`, `TError`, `TData`, readonly `unknown`[]\>
217 \| `undefined`
218β
219The first matching query, or `undefined`.
220β
221#### See
222β
223[QueryCache#findAll](#findall)
224β
225#### Example
226β
227```ts
228const queryCache = queryClient.getQueryCache()
229β
230const query = queryCache.find({ queryKey: ['posts'] })
231```
232β
233***
234β
235### findAll()
236β
237```ts
238findAll(filters?: QueryFilters<any>): Query<unknown, Error, unknown, readonly unknown[]>[];
239```
240β
241Defined in: [packages/query-core/src/queryCache.ts:350](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryCache.ts#L350)
242β
243An even more advanced method that can be used to get existing query instances from the cache
244that partially match a query key. If no queries match, an empty array is returned.
245β
246This is not typically needed for most applications, but can come in handy when needing more
247information about queries in rare scenarios.
248β
249#### Parameters
250β
251##### filters?
252β
253[`QueryFilters`](../interfaces/QueryFilters.md)\<`any`\> = `{}`
254β
255The filters to match. Without filters, every query is returned.
256β
257#### Returns
258β
259[`Query`](Query.md)\<`unknown`, `Error`, `unknown`, readonly `unknown`[]\>[]
260β
261The matching queries.
262β
263#### See
264β
265[QueryCache#find](#find)
266β
267#### Example
268β
269```ts
270const queryCache = queryClient.getQueryCache()
271β
272const queries = queryCache.findAll({ queryKey: ['posts'] })
273```
274β
275***
276β
277### get()
278β
279```ts
280get<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(queryHash: string):
281 | Query<TQueryFnData, TError, TData, TQueryKey>
282 | undefined;
283```
284β
285Defined in: [packages/query-core/src/queryCache.ts:277](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryCache.ts#L277)
286β
287Returns the `Query` instance stored under the given `queryHash`, or `undefined` if none
288exists. Unlike [QueryCache#find](#find), this looks up by the already-computed hash rather
289than by `QueryFilters`. Used by plugins (e.g. broadcast/hydration) that already have a hash
290to look up directly.
291β
292#### Type Parameters
293β
294##### TQueryFnData
295β
296`TQueryFnData` = `unknown`
297β
298##### TError
299β
300`TError` = `Error`
301β
302##### TData
303β
304`TData` = `TQueryFnData`
305β
306##### TQueryKey
307β
308`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
309β
310#### Parameters
311β
312##### queryHash
313β
314`string`
315β
316The hash of the query to look up.
317β
318#### Returns
319β
320 \| [`Query`](Query.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
321 \| `undefined`
322β
323The query stored under the hash, or `undefined`.
324β
325#### Example
326β
327```ts
328const queryCache = queryClient.getQueryCache()
329const queryHash = hashKey(['posts'])
330β
331const query = queryCache.get(queryHash)
332```
333β
334***
335β
336### getAll()
337β
338```ts
339getAll(): Query<unknown, Error, unknown, readonly unknown[]>[];
340```
341β
342Defined in: [packages/query-core/src/queryCache.ts:300](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryCache.ts#L300)
343β
344Returns all queries within the cache.
345β
346#### Returns
347β
348[`Query`](Query.md)\<`unknown`, `Error`, `unknown`, readonly `unknown`[]\>[]
349β
350Every query in the cache.
351β
352#### Example
353β
354```ts
355const queryCache = queryClient.getQueryCache()
356β
357const queries = queryCache.getAll()
358```
359β
360***
361β
362### hasListeners()
363β
364```ts
365hasListeners(): boolean;
366```
367β
368Defined in: [packages/query-core/src/subscribable.ts:43](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L43)
369β
370Returns `true` while at least one listener is registered, `false` once they have all unsubscribed.
371β
372#### Returns
373β
374`boolean`
375β
376`true` if at least one listener is registered.
377β
378#### Inherited from
379β
380```ts
381Subscribable.hasListeners
382```
383β
384***
385β
386### remove()
387β
388```ts
389remove(query: Query<any, any, any, any>): void;
390```
391β
392Defined in: [packages/query-core/src/queryCache.ts:235](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryCache.ts#L235)
393β
394Destroys the given `Query` and removes it from the cache, notifying subscribers with a
395`'removed'` event. A no-op if the query is no longer the one currently stored under its hash
396(e.g. it was already replaced). Used by plugins (e.g. the broadcast client) that mirror
397removals across `QueryCache` instances.
398β
399#### Parameters
400β
401##### query
402β
403[`Query`](Query.md)\<`any`, `any`, `any`, `any`\>
404β
405The query to remove.
406β
407#### Returns
408β
409`void`
410β
411#### Example
412β
413```ts
414const queryCache = queryClient.getQueryCache()
415const query = queryCache.find({ queryKey: ['posts'] })
416β
417if (query) {
418 queryCache.remove(query)
419}
420```
421β
422***
423β
424### subscribe()
425β
426```ts
427subscribe(listener: QueryCacheListener): () => void;
428```
429β
430Defined in: [packages/query-core/src/subscribable.ts:28](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L28)
431β
432Registers a listener to be called on every update this object notifies about. Returns a function
433that removes the listener again β call it to stop listening. The base class never drops a listener
434on its own, though some subclasses clear all of theirs in `destroy()`.
435β
436#### Parameters
437β
438##### listener
439β
440`QueryCacheListener`
441β
442Called on each update, with whatever the subclass passes to its subscribers.
443β
444#### Returns
445β
446A function that removes the listener.
447β
448() => `void`
449β
450#### Example
451β
452```ts
453const unsubscribe = subscribable.subscribe(() => {
454 // react to the update
455})
456β
457unsubscribe()
458```
459β
460#### Inherited from
461β
462```ts
463Subscribable.subscribe
464```