본문으로 건너뛰기

쿼리 키

핵심적으로 TanStack Query는 쿼리 키를 기반으로 쿼리 캐싱을 관리합니다. 쿼리 키는 최상위 수준에서 Array여야 하며, 단일 문자열을 포함한 Array처럼 단순하거나 여러 문자열과 중첩된 객체를 포함한 Array처럼 복잡할 수 있습니다. 쿼리 키를 JSON.stringify를 사용해 직렬화할 수 있고 쿼리 데이터에 고유하기만 하면 사용할 수 있습니다!

단순 쿼리 키​

키의 가장 단순한 형태는 상수 값으로 구성된 배열입니다. 이 형식은 다음에 유용합니다:

  • 일반 목록/인덱스 리소스
  • 비계층적 리소스
// A list of todos
useQuery({ queryKey: ['todos'], ... })

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

변수가 포함된 배열 키​

쿼리의 데이터를 고유하게 설명하는 데 더 많은 정보가 필요한 경우, 문자열과 원하는 수의 직렬화 가능한 객체로 구성된 배열을 사용하여 설명할 수 있습니다. 이는 다음과 같은 경우에 유용합니다:

  • 계층형 또는 중첩된 리소스
    • 항목을 고유하게 식별하기 위해 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' }], ... })

쿼리 키는 결정론적으로 해시됩니다!​

이는 객체 내 키의 순서와 관계없이 다음 쿼리가 모두 동일한 것으로 간주된다는 의미입니다:

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, status], ...})
useQuery({ queryKey: ['todos', undefined, page, status], ...})

쿼리 함수가 변수에 의존하는 경우 해당 변수를 쿼리 키에 포함하세요​

쿼리 키는 가져오는 데이터를 고유하게 설명하므로, 쿼리 함수에서 사용하는 변수 중 변경되는 모든 변수를 포함해야 합니다. 예를 들면 다음과 같습니다:

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

쿼리 키는 쿼리 함수의 의존성으로 작동한다는 점에 유의하세요. 쿼리 키에 종속 변수를 추가하면 쿼리가 서로 독립적으로 캐시되며, 변수가 변경될 때마다 쿼리가 자동으로 다시 가져와집니다(staleTime 설정에 따라 달라짐). 자세한 내용과 예제는 exhaustive-deps 섹션을 참조하세요.

추가 자료​

대규모 애플리케이션에서 쿼리 키를 구성하는 방법에 관한 팁은 효과적인 React Query 키를 살펴보고, 다음에서 제공하는 Query Key Factory Package를 확인하세요. 커뮤니티 리소스.