서버에 데이터가 업데이트된 후 새 데이터를 즉시 가져와야 할 때. 예를 들어 사용자가 어떤 폼을 제출하면 자동으로 화면에 보여지는 데이터가 최신으로 업데이트 되면 좋을 것이다.

하지만 추가적인 설정을 해주지 않으면 리액트 쿼리는 이전에 가져온 데이터의 캐시가 만료되지 않았기 때문에 데이터가 변경되었음에도 최신 데이터로 업데이트 하지 않는다.

이때 queryClient.invalidateQueries를 활용할 수 있다.

queryClient.invalidateQueries

React Query에서 특정 쿼리 또는 여러 쿼리를 무효화하고, 필요에 따라 다시 가져오게(refetch) 할 수 있는 메서드

이 메서드는 쿼리 키(queryKey)나 쿼리의 다른 상태/속성을 기반으로 동작을 제어할 수 있다.

기본적으로 조건에 맞는 모든 쿼리가 즉시 무효화되고, 활성 쿼리(active queries)는 백그라운드에서 다시 가져온다.

await queryClient.invalidateQueries(
  {
    queryKey: ['posts'], // 무효화할 대상 쿼리 키
    exact: true,         // 정확히 일치하는 쿼리 키만 무효화
    refetchType: 'active', // 활성 쿼리만 다시 가져옴
  },
  {
    throwOnError: false,  // 오류 발생 시 예외를 던지지 않음
    cancelRefetch: true,  // 기존 요청을 취소하고 새로운 요청 실행
  }
);

1. refetch Type

'active' (기본값)

현재 활성 상태(예: useQuery로 렌더링 중)인 쿼리만 다시 가져온다.

'inactive'

비활성 상태(예: 렌더링되지 않는)인 쿼리만 다시 가져온다.

'all'

활성 상태와 비활성 상태 모두의 쿼리를 다시 가져온다.

'none'

쿼리를 무효화만 하고 다시 가져오지 않는다.

2. 추가 옵션

throwOnError (기본값: false)

쿼리를 다시 가져오는 동안 오류가 발생하면 예외를 던진다.
true로 설정하면 오류가 발생할 때 catch를 통해 처리할 수 있다.

cancelRefetch (기본값: true)

현재 실행 중인 요청이 있을 경우, 해당 요청을 취소한 뒤 새로운 요청을 실행한다.
false로 설정하면 이미 실행 중인 요청이 끝날 때까지 대기하며 새로운 요청을 실행하지 않는다.

---

요약

queryClient.invalidateQueries를 사용하여 특정 키를 사용하는
모든 쿼리가 최신 데이터를 사용하도록 보장할 수 있다.

Tanstack Query 공식문서