Open History to see the last commit
1---
2id: query-invalidation
3title: Query Invalidation
4---
5β
6Waiting for queries to become stale before they are fetched again doesn't always work, especially when you know for a fact that a query's data is out of date because of something the user has done. For that purpose, the `QueryClient` has an `invalidateQueries` method that lets you intelligently mark queries as stale and potentially refetch them too!
7β
8[//]: # 'Example'
9β
10```tsx
11// Invalidate every query in the cache
12queryClient.invalidateQueries()
13// Invalidate every query with a key that starts with `todos`
14queryClient.invalidateQueries({ queryKey: ['todos'] })
15```
16β
17[//]: # 'Example'
18β
19> Note: Where other libraries that use normalized caches would attempt to update local queries with the new data either imperatively or via schema inference, TanStack Query gives you the tools to avoid the manual labor that comes with maintaining normalized caches and instead prescribes **targeted invalidation, background-refetching and ultimately atomic updates**.
20β
21When a query is invalidated with `invalidateQueries`, two things happen:
22β
23- It is marked as stale. This stale state overrides any `staleTime` configurations being used in `useQuery` or related hooks
24- If the query is currently being rendered via `useQuery` or related hooks, it will also be refetched in the background
25β
26## Query Matching with `invalidateQueries`
27β
28When using APIs like `invalidateQueries` and `removeQueries` (and others that support partial query matching), you can match multiple queries by their prefix, or get really specific and match an exact query. For information on the types of filters you can use, please see [Query Filters](./filters.md#query-filters).
29β
30In this example, we can use the `todos` prefix to invalidate any queries that start with `todos` in their query key:
31β
32[//]: # 'Example2'
33β
34```tsx
35import { useQuery, useQueryClient } from '@tanstack/react-query'
36β
37// Get QueryClient from the context
38const queryClient = useQueryClient()
39β
40queryClient.invalidateQueries({ queryKey: ['todos'] })
41β
42// Both queries below will be invalidated
43const todoListQuery = useQuery({
44 queryKey: ['todos'],
45 queryFn: fetchTodoList,
46})
47const todoListQuery = useQuery({
48 queryKey: ['todos', { page: 1 }],
49 queryFn: fetchTodoList,
50})
51```
52β
53[//]: # 'Example2'
54β
55You can even invalidate queries with specific variables by passing a more specific query key to the `invalidateQueries` method:
56β
57[//]: # 'Example3'
58β
59```tsx
60queryClient.invalidateQueries({
61 queryKey: ['todos', { type: 'done' }],
62})
63β
64// The query below will be invalidated
65const todoListQuery = useQuery({
66 queryKey: ['todos', { type: 'done' }],
67 queryFn: fetchTodoList,
68})
69β
70// However, the following query below will NOT be invalidated
71const todoListQuery = useQuery({
72 queryKey: ['todos'],
73 queryFn: fetchTodoList,
74})
75```
76β
77[//]: # 'Example3'
78β
79The `invalidateQueries` API is very flexible, so even if you want to **only** invalidate `todos` queries that don't have any more variables or subkeys, you can pass an `exact: true` option to the `invalidateQueries` method:
80β
81[//]: # 'Example4'
82β
83```tsx
84queryClient.invalidateQueries({
85 queryKey: ['todos'],
86 exact: true,
87})
88β
89// The query below will be invalidated
90const todoListQuery = useQuery({
91 queryKey: ['todos'],
92 queryFn: fetchTodoList,
93})
94β
95// However, the following query below will NOT be invalidated
96const todoListQuery = useQuery({
97 queryKey: ['todos', { type: 'done' }],
98 queryFn: fetchTodoList,
99})
100```
101β
102[//]: # 'Example4'
103β
104If you find yourself wanting **even more** granularity, you can pass a predicate function to the `invalidateQueries` method. This function will receive each `Query` instance from the query cache and allow you to return `true` or `false` for whether you want to invalidate that query:
105β
106[//]: # 'Example5'
107β
108```tsx
109queryClient.invalidateQueries({
110 predicate: (query) =>
111 query.queryKey[0] === 'todos' && query.queryKey[1]?.version >= 10,
112})
113β
114// The query below will be invalidated
115const todoListQuery = useQuery({
116 queryKey: ['todos', { version: 20 }],
117 queryFn: fetchTodoList,
118})
119β
120// The query below will be invalidated
121const todoListQuery = useQuery({
122 queryKey: ['todos', { version: 10 }],
123 queryFn: fetchTodoList,
124})
125β
126// However, the following query below will NOT be invalidated
127const todoListQuery = useQuery({
128 queryKey: ['todos', { version: 5 }],
129 queryFn: fetchTodoList,
130})
131```
132β
133[//]: # 'Example5'