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

Query.md

539 lines11.5 KB

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:283](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L283)
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)
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:304](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L304)
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:300](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L300)
102​
103***
104​
105### options
106​
107```ts
108options: QueryOptions<TQueryFnData, TError, TData, TQueryKey>;
109```
110​
111Defined in: [packages/query-core/src/query.ts:291](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L291)
112​
113***
114​
115### queryHash
116​
117```ts
118queryHash: string;
119```
120​
121Defined in: [packages/query-core/src/query.ts:290](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L290)
122​
123***
124​
125### queryKey
126​
127```ts
128queryKey: TQueryKey;
129```
130​
131Defined in: [packages/query-core/src/query.ts:289](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L289)
132​
133***
134​
135### state
136​
137```ts
138state: QueryState<TData, TError>;
139```
140​
141Defined in: [packages/query-core/src/query.ts:292](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L292)
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:323](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L323)
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:341](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L341)
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:427](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L427)
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:439](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L439)
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:703](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L703)
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:667](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L667)
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
314```
315​
316***
317​
318### invalidate()
319​
320```ts
321invalidate(): void;
322```
323​
324Defined in: [packages/query-core/src/query.ts:680](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L680)
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:469](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L469)
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:484](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L484)
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:497](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L497)
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:533](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L533)
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
434```
435​
436***
437​
438### isStaleByTime()
439​
440```ts
441isStaleByTime(staleTime?: number | "static"): boolean;
442```
443​
444Defined in: [packages/query-core/src/query.ts:561](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L561)
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(1000 * 60)
476```
477​
478***
479​
480### isStatic()
481​
482```ts
483isStatic(): boolean;
484```
485​
486Defined in: [packages/query-core/src/query.ts:506](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L506)
487​
488Returns `true` if the query has 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:459](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L459)
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:411](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L411)
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`