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

query-keys.md

103 lines3.3 KB

1---
2id: query-keys
3title: Query Keys
4---
5​
6At its core, TanStack Query manages query caching for you based on query keys. Query keys have to be an Array at the top level, and can be as simple as an Array with a single string, or as complex as an array of many strings and nested objects. As long as the query key is serializable, and **unique to the query's data**, you can use it!
7​
8## Simple Query Keys
9​
10The simplest form of a key is an array with constants values. This format is useful for:
11​
12- Generic List/Index resources
13- Non-hierarchical resources
14​
15[//]: # 'Example'
16​
17```tsx
18// A list of todos
19useQuery({ queryKey: ['todos'], ... })
20​
21// Something else, whatever!
22useQuery({ queryKey: ['something', 'special'], ... })
23```
24​
25[//]: # 'Example'
26​
27## Array Keys with variables
28​
29When a query needs more information to uniquely describe its data, you can use an array with a string and any number of serializable objects to describe it. This is useful for:
30​
31- Hierarchical or nested resources
32 - It's common to pass an ID, index, or other primitive to uniquely identify the item
33- Queries with additional parameters
34 - It's common to pass an object of additional options
35​
36[//]: # 'Example2'
37​
38```tsx
39// An individual todo
40useQuery({ queryKey: ['todo', 5], ... })
41​
42// An individual todo in a "preview" format
43useQuery({ queryKey: ['todo', 5, { preview: true }], ...})
44​
45// A list of todos that are "done"
46useQuery({ queryKey: ['todos', { type: 'done' }], ... })
47```
48​
49[//]: # 'Example2'
50​
51## Query Keys are hashed deterministically!
52​
53This means that no matter the order of keys in objects, all of the following queries are considered equal:
54​
55[//]: # 'Example3'
56​
57```tsx
58useQuery({ queryKey: ['todos', { status, page }], ... })
59useQuery({ queryKey: ['todos', { page, status }], ...})
60useQuery({ queryKey: ['todos', { page, status, other: undefined }], ... })
61```
62​
63[//]: # 'Example3'
64​
65The following query keys, however, are not equal. Array item order matters!
66​
67[//]: # 'Example4'
68​
69```tsx
70useQuery({ queryKey: ['todos', status, page], ... })
71useQuery({ queryKey: ['todos', page, status], ...})
72useQuery({ queryKey: ['todos', undefined, page, status], ...})
73```
74​
75[//]: # 'Example4'
76​
77## If your query function depends on a variable, include it in your query key
78​
79Since query keys uniquely describe the data they are fetching, they should include any variables you use in your query function that **change**. For example:
80​
81[//]: # 'Example5'
82​
83```tsx
84function Todos({ todoId }) {
85 const result = useQuery({
86 queryKey: ['todos', todoId],
87 queryFn: () => fetchTodoById(todoId),
88 })
90```
91​
92[//]: # 'Example5'
93​
94Note that query keys act as dependencies for your query functions. Adding dependent variables to your query key will ensure that queries are cached independently, and that any time a variable changes, _queries will be refetched automatically_ (depending on your `staleTime` settings). See the [exhaustive-deps](../../../eslint/exhaustive-deps.md) section for more information and examples.
95​
96[//]: # 'Materials'
97​
98## Further reading
99​
100For tips on organizing Query Keys in larger applications, have a look at [Effective React Query Keys](../community/tkdodos-blog.md#8-effective-react-query-keys) and check the [Query Key Factory Package](../community/community-projects.md#query-key-factory) from
101the Community Resources.
102​
103[//]: # 'Materials'