Chapter 33: Filters

Core Idea

QueryFilters and MutationFilters are the shared filter-object shapes accepted by cache-wide operations (cancelQueries, removeQueries, refetchQueries, isMutating, etc.) — the same handful of properties (queryKey/mutationKey, exact, status/type flags, predicate) recur across every bulk operation.

Key Concepts

• QueryFilters fields: queryKey (prefix-matched unless exact: true); type: 'active' | 'inactive' | 'all' (default 'all'); stale: boolean (match stale vs. fresh); fetchStatus: 'fetching' | 'paused' | 'idle'; predicate: (query) => boolean as a final catch-all filter, evaluated over every cached query if no other filter narrows the set first.
• MutationFilters fields: mutationKey (prefix-matched unless exact: true); status: MutationStatus; predicate: (mutation) => boolean.
• Utility functions: matchQuery(filters, query) / matchMutation(filters, mutation) — return a boolean for whether a single query/mutation would match a given filter object, useful when building custom cache logic outside the built-in bulk methods.
• These same filters power multiple methods: invalidateQueries, removeQueries, refetchQueries, cancelQueries all accept QueryFilters; isMutating accepts MutationFilters — learning the filter shape once applies everywhere.

Code Examples

// Cancel every query in the cache
await queryClient.cancelQueries()

// Remove all inactive queries whose key starts with 'posts'
queryClient.removeQueries({ queryKey: ['posts'], type: 'inactive' })

// Refetch only active 'posts'-prefixed queries
await queryClient.refetchQueries({ queryKey: ['posts'], type: 'active' })

// Count in-flight mutations matching a predicate
await queryClient.isMutating({ predicate: (m) => m.state.variables?.id === 1 })

• What it demonstrates: the same filter vocabulary (queryKey/type/predicate) reused across different bulk cache operations.

Reference Tables

QueryFilters field	Matches on
queryKey (+ exact)	Key prefix, or exact key with exact: true
type	'active', 'inactive', or 'all' (default)
stale	Stale (true) vs. fresh (false) queries
fetchStatus	'fetching', 'paused', 'idle'
predicate	Arbitrary custom logic, final filter pass

Key Takeaways

1. Learn this one filter shape once — invalidateQueries, removeQueries, refetchQueries, and cancelQueries all take the same QueryFilters object.
2. type: 'active'/'inactive' is the lever for scoping bulk operations to only what's currently rendered vs. only what's sitting idle in cache.
3. matchQuery/matchMutation let you reuse the exact same filter logic outside the built-in bulk methods, e.g. inside a custom QueryCache subscriber.

Connects To

• Query Invalidation: the chapter where QueryFilters matching was first introduced in context.
• QueryClient / QueryCache: where these filter-accepting methods live.