ragflow/web/.agents/skills/tanstack-query-best-practices/rules/qk-hierarchical-organization.md

qk-hierarchical-organization: Organize Keys Hierarchically

Priority: CRITICAL

Explanation

Structure query keys from general to specific: entity type first, then ID, then modifiers/filters. This enables efficient invalidation at any level of specificity and creates predictable cache organization.

Bad Example

// Flat, inconsistent key structures
const { data: todos } = useQuery({
  queryKey: ['all-todos-list'],
  queryFn: fetchTodos,
})

const { data: todo } = useQuery({
  queryKey: ['single-todo-5'],
  queryFn: () => fetchTodo(5),
})

const { data: comments } = useQuery({
  queryKey: ['todo-5-comments'],
  queryFn: () => fetchTodoComments(5),
})

// Can't easily invalidate all todo-related queries

Good Example

// Hierarchical: entity → id → sub-resource → filters
const { data: todos } = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
})

const { data: todo } = useQuery({
  queryKey: ['todos', 5],
  queryFn: () => fetchTodo(5),
})

const { data: comments } = useQuery({
  queryKey: ['todos', 5, 'comments'],
  queryFn: () => fetchTodoComments(5),
})

const { data: filteredTodos } = useQuery({
  queryKey: ['todos', { status: 'done', page: 1 }],
  queryFn: () => fetchTodos({ status: 'done', page: 1 }),
})

// Now we can invalidate at any level:
queryClient.invalidateQueries({ queryKey: ['todos'] })        // All todos
queryClient.invalidateQueries({ queryKey: ['todos', 5] })     // Todo 5 and its sub-resources
queryClient.invalidateQueries({ queryKey: ['todos', 5, 'comments'] }) // Just comments

Recommended Hierarchy Pattern

['entity']                              // List
['entity', id]                          // Single item
['entity', id, 'sub-resource']          // Related data
['entity', { filters }]                 // Filtered list
['entity', id, 'sub-resource', { filters }] // Filtered sub-resource

Context

• Essential for applications with related data
• Enables efficient cache management
• Works with prefix-based invalidation
• Consider using query key factories (see qk-factory-pattern) for consistency