Query Keys

TanStack Query의 핵심은 쿼리 키를 기반으로 쿼리 캐싱을 관리하는 것이다. 쿼리 키는 반드시 최상위 레벨에서 배열이어야 한다. ['todos']처럼 단일 문자열을 가진 간단한 배열일 수도 있고, 여러 문자열과 중첩된 객체를 포함하는 복잡한 배열일 수도 있다. 

 

쿼리 키가 JSON.stringfy로 직렬화 가능하고 해당 쿼리의 데이터를 고유하게 식별할 수만 있다면 어떤 형태든 사용할 수 있다.

 

Simple Query Keys

가장 간단한 형태의 키는 상수 값으로만 구성된 배열이다. 이 형식은 다음과 같은 경우에 유용하다.

• 일반적인 목록/인덱스 리소스
• 계층 구조가 없는 리소스

// A list of todos
useQuery({ queryKey: ['todos'], ... })

// Something else, whatever !
useQuery({ queryKey: ['something', 'special'], ... })

 

Array Keys with variables

쿼리가 데이터를 고유하게 식별하기 위해 더 많은 정보가 필요할 때, 문자열과 함께 직렬화 가능한 객체를 포함한 여러 값을 배열에 넣을 수 있다. 이 방식은 다음과 같은 경우에 유용하다.

• 계층적이거나 중첩된 리소스
  • 항목을 고유하게 식별하기 위해 ID, 인덱스 또는 기타 기본값을 전달하는 것이 일반적이다.
• 추가 파라미터가 있는 쿼리
  • 추가 옵션이 담긴 객체를 전달하는 것이 일반적이다.

// An individual todo
useQuery({ queryKey: ['todo', 5], ... })

// An individual todo in a "preview" format
useQuery({ queryKey: ['todo', 5, { preview: true }], ... })

// A list of todos that are "done"
useQuery({ queryKey: ['todos', { type: 'done' }], ... })

 

Query Keys are hashed deterministically!

이는 객체 내부의 키 순서와 상관없이 다음 쿼리들이 모두 동일한 것으로 간주된다는 의미이다.

useQuery({ queryKey: ['todos', { status, page }], ... })
useQuery({ queryKey: ['todos', { page, status }], ... })
useQuery({ queryKey: ['todos', { page, status, other: undefined }], ... })

 

하지만, 배열에서는 요소의 순서가 중요하기 때문에 다음 쿼리 키들은 동일하지 않은 것으로 간주된다.

useQuery({ queryKey: ['todos', status, page], ... })
useQuery({ queryKey: ['todos', page, statue], ... })
useQuery({ queryKey: ['todos', undefined, page, status], ...})

 

쿼리 함수가 변수에 의존한다면, 반드시 쿼리 키에 포함해야 한다.

쿼리 키는 가져올 데이터를 고유하게 식별하므로, 쿼리 함수(queryFn)에서 사용하는 변수가 변경될 경우 해당 변수를 쿼리 키에 반드시 포함해야 한다.

function Todos({ todoId }) {
  const result = useQuery({
    queryKey: ['todos', todoId],
    queryFn: () => fetchTodoById(todoId),
  })
}

 

쿼리 키는 쿼리 함수의 의존성처럼 작동한다. 의존하는 변수를 쿼리 키에 추가하면, 해당 변수 값마다 쿼리가 독립적으로 캐시된다. 또한 변수 값이 변경될 때마다 쿼리가 자동으로 다시 실행된다. (staleTime 설정에 따라 다르다.)

 

https://tanstack.com/query/latest/docs/framework/react/guides/query-keys

Query Keys | TanStack Query React Docs