QueryCache

Defined in: packages/query-core/src/queryCache.ts:123

The QueryCache is the storage mechanism for TanStack Query. It stores all the data, meta information, and state of the queries it contains.

Normally, you will not interact with the QueryCache directly and instead use a QueryClient for a specific cache. You can subscribe to it (inherited from Subscribable) to be informed of safe/known updates to the cache, such as queries being added, removed, or updated — updates made outside of the cache's own tracked mechanisms (e.g. mutating a query's state object directly) do not notify subscribers.

Example#

const unsubscribe = queryCache.subscribe((event) => {
  console.log(event.type, event.query)
})

Extends#

• Subscribable<QueryCacheListener>

Constructors#

Constructor#

new QueryCache(config): QueryCache;

Defined in: packages/query-core/src/queryCache.ts:126

Parameters#

config#

QueryCacheConfig = {}

Returns#

QueryCache

Overrides#

Subscribable<QueryCacheListener>.constructor

Properties#

config#

config: QueryCacheConfig = {};

Defined in: packages/query-core/src/queryCache.ts:126

listeners#

protected listeners: Set<QueryCacheListener>;

Defined in: packages/query-core/src/subscribable.ts:2

Inherited from#

Subscribable.listeners

Methods#

build()#

build<TQueryFnData, TError, TData, TQueryKey>(
   client,
   options,
state?): Query<TQueryFnData, TError, TData, TQueryKey>;

Defined in: packages/query-core/src/queryCache.ts:147

Returns the existing Query instance for the given options' queryKey/queryHash, or builds and adds a new one to the cache if none exists yet. Used by framework adapters and plugins (e.g. broadcast/persistence) that need to get-or-create a Query directly, bypassing the reactive QueryObserver machinery.

Type Parameters#

TQueryFnData#

TQueryFnData = unknown

TError#

TError = Error

TData#

TData = TQueryFnData

TQueryKey#

TQueryKey extends readonly unknown[] = readonly unknown[]

Parameters#

client#

QueryClient

options#

WithRequired<QueryOptions<TQueryFnData, TError, TData, TQueryKey, never>, "queryKey">

state?#

QueryState<TData, TError>

Returns#

Query<TQueryFnData, TError, TData, TQueryKey>

Example#

const queryCache = queryClient.getQueryCache()

const query = queryCache.build(queryClient, {
  queryKey: ['posts'],
  queryFn: fetchPosts,
})

clear()#

clear(): void;

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

Removes all queries from the cache.

Returns#

void

Example#

const queryCache = queryClient.getQueryCache()

queryCache.clear()

find()#

find<TQueryFnData, TError, TData>(filters):
  | Query<TQueryFnData, TError, TData, readonly unknown[]>
  | undefined;

Defined in: packages/query-core/src/queryCache.ts:299

A slightly more advanced method that can be used to get an existing query instance from the cache. This instance not only contains all the state for the query, but all of the instances, and underlying guts of the query as well. If the query does not exist, undefined is returned.

This is not typically needed for most applications, but can come in handy when needing more information about a query in rare scenarios (e.g. looking at query.state.dataUpdatedAt to decide whether a query is fresh enough to be used as an initial value).

Type Parameters#

TQueryFnData#

TQueryFnData = unknown

TError#

TError = Error

TData#

TData = TQueryFnData

Parameters#

filters#

WithRequired<QueryFilters<readonly unknown[]>, "queryKey">

Returns#

| Query<TQueryFnData, TError, TData, readonly unknown[]> | undefined

See#

QueryCache#findAll

Example#

const queryCache = queryClient.getQueryCache()

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

findAll()#

findAll(filters): Query<unknown, Error, unknown, readonly unknown[]>[];

Defined in: packages/query-core/src/queryCache.ts:324

An even more advanced method that can be used to get existing query instances from the cache that partially match a query key. If no queries match, an empty array is returned.

This is not typically needed for most applications, but can come in handy when needing more information about queries in rare scenarios.

Parameters#

filters#

QueryFilters<any> = {}

Returns#

Query<unknown, Error, unknown, readonly unknown[]>[]

See#

QueryCache#find

Example#

const queryCache = queryClient.getQueryCache()

const queries = queryCache.findAll({ queryKey: ['posts'] })

get()#

get<TQueryFnData, TError, TData, TQueryKey>(queryHash):
  | Query<TQueryFnData, TError, TData, TQueryKey>
  | undefined;

Defined in: packages/query-core/src/queryCache.ts:254

Returns the Query instance stored under the given queryHash, or undefined if none exists. Unlike QueryCache#find, this looks up by the already-computed hash rather than by QueryFilters. Used by plugins (e.g. broadcast/hydration) that already have a hash to look up directly.

Type Parameters#

TQueryFnData#

TQueryFnData = unknown

TError#

TError = Error

TData#

TData = TQueryFnData

TQueryKey#

TQueryKey extends readonly unknown[] = readonly unknown[]

Parameters#

queryHash#

string

Returns#

| Query<TQueryFnData, TError, TData, TQueryKey> | undefined

Example#

const queryCache = queryClient.getQueryCache()
const queryHash = hashKey(['posts'])

const query = queryCache.get(queryHash)

getAll()#

getAll(): Query<unknown, Error, unknown, readonly unknown[]>[];

Defined in: packages/query-core/src/queryCache.ts:277

Returns all queries within the cache.

Returns#

Query<unknown, Error, unknown, readonly unknown[]>[]

Example#

const queryCache = queryClient.getQueryCache()

const queries = queryCache.getAll()

hasListeners()#

hasListeners(): boolean;

Defined in: packages/query-core/src/subscribable.ts:19

Returns#

boolean

Inherited from#

Subscribable.hasListeners

onSubscribe()#

protected onSubscribe(): void;

Defined in: packages/query-core/src/subscribable.ts:23

Returns#

void

Inherited from#

Subscribable.onSubscribe

onUnsubscribe()#

protected onUnsubscribe(): void;

Defined in: packages/query-core/src/subscribable.ts:27

Returns#

void

Inherited from#

Subscribable.onUnsubscribe

remove()#

remove(query): void;

Defined in: packages/query-core/src/queryCache.ts:208

Destroys the given Query and removes it from the cache, notifying subscribers with a 'removed' event. A no-op if the query is no longer the one currently stored under its hash (e.g. it was already replaced). Used by plugins (e.g. the broadcast client) that mirror removals across QueryCache instances.

Parameters#

query#

Query<any, any, any, any>

Returns#

void

Example#

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

if (query) {
  queryCache.remove(query)
}

subscribe()#

subscribe(listener): () => void;

Defined in: packages/query-core/src/subscribable.ts:8

Parameters#

listener#

QueryCacheListener

Returns#

(): void;

Returns#

void

Inherited from#

Subscribable.subscribe