Find cached queries matching a key or other criteria
Cache inspection
TanStack · Function
matchQuery
Tests whether a Query satisfies the supplied QueryFilters. It returns true only when every provided filter matches.
How it works
matchQuery evaluates one Query against a QueryFilters object. Every supplied filter must match; omitted filters do not constrain the result, and the function returns a boolean.
Syntax
function matchQuery(filters: QueryFilters, query: Query<any, any, any, any>): boolean;Parameters
| Name | Type | Description |
|---|---|---|
filters | QueryFilters | Filters used to test the query; supported properties include exact, fetchStatus, predicate, queryKey, stale, and type. |
query | Query<any, any, any, any> | The query to evaluate against the filters. |
Returns
boolean — true if the query matches every specified filter.
Key points
- Use matchQuery to evaluate a Query against a QueryFilters object.
- The exact filter requires an exact query-key match.
- fetchStatus can select queries that are fetching, paused, or idle.
- predicate provides custom matching logic based on the Query object.
- queryKey restricts matching to a specified key or tuple prefix.
- stale selects whether stale queries should match.
- type limits matching to active, inactive, or all queries.
Common mistakes
- All supplied filters are combined as required conditions; leaving a filter out removes that condition.
Example: Check a query key
import { matchQuery } from '@tanstack/query-core'
const isMatch = matchQuery(
{ queryKey: ['posts'], exact: false },
query,
)
console.log(isMatch)Pass a QueryFilters object and a Query instance to test whether the query satisfies every specified filter.
When to use it
Decide whether an individual query qualifies for an operation
Selective cache operations
Combine built-in filters with a predicate for application-specific matching
Custom selection
Interview questions
QWhat does matchQuery do?
matchQuery accepts QueryFilters and a Query, then returns true only when the query satisfies every specified filter. Unspecified filters are ignored.
Follow-up: How can you inspect a cache for matches? Retrieve all queries from the QueryCache and filter them with matchQuery.
QHow do queryKey and exact affect matching?
Set queryKey in the filters to test the query key. The exact option controls whether the key must match exactly rather than using a matching prefix.
Follow-up: What other query-selection dimensions are available? Use type, stale, fetchStatus, or predicate filters.
QWhat are the inputs and output of matchQuery?
The function returns a boolean indicating whether the query matches all requested criteria. Its second argument is a Query instance, not a query key or query data object.
Follow-up: How would you select only active stale queries? Provide type: 'active' and stale: true in the filters.
Related
QueryFiltersQueryQueryCachequeryClient.getQueryCache