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