Inspect existing queries synchronously
Cache inspection
TanStack · Class
QueryCache
QueryCache stores TanStack Query's query data, metadata, and state. It supports creating, finding, clearing, and observing cached queries, but applications normally use QueryClient instead.
How it works
QueryCache is TanStack Query's storage layer for query data, metadata, and state. It can be constructed with configuration, queried synchronously, cleared, or observed for tracked cache changes, although most application code should use QueryClient instead.
Syntax
new QueryCache(config?: QueryCacheConfig): QueryCache;Parameters
| Name | Type | Description |
|---|---|---|
config | QueryCacheConfig | Optional configuration for cache behavior and callbacks. |
Returns
A QueryCache instance; build returns an existing or newly created Query, while subscription methods provide an unsubscribe function.
Key points
- It is the core storage mechanism behind TanStack Query's cached queries.
- Each contained query contributes its data, metadata, and state to the cache.
- Subscriptions provide notifications for tracked cache updates.
- Typical subscription events include query creation, removal, and updates.
- Construction optionally accepts QueryCacheConfig and returns a QueryCache instance.
- build reuses a matching query or creates and caches one when necessary.
Common mistakes
- Prefer QueryClient for normal application cache operations rather than accessing QueryCache directly.
- A subscriber is not notified when query state is mutated outside the cache's tracked mechanisms.
Example: Create and observe a QueryCache
import { QueryCache } from '@tanstack/query-core'
const queryCache = new QueryCache({
onError: (error, query) => {
console.error(query.queryKey, error)
},
})
const unsubscribe = queryCache.subscribe((event) => {
console.log(event.type)
})
queryCache.clear()
unsubscribe()Creates a cache with an error callback, observes cache events, clears it, and then removes the subscription.
When to use it
Clear all cached queries when resetting application state
Cache lifecycle
Observe tracked additions, removals, and updates
Instrumentation
Create or retrieve Query instances for framework integrations and plugins
Core integrations
Interview questions
QWhat is QueryCache responsible for, and how is it normally accessed?
QueryCache stores the data, metadata, and state for the queries it contains. QueryClient is normally the application-facing interface for working with a specific cache.
Follow-up: How can an application observe cache changes? Use subscribe; it reports safe, tracked updates such as queries being added, removed, or updated.
QHow is a QueryCache created and what operations does it provide?
The constructor accepts an optional QueryCacheConfig object. The cache can then expose operations such as build, find, findAll, clear, and subscribe.
Follow-up: What does build do when the requested query is absent? It creates a Query instance and adds it to the cache.
QWhat does QueryCache.build do?
build checks the supplied query options' queryKey or queryHash. It returns the existing matching Query, or creates and stores a new one when no match exists.
Follow-up: Why might direct QueryCache access be inappropriate for UI code? QueryClient and framework integrations provide the intended higher-level interaction model.
Related
QueryClientQuerySubscribablequeryClient.getQueryCache()