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

QueryCache.md

458 lines10.1 KB

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`
106​
107The client the query belongs to, used to default its options.
108​
109##### options
110​
111[`WithRequired`](../type-aliases/WithRequired.md)\<`QueryOptions`\<`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)
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```