Skip to content
Source
Sign inSign up
TanStack/query
Open History to see the last commit

query-invalidation.md

133 lines4.3 KB

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'