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

Query.md

537 lines11.3 KB

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)
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`\<`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
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
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`