upstream-tanstack-query/docs/framework/vue/reference/classes/Query.md

id, title

id	title
Query	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