Query

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): 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?): 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?#

CancelOptions

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#

Query#cancel

Overrides#

Removable.destroy

fetch()#

fetch(options?, fetchOptions?): 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.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()#

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 queryFn is skipToken or 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 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

Example#

if (query.isStale()) {
  // refetch or otherwise treat the cached data as outdated
}

isStaleByTime()#

isStaleByTime(staleTime): 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#

StaleTime = 0

Returns#

boolean

See#

Query#isStale

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): 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): void;

Defined in: packages/query-core/src/removable.ts:24

Parameters#

newGcTime#

number | undefined

Returns#

void

Inherited from#

Removable.updateGcTime