> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/tanstack/query/llms.txt
> Use this file to discover all available pages before exploring further.
# QueryCache
> The QueryCache stores and manages all Query instances.
## Overview
The `QueryCache` is responsible for storing and managing all `Query` instances. It provides methods to build, access, and manipulate queries, and emits events when queries are added, removed, or updated.
## Constructor
```typescript theme={null}
const queryCache = new QueryCache(config?: QueryCacheConfig)
```
Configuration options for the QueryCache
Global error handler called when any query errors
Global success handler called when any query succeeds
Global settled handler called when any query completes (success or error)
**Example:**
```typescript theme={null}
const queryCache = new QueryCache({
onError: (error, query) => {
console.error('Query error:', error, 'Query key:', query.queryKey)
},
onSuccess: (data, query) => {
console.log('Query success:', query.queryKey)
},
})
```
## Methods
### build()
Builds or retrieves a query instance.
```typescript theme={null}
const query = queryCache.build(
client: QueryClient,
options: QueryOptions,
state?: QueryState
): Query
```
The QueryClient instance
Query options including queryKey
Initial state for the query
**Returns:** A `Query` instance
If a query with the same hash already exists, it returns the existing query. Otherwise, creates a new one.
### add()
Adds a query to the cache.
```typescript theme={null}
queryCache.add(query: Query): void
```
The query instance to add
This method is typically called internally by the `build()` method.
### remove()
Removes a query from the cache and destroys it.
```typescript theme={null}
queryCache.remove(query: Query): void
```
The query instance to remove
### clear()
Removes all queries from the cache.
```typescript theme={null}
queryCache.clear(): void
```
**Example:**
```typescript theme={null}
queryCache.clear()
```
### get()
Retrieves a query from the cache by its hash.
```typescript theme={null}
const query = queryCache.get(
queryHash: string
): Query | undefined
```
The hash of the query to retrieve
**Returns:** The `Query` instance or `undefined` if not found
**Example:**
```typescript theme={null}
const query = queryCache.get('["\'todos\'"]')
```
### getAll()
Returns all queries in the cache.
```typescript theme={null}
const queries = queryCache.getAll(): Array
```
**Returns:** Array of all `Query` instances
**Example:**
```typescript theme={null}
const allQueries = queryCache.getAll()
console.log(`Total queries: ${allQueries.length}`)
```
### find()
Finds a single query that matches the filters.
```typescript theme={null}
const query = queryCache.find(
filters: QueryFilters
): Query | undefined
```
Filters to match queries
Query key to filter by
Match query key exactly. Defaults to `true` for `find()`.
**Returns:** The first matching `Query` or `undefined`
**Example:**
```typescript theme={null}
const todoQuery = queryCache.find({ queryKey: ['todos', 1], exact: true })
```
### findAll()
Finds all queries that match the filters.
```typescript theme={null}
const queries = queryCache.findAll(filters?: QueryFilters): Array
```
Filters to match queries
Filter by query key (partial match by default)
Match query key exactly. Defaults to `false`.
Filter by query type
Filter by stale status
Filter by fetch status
Custom predicate function
**Returns:** Array of matching `Query` instances
**Example:**
```typescript theme={null}
// Find all queries with 'todos' in the key
const todoQueries = queryCache.findAll({ queryKey: ['todos'] })
// Find all stale queries
const staleQueries = queryCache.findAll({ stale: true })
// Find all fetching queries
const fetchingQueries = queryCache.findAll({ fetchStatus: 'fetching' })
```
### notify()
Notifies all subscribers of a cache event.
```typescript theme={null}
queryCache.notify(event: QueryCacheNotifyEvent): void
```
The event to notify subscribers about
Emitted when a query is added to the cache
Emitted when a query is removed from the cache
Emitted when a query is updated
Emitted when an observer is added to a query
Emitted when an observer is removed from a query
Emitted when observer results are updated
Emitted when observer options are updated
### subscribe()
Subscribes to cache events.
```typescript theme={null}
const unsubscribe = queryCache.subscribe(
listener: (event: QueryCacheNotifyEvent) => void
): () => void
```
Callback function to handle cache events
**Returns:** Function to unsubscribe
**Example:**
```typescript theme={null}
const unsubscribe = queryCache.subscribe((event) => {
if (event.type === 'added') {
console.log('Query added:', event.query.queryKey)
}
if (event.type === 'updated') {
console.log('Query updated:', event.query.queryKey)
}
})
// Later, unsubscribe
unsubscribe()
```
### onFocus()
Called when the window regains focus. Triggers focus events on all queries.
```typescript theme={null}
queryCache.onFocus(): void
```
This method is typically called automatically by the QueryClient.
### onOnline()
Called when the network comes back online. Triggers online events on all queries.
```typescript theme={null}
queryCache.onOnline(): void
```
This method is typically called automatically by the QueryClient.
## Events
The QueryCache emits the following events:
* `added` - When a query is added to the cache
* `removed` - When a query is removed from the cache
* `updated` - When a query's state changes
* `observerAdded` - When an observer subscribes to a query
* `observerRemoved` - When an observer unsubscribes from a query
* `observerResultsUpdated` - When observer results are updated
* `observerOptionsUpdated` - When observer options are updated
## Usage with QueryClient
```typescript theme={null}
const queryCache = new QueryCache()
const queryClient = new QueryClient({
queryCache,
})
```