본문으로 건너뛰기

폴링

refetchInterval은 타이머에 따라 쿼리를 다시 가져오게 합니다. 밀리초 단위의 숫자로 설정하면 활성 observer가 하나 이상 있는 동안 쿼리가 N ms마다 실행됩니다:

useQuery({
  queryKey: ['prices'],
  queryFn: fetchPrices,
  refetchInterval: 5_000, // every 5 seconds
})

폴링은 staleTime과 독립적입니다. 쿼리가 fresh 상태여도 일정에 따라 폴링할 수 있습니다. staleTime이 다른 다시 가져오기 동작과 상호작용하는 방식은 중요한 기본값을 참조하세요. refetchInterval은 freshness와 관계없이 자체 주기에 따라 실행됩니다.

쿼리 상태에 맞게 간격 조정하기​

현재 쿼리에서 간격을 계산하려면 숫자 대신 함수를 전달합니다. 함수는 Query 객체를 받고 ms 단위의 숫자 또는 폴링을 중지하려면 false를 반환해야 합니다:

useQuery({
  queryKey: ['job', jobId],
  queryFn: () => fetchJobStatus(jobId),
  refetchInterval: (query) => {
    // Stop polling once the job finishes
    if (query.state.data?.status === 'complete') return false
    return 2_000
  },
})

false를 반환하면 인터벌 타이머가 해제됩니다. 쿼리 결과가 변경되어 함수가 다시 양수를 반환하게 되면 폴링이 자동으로 재개됩니다.

백그라운드 폴링​

기본적으로 브라우저 탭이 포커스를 잃으면 폴링이 일시 중지됩니다. 사용자가 다른 탭에 있는 동안에도 데이터를 최신 상태로 유지해야 하는 대시보드나 기타 인터페이스에서는 이 동작을 비활성화합니다:

useQuery({
  queryKey: ['portfolio'],
  queryFn: fetchPortfolio,
  refetchInterval: 30_000,
  refetchIntervalInBackground: true,
})

폴링 일시 중지​

폴링 실행 시점을 제어하려면 refetchInterval에 함수를 전달하고 컴포넌트 상태를 클로저로 캡처합니다:

useQuery({
  queryKey: ['prices', tokenAddress],
  queryFn: () => fetchPrice(tokenAddress),
  refetchInterval: () => {
    if (!tokenAddress || isPaused) return false
    return 15_000
  },
})

오프라인 지원을 통한 폴링​

TanStack Query는 브라우저의 online 및 offline 이벤트를 수신하여 연결 상태를 감지합니다. 이러한 이벤트가 안정적으로 발생하지 않는 환경(Electron, 일부 임베디드 WebViews)에서는 연결 상태 확인을 건너뛰도록 networkMode: 'always'를 설정합니다:

useQuery({
  queryKey: ['chainStatus'],
  queryFn: fetchChainStatus,
  refetchInterval: 10_000,
  networkMode: 'always',
})

네트워크 모드에 대한 자세한 내용은 네트워크 모드를 참조하세요.

중복 제거에 관한 참고 사항​

각 QueryObserver(refetchInterval과 함께 useQuery를 사용하는 각 컴포넌트)은 자체 타이머를 실행합니다. refetchInterval: 5000를 사용하여 동일한 키를 구독하는 두 컴포넌트는 각각 5초마다 타이머를 작동시킵니다. 중복 제거되는 것은 동시에 진행 중인 가져오기입니다. 두 타이머가 동시에 작동하면 네트워크 요청은 하나만 전송됩니다. 타이머는 observer 수준이고, 중복 제거는 쿼리 수준입니다.

브라우저가 아닌 환경​

React Native 같은 비브라우저 런타임에서는 표준 online/offline 및 포커스 이벤트를 사용할 수 없습니다. React Native 가이드에서는 focusManager 및 onlineManager를 네이티브 앱 상태 API에 연결하는 방법을 다룹니다.