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

QueryCache.md

461 lines10.4 KB

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`](QueryClient.md)
109​
110The client the query belongs to, used to default its options.
111​
112##### options
113​
114[`WithRequired`](../type-aliases/WithRequired.md)\<[`QueryOptions`](../interfaces/QueryOptions.md)\<`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:46](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L46)
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)
417```
418​
419***
420​
421### subscribe()
422​
423```ts
424subscribe(listener: QueryCacheListener): () => void;
425```
426​
427Defined in: [packages/query-core/src/subscribable.ts:31](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L31)
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```