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: QueryCacheConfig): 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: QueryClient,
options: WithRequired<QueryOptions<TQueryFnData, TError, TData, TQueryKey, never>, "queryKey">,
state?: QueryState<TData, TError>): 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#
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:228
Removes all queries from the cache.
Returns#
void
Example#
const queryCache = queryClient.getQueryCache()
queryCache.clear()
find()#
find<TQueryFnData, TError, TData>(filters: WithRequired<QueryFilters<readonly unknown[]>, "queryKey">):
| Query<TQueryFnData, TError, TData, readonly unknown[]>
| undefined;
Defined in: packages/query-core/src/queryCache.ts:295
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#
Example#
const queryCache = queryClient.getQueryCache()
const query = queryCache.find({ queryKey: ['posts'] })
findAll()#
findAll(filters: QueryFilters<any>): Query<unknown, Error, unknown, readonly unknown[]>[];
Defined in: packages/query-core/src/queryCache.ts:320
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#
Example#
const queryCache = queryClient.getQueryCache()
const queries = queryCache.findAll({ queryKey: ['posts'] })
get()#
get<TQueryFnData, TError, TData, TQueryKey>(queryHash: string):
| Query<TQueryFnData, TError, TData, TQueryKey>
| undefined;
Defined in: packages/query-core/src/queryCache.ts:250
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:273
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: Query<any, any, any, any>): 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: QueryCacheListener): () => void;
Defined in: packages/query-core/src/subscribable.ts:8
Parameters#
listener#
QueryCacheListener
Returns#
(): void;
Returns#
void
Inherited from#
Subscribable.subscribe