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

QueryCache.md

464 lines10.5 KB

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:46](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L46)
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)
420```
421​
422***
423​
424### subscribe()
425​
426```ts
427subscribe(listener: QueryCacheListener): () => void;
428```
429​
430Defined in: [packages/query-core/src/subscribable.ts:31](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L31)
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```