84 lines
2.0 KiB
Markdown
84 lines
2.0 KiB
Markdown
---
|
|
id: query-invalidation
|
|
title: Query Invalidation
|
|
---
|
|
|
|
Waiting for queries to become stale is not always enough. After a mutation succeeds, you often know that related cached data is out of date. Use `queryClient.invalidateQueries` to mark matching queries stale and refetch active observers.
|
|
|
|
```ts
|
|
queryClient.invalidateQueries()
|
|
|
|
queryClient.invalidateQueries({
|
|
queryKey: ['todos'],
|
|
})
|
|
```
|
|
|
|
When a query is invalidated:
|
|
|
|
- It is marked stale, overriding any `staleTime`
|
|
- If a matching query is active in a controller, it can refetch in the background
|
|
|
|
## Invalidation from Mutations
|
|
|
|
```ts
|
|
private readonly addTodo = createMutationController(this, {
|
|
mutationFn: addTodo,
|
|
onSuccess: async () => {
|
|
await queryClient.invalidateQueries({ queryKey: ['todos'] })
|
|
},
|
|
})
|
|
```
|
|
|
|
Use this pattern when the mutation result tells you related cached data is stale. The [Pagination example](../examples/pagination) shows invalidation after project mutations.
|
|
|
|
## Query Matching
|
|
|
|
Match a group of queries by prefix:
|
|
|
|
```ts
|
|
queryClient.invalidateQueries({ queryKey: ['projects'] })
|
|
```
|
|
|
|
Both of these query keys match:
|
|
|
|
```ts
|
|
const projectsListKey = ['projects']
|
|
const projectsPageKey = ['projects', 1, 250, false]
|
|
```
|
|
|
|
Use a more specific key when only one slice should be invalidated:
|
|
|
|
```ts
|
|
queryClient.invalidateQueries({
|
|
queryKey: ['projects', this.page],
|
|
})
|
|
```
|
|
|
|
Use `exact: true` to match only the exact key:
|
|
|
|
```ts
|
|
queryClient.invalidateQueries({
|
|
queryKey: ['projects'],
|
|
exact: true,
|
|
})
|
|
```
|
|
|
|
## Manual Cache Updates
|
|
|
|
Invalidation is usually simpler than normalized cache updates. When you do need immediate UI updates, combine targeted cache writes with invalidation:
|
|
|
|
```ts
|
|
queryClient.setQueryData<TodosResponse>(['todos'], (existing) => {
|
|
if (!existing) return existing
|
|
|
|
return {
|
|
...existing,
|
|
items: [...existing.items, createdTodo],
|
|
}
|
|
})
|
|
|
|
await queryClient.invalidateQueries({ queryKey: ['todos'] })
|
|
```
|
|
|
|
For rollback with optimistic updates, see the mutation guide and the [Pagination example](../examples/pagination).
|