Query

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

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:245

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:11

Inherited from#

Removable.gcTime

observers#

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

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

options#

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

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

queryHash#

queryHash: string;

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

queryKey#

queryKey: TQueryKey;

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

state#

state: QueryState<TData, TError>;

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

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

The query's meta, or undefined if none was set.

promise#

Get Signature#

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

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

The promise for the currently in-flight fetch, if the query is fetching. undefined when the query is not fetching.

Returns#

Promise<TData> | undefined

The promise of the in-flight fetch, or undefined.

Methods#

cancel()#

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

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

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

Set revert to restore the state from before the fetch started, and silent to suppress the cancellation error when a new fetch replaces the cancelled one.

Returns#

Promise<void>

A promise that resolves once the cancellation has settled.

Example#

await query.cancel()

destroy()#

destroy(): void;

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

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?: QueryOptions<TQueryFnData, TError, TData, TQueryKey, never>, fetchOptions?: FetchOptions<TQueryFnData>): Promise<TData>;

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

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>

Query options that replace the query's current options before fetching. They are not applied when an in-flight fetch is reused.

fetchOptions?#

FetchOptions<TQueryFnData>

Set cancelRefetch to cancel an in-flight fetch first (only if the query already has data), and meta to pass extra information to the query's behavior.

Returns#

Promise<TData>

A promise that resolves with the fetched data, or rejects with the fetch error. If the fetch is cancelled with revert while the query has data, it resolves with the restored data instead.

getObserversCount()#

getObserversCount(): number;

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

Returns the number of observers currently subscribed to this query.

Returns#

number

The number of observers.

Example#

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

invalidate()#

invalidate(): void;

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

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:410

Returns true if the query has at least one observer for which enabled does not resolve to false.

Returns#

boolean

true if the query has an enabled observer.

isDisabled()#

isDisabled(): boolean;

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

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

true if the query is disabled.

isFetched()#

isFetched(): boolean;

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

Returns true if the query has been fetched, i.e. it has resolved with either data or an error at least once.

Returns#

boolean

true if the query has been fetched.

isStale()#

isStale(): boolean;

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

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

true if the query is stale.

See#

Query#isStaleByTime

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:502

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#

The time, in milliseconds, after which data is considered stale, or 'static' to never treat existing data as stale. A query without data is stale either way.

number | "static"

Returns#

boolean

true if the query's data is stale.

See#

Query#isStale

Example#

const isStale = query.isStaleByTime(1000 * 60)

isStatic()#

isStatic(): boolean;

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

Returns true if the query has at least one observer configured with staleTime: 'static', meaning it is treated as never stale.

Returns#

boolean

true if the query is static.

reset()#

reset(): void;

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

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

setState()#

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

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

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

The partial state to merge into the query's state.

Returns#

void