snapshot of https://github.com/TanStack/query.git (main, 2026-09-16; blobs > 131072B omitted)

docs/framework/lit/guides/query-keys.md

@@ -0,0 +1,85 @@
+---
+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.