[TanStack Query] TanStack Query(React Query)의 stale time과 cache time은 무엇일까?

 TanStack Query(React Query)를 사용하다보면 stale time과 cache time을 직접 조작할 수 있다는 것을 알 수 있습니다. 하지만 막상 stale time과 cache time을 직접 건드릴 일이 생기면 각각 어떤 차이가 있고 어떤 기능을 수행하는지 잘 와닿지 않는 것도 사실입니다. 오늘은 두 가지를 정리해보고자 합니다.

본 포스팅은 아래 TanStack Query의 `useQuery` 관련 공식 문서를 정리한 내용입니다.

useQuery | TanStack Query React Docs

우리는 stale time과 cache time을 명확하게 이해하기 위해서는 TanStack Query의 라이프 사이클을 알 필요가 있습니다.

---

TanStack Query 라이프 사이클 상태

fresh: 새롭게 추가된 쿼리, 만료되지 않은 쿼리, 신선한 데이터를 가지고 있음을 의미합니다.

• component mount, update, window focus 등의 상황이 발생해도 refetch하지 않음.
• TanStack Query에서는 기본 stale time이 0으로 설정되어 있기 때문에 쿼리 호출이 끝나면 fresh -> stale로 상태가 곧바로 변경됩니다.
• stale time은 쿼리의 만료 시간, 다시 말하여 데이터가 신선하다고 판단되는 시간이며 이 시간이 지나 stale 상태가 되면 refetch의 대상이 됩니다.

fetching: 서버로 요청 중인 쿼리를 의미합니다.

 

stale: 만료된 쿼리, 신선하지 않은 데이터를 가지고 있음을 의미합니다.

• component mount, update, window focus 등의 상황이 발생하면 refetch됩니다.

inactive: 비활성화된 쿼리를 의미합니다.

• active 쿼리가 하나도 존재하지 않는 쿼리입니다.
• inactive된 이후 cacheTime 동안 캐시 데이터를 유지합니다.
• cacheTime 이후 가비지 컬렉터(GC)에 의하여 제거됩니다.

 

TanStack Query 라이프 사이클

• A 쿼리 인스턴스가 mount 됩니다.
• 네트워크에서 data fetch를 진행하고 A라는 query key로 캐싱합니다.
• 해당 쿼리는 staleTime동안 fresh한 상태로 유지되며, 이후로는 stale 상태로 변경됩니다.
• A 쿼리 인스턴스가 unmount 됩니다.
•  캐시는 cacheTime만큼 유지되다가 GC에 의하여 제거됩니다.

---

 

stale time과 cache time이 각각 연관된 상태, 그리고 라이프 사이클의 위치가 다름을 파악할 수 있습니다. 즉, cache time은 가비지 컬렉터에 의하여 수집되지 않을 시간을 의미합니다. refetch를 방지하는 시간은 stale time임을 알 수 있죠. 각각 다시 한 번 정리하면 아래와 같습니다.

 

stale time

• fresh -> stale 상태로 변경되는데 걸리는 시간입니다.
• fresh 상태에서는 refetch가 발생하지 않습니다.
• 데이터가 fetch되고 난 뒤, staleTime이 지나지 않았으면 추가적인 data fetch는 발생하지 않습니다.

 

cache time

• inactive 상태일 때 데이터를 캐싱해두는 시간입니다.
• 쿼리 인스턴스가 unmount되면 inactive 상태로 변경되고, 데이터는 cacheTime만큼 캐싱됩니다.
• cacheTime이 지나면 가비지 콜렉터가 이를 제거합니다.

 

여담으로 많은 사용자들이 stale time과 cache time의 명칭때문에 수행하는 역할에 대한 혼란을 겪는 것을 보며, TanStack Query에서 버전 5부터 cacheTime의 명칭은 gcTime으로 변경되었습니다.