--- 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(config): Query; ``` 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[]; ``` 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; ``` 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; ``` 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 | 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 | 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; ``` 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; ``` 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`\<`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 ```