586 lines
11 KiB
Markdown
586 lines
11 KiB
Markdown
---
|
|
id: Query
|
|
title: Query
|
|
---
|
|
|
|
Defined in: [packages/query-core/src/query.ts:225](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L225)
|
|
|
|
Represents a single cached query. A `Query` holds the query's key, options,
|
|
state (data/error/status), and the observers currently subscribed to it.
|
|
|
|
Instances are created and managed internally by `QueryCache`; application
|
|
code typically interacts with queries indirectly through `QueryClient` or
|
|
a framework hook like `useQuery`. Direct access to a `Query` instance is
|
|
possible via `queryCache.find()`/`findAll()` for inspecting cache state.
|
|
|
|
## Example
|
|
|
|
```ts
|
|
const queryCache = queryClient.getQueryCache()
|
|
const query = queryCache.find({ queryKey: ['posts'] })
|
|
|
|
if (query) {
|
|
console.log(query.state.dataUpdatedAt)
|
|
}
|
|
```
|
|
|
|
## Extends
|
|
|
|
- `Removable`
|
|
|
|
## Type Parameters
|
|
|
|
### TQueryFnData
|
|
|
|
`TQueryFnData` = `unknown`
|
|
|
|
### TError
|
|
|
|
`TError` = [`DefaultError`](../type-aliases/DefaultError.md)
|
|
|
|
### TData
|
|
|
|
`TData` = `TQueryFnData`
|
|
|
|
### TQueryKey
|
|
|
|
`TQueryKey` *extends* [`QueryKey`](../type-aliases/QueryKey.md) = [`QueryKey`](../type-aliases/QueryKey.md)
|
|
|
|
## Constructors
|
|
|
|
### Constructor
|
|
|
|
```ts
|
|
new Query<TQueryFnData, TError, TData, TQueryKey>(config): Query<TQueryFnData, TError, TData, TQueryKey>;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/query.ts:246](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L246)
|
|
|
|
#### Parameters
|
|
|
|
##### config
|
|
|
|
`QueryConfig`\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
|
|
|
|
#### Returns
|
|
|
|
`Query`\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
|
|
|
|
#### Overrides
|
|
|
|
```ts
|
|
Removable.constructor
|
|
```
|
|
|
|
## Properties
|
|
|
|
### gcTime
|
|
|
|
```ts
|
|
gcTime: number;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/removable.ts:7](https://github.com/TanStack/query/blob/main/packages/query-core/src/removable.ts#L7)
|
|
|
|
#### Inherited from
|
|
|
|
```ts
|
|
Removable.gcTime
|
|
```
|
|
|
|
***
|
|
|
|
### observers
|
|
|
|
```ts
|
|
observers: QueryObserver<any, any, any, any, any>[];
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/query.ts:242](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L242)
|
|
|
|
***
|
|
|
|
### options
|
|
|
|
```ts
|
|
options: QueryOptions<TQueryFnData, TError, TData, TQueryKey>;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/query.ts:233](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L233)
|
|
|
|
***
|
|
|
|
### queryHash
|
|
|
|
```ts
|
|
queryHash: string;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/query.ts:232](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L232)
|
|
|
|
***
|
|
|
|
### queryKey
|
|
|
|
```ts
|
|
queryKey: TQueryKey;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/query.ts:231](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L231)
|
|
|
|
***
|
|
|
|
### state
|
|
|
|
```ts
|
|
state: QueryState<TData, TError>;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/query.ts:234](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L234)
|
|
|
|
## Accessors
|
|
|
|
### meta
|
|
|
|
#### Get Signature
|
|
|
|
```ts
|
|
get meta(): Record<string, unknown> | undefined;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/query.ts:264](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L264)
|
|
|
|
The `meta` object passed in the query's options, if any.
|
|
|
|
##### Returns
|
|
|
|
`Record`\<`string`, `unknown`\> \| `undefined`
|
|
|
|
***
|
|
|
|
### promise
|
|
|
|
#### Get Signature
|
|
|
|
```ts
|
|
get promise(): Promise<TData> | undefined;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/query.ts:277](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L277)
|
|
|
|
The promise for the currently in-flight fetch, if the query is fetching.
|
|
`undefined` when the query is not fetching.
|
|
|
|
##### Returns
|
|
|
|
`Promise`\<`TData`\> \| `undefined`
|
|
|
|
## Methods
|
|
|
|
### cancel()
|
|
|
|
```ts
|
|
cancel(options?): Promise<void>;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/query.ts:348](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L348)
|
|
|
|
Cancels the query's currently in-flight fetch, if any.
|
|
- Returns a promise that resolves once the cancellation has settled.
|
|
- If no fetch is in progress, resolves immediately.
|
|
|
|
#### Parameters
|
|
|
|
##### options?
|
|
|
|
[`CancelOptions`](../interfaces/CancelOptions.md)
|
|
|
|
#### Returns
|
|
|
|
`Promise`\<`void`\>
|
|
|
|
#### Example
|
|
|
|
```ts
|
|
await query.cancel()
|
|
```
|
|
|
|
***
|
|
|
|
### clearGcTimeout()
|
|
|
|
```ts
|
|
protected clearGcTimeout(): void;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/removable.ts:32](https://github.com/TanStack/query/blob/main/packages/query-core/src/removable.ts#L32)
|
|
|
|
#### Returns
|
|
|
|
`void`
|
|
|
|
#### Inherited from
|
|
|
|
```ts
|
|
Removable.clearGcTimeout
|
|
```
|
|
|
|
***
|
|
|
|
### destroy()
|
|
|
|
```ts
|
|
destroy(): void;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/query.ts:361](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L361)
|
|
|
|
Clears the query's garbage collection timeout and silently cancels any
|
|
in-flight fetch. Called by `QueryCache` when the query is removed from
|
|
the cache.
|
|
|
|
#### Returns
|
|
|
|
`void`
|
|
|
|
#### See
|
|
|
|
[Query#cancel](#cancel)
|
|
|
|
#### Overrides
|
|
|
|
```ts
|
|
Removable.destroy
|
|
```
|
|
|
|
***
|
|
|
|
### fetch()
|
|
|
|
```ts
|
|
fetch(options?, fetchOptions?): Promise<TData>;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/query.ts:590](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L590)
|
|
|
|
Fetches the query, i.e. runs its `queryFn` (through any configured
|
|
retryer/behavior) and updates the query's state with the result.
|
|
- If a fetch is already in flight, returns its promise instead of
|
|
starting a new one, unless `fetchOptions.cancelRefetch` is set and the
|
|
query already has data, in which case the current fetch is silently
|
|
cancelled first.
|
|
- If `options` is passed, it replaces the query's current options
|
|
before fetching.
|
|
|
|
#### Parameters
|
|
|
|
##### options?
|
|
|
|
[`QueryOptions`](../interfaces/QueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `never`\>
|
|
|
|
##### fetchOptions?
|
|
|
|
`FetchOptions`\<`TQueryFnData`\>
|
|
|
|
#### Returns
|
|
|
|
`Promise`\<`TData`\>
|
|
|
|
***
|
|
|
|
### getObserversCount()
|
|
|
|
```ts
|
|
getObserversCount(): number;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/query.ts:560](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L560)
|
|
|
|
Returns the number of observers currently subscribed to this query.
|
|
|
|
#### Returns
|
|
|
|
`number`
|
|
|
|
#### Example
|
|
|
|
```ts
|
|
if (query.getObserversCount() === 0) {
|
|
// no component is currently watching this query
|
|
}
|
|
```
|
|
|
|
***
|
|
|
|
### invalidate()
|
|
|
|
```ts
|
|
invalidate(): void;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/query.ts:574](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L574)
|
|
|
|
Marks the query as invalidated, unless it is already invalidated. This
|
|
updates `state.isInvalidated` and notifies observers, but does not by
|
|
itself trigger a refetch.
|
|
|
|
#### Returns
|
|
|
|
`void`
|
|
|
|
#### Example
|
|
|
|
```ts
|
|
query.invalidate()
|
|
```
|
|
|
|
***
|
|
|
|
### isActive()
|
|
|
|
```ts
|
|
isActive(): boolean;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/query.ts:386](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L386)
|
|
|
|
Returns `true` if the query has at least one observer for which `enabled`
|
|
does not resolve to `false`.
|
|
|
|
#### Returns
|
|
|
|
`boolean`
|
|
|
|
***
|
|
|
|
### isDisabled()
|
|
|
|
```ts
|
|
isDisabled(): boolean;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/query.ts:400](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L400)
|
|
|
|
Returns `true` if the query is disabled, meaning it will not fetch
|
|
automatically.
|
|
- If the query has observers, it is disabled when none of them are active
|
|
(see `isActive`).
|
|
- If the query has no observers, it is disabled when its `queryFn` is
|
|
`skipToken` or it has never been fetched.
|
|
|
|
#### Returns
|
|
|
|
`boolean`
|
|
|
|
***
|
|
|
|
### isFetched()
|
|
|
|
```ts
|
|
isFetched(): boolean;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/query.ts:412](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L412)
|
|
|
|
Returns `true` if the query has been fetched, i.e. it has resolved with
|
|
either data or an error at least once.
|
|
|
|
#### Returns
|
|
|
|
`boolean`
|
|
|
|
***
|
|
|
|
### isStale()
|
|
|
|
```ts
|
|
isStale(): boolean;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/query.ts:447](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L447)
|
|
|
|
Returns `true` if the query is stale.
|
|
- If the query has observers, defers to whether any observer's current
|
|
result reports `isStale` (which accounts for each observer's own
|
|
`staleTime` and `enabled` state).
|
|
- If the query has no observers, it is considered stale when it has no
|
|
data or has been invalidated.
|
|
|
|
#### Returns
|
|
|
|
`boolean`
|
|
|
|
#### See
|
|
|
|
[Query#isStaleByTime](#isstalebytime)
|
|
|
|
#### Example
|
|
|
|
```ts
|
|
if (query.isStale()) {
|
|
// refetch or otherwise treat the cached data as outdated
|
|
}
|
|
```
|
|
|
|
***
|
|
|
|
### isStaleByTime()
|
|
|
|
```ts
|
|
isStaleByTime(staleTime): boolean;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/query.ts:473](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L473)
|
|
|
|
Returns `true` if the query's data is stale relative to the given
|
|
`staleTime` (defaults to `0`).
|
|
- A query with no data is always stale.
|
|
- `staleTime: 'static'` is never stale.
|
|
- An invalidated query is always stale.
|
|
- Otherwise, staleness is based on elapsed time since `dataUpdatedAt`.
|
|
|
|
#### Parameters
|
|
|
|
##### staleTime
|
|
|
|
[`StaleTime`](../type-aliases/StaleTime.md) = `0`
|
|
|
|
#### Returns
|
|
|
|
`boolean`
|
|
|
|
#### See
|
|
|
|
[Query#isStale](#isstale)
|
|
|
|
#### Example
|
|
|
|
```ts
|
|
const isStale = query.isStaleByTime(1000 * 60)
|
|
```
|
|
|
|
***
|
|
|
|
### isStatic()
|
|
|
|
```ts
|
|
isStatic(): boolean;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/query.ts:420](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L420)
|
|
|
|
Returns `true` if the query has at least one observer configured with
|
|
`staleTime: 'static'`, meaning it is treated as never stale.
|
|
|
|
#### Returns
|
|
|
|
`boolean`
|
|
|
|
***
|
|
|
|
### optionalRemove()
|
|
|
|
```ts
|
|
protected optionalRemove(): void;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/query.ts:305](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L305)
|
|
|
|
#### Returns
|
|
|
|
`void`
|
|
|
|
#### Overrides
|
|
|
|
```ts
|
|
Removable.optionalRemove
|
|
```
|
|
|
|
***
|
|
|
|
### reset()
|
|
|
|
```ts
|
|
reset(): void;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/query.ts:377](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L377)
|
|
|
|
Resets the query back to its initial state (the state it had when it was
|
|
first created, e.g. any `initialData`), destroying it first to cancel any
|
|
in-flight fetch.
|
|
|
|
#### Returns
|
|
|
|
`void`
|
|
|
|
***
|
|
|
|
### scheduleGc()
|
|
|
|
```ts
|
|
protected scheduleGc(): void;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/removable.ts:14](https://github.com/TanStack/query/blob/main/packages/query-core/src/removable.ts#L14)
|
|
|
|
#### Returns
|
|
|
|
`void`
|
|
|
|
#### Inherited from
|
|
|
|
```ts
|
|
Removable.scheduleGc
|
|
```
|
|
|
|
***
|
|
|
|
### setState()
|
|
|
|
```ts
|
|
setState(state): void;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/query.ts:334](https://github.com/TanStack/query/blob/main/packages/query-core/src/query.ts#L334)
|
|
|
|
Merges the given partial state directly into this query's state, notifying observers. Used
|
|
by persistence and broadcast plugins to restore a state snapshot, and by devtools to let a
|
|
user manually trigger a loading/error state or edit the cached data.
|
|
|
|
#### Parameters
|
|
|
|
##### state
|
|
|
|
`Partial`\<[`QueryState`](../interfaces/QueryState.md)\<`TData`, `TError`\>\>
|
|
|
|
#### Returns
|
|
|
|
`void`
|
|
|
|
***
|
|
|
|
### updateGcTime()
|
|
|
|
```ts
|
|
protected updateGcTime(newGcTime): void;
|
|
```
|
|
|
|
Defined in: [packages/query-core/src/removable.ts:24](https://github.com/TanStack/query/blob/main/packages/query-core/src/removable.ts#L24)
|
|
|
|
#### Parameters
|
|
|
|
##### newGcTime
|
|
|
|
`number` | `undefined`
|
|
|
|
#### Returns
|
|
|
|
`void`
|
|
|
|
#### Inherited from
|
|
|
|
```ts
|
|
Removable.updateGcTime
|
|
```
|