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