Open History to see the last commit
1---
2id: Query
3title: Query
4---
5β
6Defined in: [packages/query-core/src/query.ts:283](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L283)
7β
8Represents a single cached query. A `Query` holds the query's key, options,
9state (data/error/status), and the observers currently subscribed to it.
10β
11Instances are created and managed internally by `QueryCache`; application
12code typically interacts with queries indirectly through `QueryClient` or
13a framework hook like `useQuery`. Direct access to a `Query` instance is
14possible via `queryCache.find()`/`findAll()` for inspecting cache state.
15β
16## Example
17β
18```ts
19const queryCache = queryClient.getQueryCache()
20const query = queryCache.find({ queryKey: ['posts'] })
21β
22if (query) {
23 console.log(query.state.dataUpdatedAt)
24}
25```
26β
27## Extends
28β
29- `Removable`
30β
31## Type Parameters
32β
33### TQueryFnData
34β
35`TQueryFnData` = `unknown`
36β
37### TError
38β
39`TError` = [`DefaultError`](../type-aliases/DefaultError.md)
40β
41### TData
42β
43`TData` = `TQueryFnData`
44β
45### TQueryKey
46β
47`TQueryKey` *extends* [`QueryKey`](../type-aliases/QueryKey.md) = [`QueryKey`](../type-aliases/QueryKey.md)
48β
49## Constructors
50β
51### Constructor
52β
53```ts
54new Query<TQueryFnData, TError, TData, TQueryKey>(config: QueryConfig<TQueryFnData, TError, TData, TQueryKey>): Query<TQueryFnData, TError, TData, TQueryKey>;
55```
56β
57Defined in: [packages/query-core/src/query.ts:304](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L304)
58β
59#### Parameters
60β
61##### config
62β
63`QueryConfig`\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
64β
65#### Returns
66β
67`Query`\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
68β
69#### Overrides
70β
71```ts
72Removable.constructor
73```
74β
75## Properties
76β
77### gcTime
78β
79```ts
80gcTime: number;
81```
82β
83Defined in: [packages/query-core/src/removable.ts:11](https://github.com/TanStack/query/blob/main/packages/query-core/src/removable.ts#L11)
84β
85#### Inherited from
86β
87```ts
88Removable.gcTime
89```
90β
91***
92β
93### observers
94β
95```ts
96observers: QueryObserver<any, any, any, any, any>[];
97```
98β
99Defined in: [packages/query-core/src/query.ts:300](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L300)
100β
101***
102β
103### options
104β
105```ts
106options: QueryOptions<TQueryFnData, TError, TData, TQueryKey>;
107```
108β
109Defined in: [packages/query-core/src/query.ts:291](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L291)
110β
111***
112β
113### queryHash
114β
115```ts
116queryHash: string;
117```
118β
119Defined in: [packages/query-core/src/query.ts:290](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L290)
120β
121***
122β
123### queryKey
124β
125```ts
126queryKey: TQueryKey;
127```
128β
129Defined in: [packages/query-core/src/query.ts:289](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L289)
130β
131***
132β
133### state
134β
135```ts
136state: QueryState<TData, TError>;
137```
138β
139Defined in: [packages/query-core/src/query.ts:292](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L292)
140β
141## Accessors
142β
143### meta
144β
145#### Get Signature
146β
147```ts
148get meta(): Record<string, unknown> | undefined;
149```
150β
151Defined in: [packages/query-core/src/query.ts:323](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L323)
152β
153The `meta` object passed in the query's options, if any.
154β
155##### Returns
156β
157`Record`\<`string`, `unknown`\> \| `undefined`
158β
159The query's `meta`, or `undefined` if none was set.
160β
161***
162β
163### promise
164β
165#### Get Signature
166β
167```ts
168get promise(): Promise<TData> | undefined;
169```
170β
171Defined in: [packages/query-core/src/query.ts:341](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L341)
172β
173The promise for the currently in-flight fetch, if the query is fetching.
174`undefined` when the query is not fetching.
175β
176##### Returns
177β
178`Promise`\<`TData`\> \| `undefined`
179β
180The promise of the in-flight fetch, or `undefined`.
181β
182## Methods
183β
184### cancel()
185β
186```ts
187cancel(options?: CancelOptions): Promise<void>;
188```
189β
190Defined in: [packages/query-core/src/query.ts:427](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L427)
191β
192Cancels the query's currently in-flight fetch, if any.
193- Returns a promise that resolves once the cancellation has settled.
194- If no fetch is in progress, resolves immediately.
195β
196#### Parameters
197β
198##### options?
199β
200[`CancelOptions`](../interfaces/CancelOptions.md)
201β
202Set `revert` to restore the state from before the fetch started, and `silent`
203to suppress the cancellation error when a new fetch replaces the cancelled one.
204β
205#### Returns
206β
207`Promise`\<`void`\>
208β
209A promise that resolves once the cancellation has settled.
210β
211#### Example
212β
213```ts
214await query.cancel()
215```
216β
217***
218β
219### destroy()
220β
221```ts
222destroy(): void;
223```
224β
225Defined in: [packages/query-core/src/query.ts:439](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L439)
226β
227Clears the query's garbage collection timeout and silently cancels any
228in-flight fetch. Called by `QueryCache` when the query is removed from
229the cache.
230β
231#### Returns
232β
233`void`
234β
235#### See
236β
237[Query#cancel](#cancel)
238β
239#### Overrides
240β
241```ts
242Removable.destroy
243```
244β
245***
246β
247### fetch()
248β
249```ts
250fetch(options?: QueryOptions<TQueryFnData, TError, TData, TQueryKey, never>, fetchOptions?: FetchOptions<TQueryFnData>): Promise<TData>;
251```
252β
253Defined in: [packages/query-core/src/query.ts:703](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L703)
254β
255Fetches the query, i.e. runs its `queryFn` (through any configured
256retryer/behavior) and updates the query's state with the result.
257- If a fetch is already in flight, returns its promise instead of
258 starting a new one, unless `fetchOptions.cancelRefetch` is set and the
259 query already has data, in which case the current fetch is silently
260 cancelled first.
261- If `options` is passed, it replaces the query's current options
262 before fetching.
263β
264#### Parameters
265β
266##### options?
267β
268[`QueryOptions`](../interfaces/QueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `never`\>
269β
270Query options that replace the query's current options before fetching. They
271are not applied when an in-flight fetch is reused.
272β
273##### fetchOptions?
274β
275`FetchOptions`\<`TQueryFnData`\>
276β
277Set `cancelRefetch` to cancel an in-flight fetch first (only if the query
278already has data), and `meta` to pass extra information to the query's behavior.
279β
280#### Returns
281β
282`Promise`\<`TData`\>
283β
284A promise that resolves with the fetched data, or rejects with the fetch error. If the
285fetch is cancelled with `revert` while the query has data, it resolves with the restored data
286instead.
287β
288***
289β
290### getObserversCount()
291β
292```ts
293getObserversCount(): number;
294```
295β
296Defined in: [packages/query-core/src/query.ts:667](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L667)
297β
298Returns the number of observers currently subscribed to this query.
299β
300#### Returns
301β
302`number`
303β
304The number of observers.
305β
306#### Example
307β
308```ts
309if (query.getObserversCount() === 0) {
310 // no component is currently watching this query
311}
312```
313β
314***
315β
316### invalidate()
317β
318```ts
319invalidate(): void;
320```
321β
322Defined in: [packages/query-core/src/query.ts:680](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L680)
323β
324Marks the query as invalidated, unless it is already invalidated. This
325updates `state.isInvalidated` and notifies observers, but does not by
326itself trigger a refetch.
327β
328#### Returns
329β
330`void`
331β
332#### Example
333β
334```ts
335query.invalidate()
336```
337β
338***
339β
340### isActive()
341β
342```ts
343isActive(): boolean;
344```
345β
346Defined in: [packages/query-core/src/query.ts:469](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L469)
347β
348Returns `true` if the query has at least one observer for which `enabled`
349does not resolve to `false`.
350β
351#### Returns
352β
353`boolean`
354β
355`true` if the query has an enabled observer.
356β
357***
358β
359### isDisabled()
360β
361```ts
362isDisabled(): boolean;
363```
364β
365Defined in: [packages/query-core/src/query.ts:484](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L484)
366β
367Returns `true` if the query is disabled, meaning it will not fetch
368automatically.
369- If the query has observers, it is disabled when none of them are active
370 (see `isActive`).
371- If the query has no observers, it is disabled when its `queryFn` is
372 `skipToken` or it has never been fetched.
373β
374#### Returns
375β
376`boolean`
377β
378`true` if the query is disabled.
379β
380***
381β
382### isFetched()
383β
384```ts
385isFetched(): boolean;
386```
387β
388Defined in: [packages/query-core/src/query.ts:497](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L497)
389β
390Returns `true` if the query has been fetched, i.e. it has resolved with
391either data or an error at least once.
392β
393#### Returns
394β
395`boolean`
396β
397`true` if the query has been fetched.
398β
399***
400β
401### isStale()
402β
403```ts
404isStale(): boolean;
405```
406β
407Defined in: [packages/query-core/src/query.ts:533](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L533)
408β
409Returns `true` if the query is stale.
410- If the query has observers, defers to whether any observer's current
411 result reports `isStale` (which accounts for each observer's own
412 `staleTime` and `enabled` state).
413- If the query has no observers, it is considered stale when it has no
414 data or has been invalidated.
415β
416#### Returns
417β
418`boolean`
419β
420`true` if the query is stale.
421β
422#### See
423β
424[Query#isStaleByTime](#isstalebytime)
425β
426#### Example
427β
428```ts
429if (query.isStale()) {
430 // refetch or otherwise treat the cached data as outdated
431}
432```
433β
434***
435β
436### isStaleByTime()
437β
438```ts
439isStaleByTime(staleTime?: number | "static"): boolean;
440```
441β
442Defined in: [packages/query-core/src/query.ts:561](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L561)
443β
444Returns `true` if the query's data is stale relative to the given
445`staleTime` (defaults to `0`).
446- A query with no data is always stale.
447- `staleTime: 'static'` is never stale.
448- An invalidated query is always stale.
449- Otherwise, staleness is based on elapsed time since `dataUpdatedAt`.
450β
451#### Parameters
452β
453##### staleTime?
454β
455`number` \| `"static"`
456β
457The time, in milliseconds, after which data is considered stale, or
458`'static'` to never treat existing data as stale. A query without data is stale either way.
459β
460#### Returns
461β
462`boolean`
463β
464`true` if the query's data is stale.
465β
466#### See
467β
468[Query#isStale](#isstale)
469β
470#### Example
471β
472```ts
473const isStale = query.isStaleByTime(1000 * 60)
474```
475β
476***
477β
478### isStatic()
479β
480```ts
481isStatic(): boolean;
482```
483β
484Defined in: [packages/query-core/src/query.ts:506](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L506)
485β
486Returns `true` if the query has at least one observer configured with
487`staleTime: 'static'`, meaning it is treated as never stale.
488β
489#### Returns
490β
491`boolean`
492β
493`true` if the query is static.
494β
495***
496β
497### reset()
498β
499```ts
500reset(): void;
501```
502β
503Defined in: [packages/query-core/src/query.ts:459](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L459)
504β
505Resets the query back to its initial state (the state it had when it was
506first created, e.g. any `initialData`), destroying it first to cancel any
507in-flight fetch.
508β
509#### Returns
510β
511`void`
512β
513***
514β
515### setState()
516β
517```ts
518setState(state: Partial<QueryState<TData, TError>>): void;
519```
520β
521Defined in: [packages/query-core/src/query.ts:411](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L411)
522β
523Merges the given partial state directly into this query's state, notifying observers. Used
524by persistence and broadcast plugins to restore a state snapshot, and by devtools to let a
525user manually trigger a loading/error state or edit the cached data.
526β
527#### Parameters
528β
529##### state
530β
531`Partial`\<[`QueryState`](../interfaces/QueryState.md)\<`TData`, `TError`\>\>
532β
533The partial state to merge into the query's state.
534β
535#### Returns
536β
537`void`