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.

const queryCache = queryClient.getQueryCache()
const query = queryCache.find({ queryKey: ['posts'] })

if (query) {
  console.log(query.state.dataUpdatedAt)
}

const queryCache = queryClient.getQueryCache()
const query = queryCache.find({ queryKey: ['posts'] })

if (query) {
  console.log(query.state.dataUpdatedAt)
}

• Removable

TQueryFnData = unknown

TError = DefaultError

TData = TQueryFnData

TQueryKey extends QueryKey = QueryKey

new Query<TQueryFnData, TError, TData, TQueryKey>(config: QueryConfig<TQueryFnData, TError, TData, TQueryKey>): Query<TQueryFnData, TError, TData, TQueryKey>;

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

QueryConfig<TQueryFnData, TError, TData, TQueryKey>

Query<TQueryFnData, TError, TData, TQueryKey>

Removable.constructor

Removable.constructor

gcTime: number;

gcTime: number;

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

Removable.gcTime

Removable.gcTime

observers: QueryObserver<any, any, any, any, any>[];

observers: QueryObserver<any, any, any, any, any>[];

Defined in: packages/query-core/src/query.ts:242

options: QueryOptions<TQueryFnData, TError, TData, TQueryKey>;

options: QueryOptions<TQueryFnData, TError, TData, TQueryKey>;

Defined in: packages/query-core/src/query.ts:233

queryHash: string;

queryHash: string;

Defined in: packages/query-core/src/query.ts:232

queryKey: TQueryKey;

queryKey: TQueryKey;

Defined in: packages/query-core/src/query.ts:231

state: QueryState<TData, TError>;

state: QueryState<TData, TError>;

Defined in: packages/query-core/src/query.ts:234

get meta(): Record<string, unknown> | undefined;

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.

Record<string, unknown> | undefined

get promise(): Promise<TData> | undefined;

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.

Promise<TData> | undefined

cancel(options?: CancelOptions): Promise<void>;

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.

CancelOptions

Promise<void>

await query.cancel()

await query.cancel()

protected clearGcTimeout(): void;

protected clearGcTimeout(): void;

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

void

Removable.clearGcTimeout

Removable.clearGcTimeout

destroy(): void;

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.

void

Query#cancel

Removable.destroy

Removable.destroy

fetch(options?: QueryOptions<TQueryFnData, TError, TData, TQueryKey, never>, fetchOptions?: FetchOptions<TQueryFnData>): Promise<TData>;

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.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.

QueryOptions<TQueryFnData, TError, TData, TQueryKey, never>

FetchOptions<TQueryFnData>

Promise<TData>

getObserversCount(): number;

getObserversCount(): number;

Defined in: packages/query-core/src/query.ts:560

Returns the number of observers currently subscribed to this query.

number

if (query.getObserversCount() === 0) {
  // no component is currently watching this query
}

if (query.getObserversCount() === 0) {
  // no component is currently watching this query
}

invalidate(): void;

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.

void

query.invalidate()

query.invalidate()

isActive(): boolean;

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.

boolean

isDisabled(): boolean;

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.

boolean

isFetched(): boolean;

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.

boolean

isStale(): boolean;

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.

boolean

Query#isStaleByTime

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

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

isStaleByTime(staleTime: number | "static"): boolean;

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.

number | "static"

boolean

Query#isStale

const isStale = query.isStaleByTime(1000 * 60)

const isStale = query.isStaleByTime(1000 * 60)

isStatic(): boolean;

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.

boolean

protected optionalRemove(): void;

protected optionalRemove(): void;

Defined in: packages/query-core/src/query.ts:305

void

Removable.optionalRemove

Removable.optionalRemove

reset(): void;

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.

void

protected scheduleGc(): void;

protected scheduleGc(): void;

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

void

Removable.scheduleGc

Removable.scheduleGc

setState(state: Partial<QueryState<TData, TError>>): void;

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.

Partial<QueryState<TData, TError>>

void

protected updateGcTime(newGcTime: number | undefined): void;

protected updateGcTime(newGcTime: number | undefined): void;

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

number | undefined

void

Removable.updateGcTime

Removable.updateGcTime