Open History to see the last commit
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 })
89}
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'