86 lines
1.8 KiB
Markdown
86 lines
1.8 KiB
Markdown
---
|
|
id: query-keys
|
|
title: Query Keys
|
|
---
|
|
|
|
TanStack Query manages caching by query key. Query keys must be arrays at the top level, and they should uniquely describe the data returned by the query function.
|
|
|
|
## Simple Keys
|
|
|
|
Use simple keys for list resources or non-hierarchical data:
|
|
|
|
```ts
|
|
createQueryController(this, {
|
|
queryKey: ['todos'],
|
|
queryFn: fetchTodos,
|
|
})
|
|
|
|
createQueryController(this, {
|
|
queryKey: ['settings'],
|
|
queryFn: fetchSettings,
|
|
})
|
|
```
|
|
|
|
## Keys with Variables
|
|
|
|
Include variables when they change what the query fetches:
|
|
|
|
```ts
|
|
createQueryController(this, () => ({
|
|
queryKey: ['todo', this.todoId],
|
|
queryFn: () => fetchTodo(this.todoId),
|
|
}))
|
|
|
|
createQueryController(this, () => ({
|
|
queryKey: ['projects', { page: this.page, filter: this.filter }],
|
|
queryFn: () => fetchProjects({ page: this.page, filter: this.filter }),
|
|
}))
|
|
```
|
|
|
|
The pagination example uses a key shaped like this:
|
|
|
|
```ts
|
|
type ProjectsQueryKey = readonly ['projects', number, number, boolean]
|
|
|
|
function projectsQueryKey(
|
|
page: number,
|
|
delayMs: number,
|
|
forceError: boolean,
|
|
): ProjectsQueryKey {
|
|
return ['projects', page, delayMs, forceError] as const
|
|
}
|
|
```
|
|
|
|
## Deterministic Hashing
|
|
|
|
Object key order does not matter inside a query key:
|
|
|
|
```ts
|
|
const keyA = ['todos', { status, page }]
|
|
const keyB = ['todos', { page, status }]
|
|
```
|
|
|
|
Array item order does matter:
|
|
|
|
```ts
|
|
const keyA = ['todos', status, page]
|
|
const keyB = ['todos', page, status]
|
|
```
|
|
|
|
## Query Keys as Dependencies
|
|
|
|
If your query function reads a reactive host property, include that value in the query key:
|
|
|
|
```ts
|
|
class UserTodos extends LitElement {
|
|
userId = ''
|
|
|
|
private readonly todos = createQueryController(this, () => ({
|
|
queryKey: ['todos', this.userId],
|
|
queryFn: () => fetchTodos(this.userId),
|
|
}))
|
|
}
|
|
```
|
|
|
|
This lets Lit Query cache each user's todos separately and refetch when the host state changes.
|