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