Defined in: packages/query-core/src/query.ts:225
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#
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
TData#
TData = TQueryFnData
TQueryKey#
TQueryKey extends QueryKey = QueryKey
Constructors#
Constructor#
new Query<TQueryFnData, TError, TData, TQueryKey>(config: QueryConfig<TQueryFnData, TError, TData, TQueryKey>): Query<TQueryFnData, TError, TData, TQueryKey>;
Defined in: packages/query-core/src/query.ts:246
Parameters#
config#
QueryConfig<TQueryFnData, TError, TData, TQueryKey>
Returns#
Query<TQueryFnData, TError, TData, TQueryKey>
Overrides#
Removable.constructor
Properties#
gcTime#
gcTime: number;
Defined in: packages/query-core/src/removable.ts:7
Inherited from#
Removable.gcTime
observers#
observers: QueryObserver<any, any, any, any, any>[];
Defined in: packages/query-core/src/query.ts:242
options#
options: QueryOptions<TQueryFnData, TError, TData, TQueryKey>;
Defined in: packages/query-core/src/query.ts:233
queryHash#
queryHash: string;
Defined in: packages/query-core/src/query.ts:232
queryKey#
queryKey: TQueryKey;
Defined in: packages/query-core/src/query.ts:231
state#
state: QueryState<TData, TError>;
Defined in: packages/query-core/src/query.ts:234
Accessors#
meta#
Get Signature#
get meta(): Record<string, unknown> | undefined;
Defined in: packages/query-core/src/query.ts:264
The meta object passed in the query's options, if any.
Returns#
Record<string, unknown> | undefined
promise#
Get Signature#
get promise(): Promise<TData> | undefined;
Defined in: packages/query-core/src/query.ts:277
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()#
cancel(options?: CancelOptions): Promise<void>;
Defined in: packages/query-core/src/query.ts:348
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?#
Returns#
Promise<void>
Example#
await query.cancel()
clearGcTimeout()#
protected clearGcTimeout(): void;
Defined in: packages/query-core/src/removable.ts:32
Returns#
void
Inherited from#
Removable.clearGcTimeout
destroy()#
destroy(): void;
Defined in: packages/query-core/src/query.ts:361
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#
Overrides#
Removable.destroy
fetch()#
fetch(options?: QueryOptions<TQueryFnData, TError, TData, TQueryKey, never>, fetchOptions?: FetchOptions<TQueryFnData>): Promise<TData>;
Defined in: packages/query-core/src/query.ts:590
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.cancelRefetchis set and the query already has data, in which case the current fetch is silently cancelled first. - If
optionsis 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()#
getObserversCount(): number;
Defined in: packages/query-core/src/query.ts:560
Returns the number of observers currently subscribed to this query.
Returns#
number
Example#
if (query.getObserversCount() === 0) {
// no component is currently watching this query
}
invalidate()#
invalidate(): void;
Defined in: packages/query-core/src/query.ts:574
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#
query.invalidate()
isActive()#
isActive(): boolean;
Defined in: packages/query-core/src/query.ts:386
Returns true if the query has at least one observer for which enabled
does not resolve to false.
Returns#
boolean
isDisabled()#
isDisabled(): boolean;
Defined in: packages/query-core/src/query.ts:400
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
queryFnisskipTokenor it has never been fetched.
Returns#
boolean
isFetched()#
isFetched(): boolean;
Defined in: packages/query-core/src/query.ts:412
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()#
isStale(): boolean;
Defined in: packages/query-core/src/query.ts:447
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 ownstaleTimeandenabledstate). - If the query has no observers, it is considered stale when it has no data or has been invalidated.
Returns#
boolean
See#
Example#
if (query.isStale()) {
// refetch or otherwise treat the cached data as outdated
}
isStaleByTime()#
isStaleByTime(staleTime: number | "static"): boolean;
Defined in: packages/query-core/src/query.ts:473
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#
number | "static"
Returns#
boolean
See#
Example#
const isStale = query.isStaleByTime(1000 * 60)
isStatic()#
isStatic(): boolean;
Defined in: packages/query-core/src/query.ts:420
Returns true if the query has at least one observer configured with
staleTime: 'static', meaning it is treated as never stale.
Returns#
boolean
optionalRemove()#
protected optionalRemove(): void;
Defined in: packages/query-core/src/query.ts:305
Returns#
void
Overrides#
Removable.optionalRemove
reset()#
reset(): void;
Defined in: packages/query-core/src/query.ts:377
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()#
protected scheduleGc(): void;
Defined in: packages/query-core/src/removable.ts:14
Returns#
void
Inherited from#
Removable.scheduleGc
setState()#
setState(state: Partial<QueryState<TData, TError>>): void;
Defined in: packages/query-core/src/query.ts:334
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<TData, TError>>
Returns#
void
updateGcTime()#
protected updateGcTime(newGcTime: number | undefined): void;
Defined in: packages/query-core/src/removable.ts:24
Parameters#
newGcTime#
number | undefined
Returns#
void
Inherited from#
Removable.updateGcTime