TanStack React Query 주요 함수 정리표

1. 핵심 Hooks

함수	용도	주요 반환값	주요 옵션
useQuery	데이터 조회 (GET)	data, isLoading, isError, error, isFetching, refetch	queryKey, queryFn, enabled, staleTime, gcTime, retry, select
useMutation	데이터 변경 (POST/PUT/DELETE)	mutate, mutateAsync, isPending, isSuccess, isError, data, reset	mutationFn, onSuccess, onError, onMutate, onSettled
useInfiniteQuery	무한 스크롤/페이지네이션	data, fetchNextPage, fetchPreviousPage, hasNextPage, hasPreviousPage, isFetchingNextPage	queryKey, queryFn, initialPageParam, getNextPageParam, getPreviousPageParam
useQueryClient	QueryClient 인스턴스 접근	queryClient 객체	–
useSuspenseQuery	Suspense와 함께 사용	data (항상 존재)	useQuery와 동일
useQueries	여러 쿼리 동시 실행	쿼리 결과 배열	queries 배열
useIsFetching	현재 fetching 중인 쿼리 수	숫자	queryKey, filters
useIsMutating	현재 mutating 중인 개수	숫자	mutationKey, filters

2. QueryClient 메서드

캐시 관리

메서드	용도	예시
invalidateQueries	쿼리를 stale로 만들고 리페치	queryClient.invalidateQueries({ queryKey: ['todos'] })
refetchQueries	쿼리 즉시 리페치	queryClient.refetchQueries({ queryKey: ['todos'] })
cancelQueries	진행 중인 쿼리 취소	queryClient.cancelQueries({ queryKey: ['todos'] })
removeQueries	쿼리를 캐시에서 제거	queryClient.removeQueries({ queryKey: ['todos'] })
resetQueries	쿼리를 초기 상태로 리셋	queryClient.resetQueries({ queryKey: ['todos'] })
clear	모든 캐시 제거	queryClient.clear()

데이터 조회/설정

메서드	용도	예시
getQueryData	캐시에서 데이터 읽기	queryClient.getQueryData(['todos'])
setQueryData	캐시 데이터 직접 수정	queryClient.setQueryData(['todos'], newData)
getQueryState	쿼리 상태 가져오기	queryClient.getQueryState(['todos'])
setQueryDefaults	쿼리 기본 옵션 설정	queryClient.setQueryDefaults(['todos'], { staleTime: 10000 })
getQueriesData	여러 쿼리 데이터 가져오기	queryClient.getQueriesData({ queryKey: ['todos'] })
setQueriesData	여러 쿼리 데이터 설정	queryClient.setQueriesData({ queryKey: ['todos'] }, updater)

Prefetching

메서드	용도	예시
prefetchQuery	데이터 미리 가져오기 (Promise 반환)	await queryClient.prefetchQuery({ queryKey: ['todos'], queryFn })
prefetchInfiniteQuery	무한 쿼리 미리 가져오기	await queryClient.prefetchInfiniteQuery({ queryKey, queryFn })
ensureQueryData	캐시에 없으면 fetch, 있으면 반환	const data = await queryClient.ensureQueryData({ queryKey, queryFn })

3. 주요 옵션

useQuery 옵션

옵션	타입	기본값	설명
queryKey	unknown[]	필수	쿼리의 고유 키
queryFn	() => Promise<T>	필수	데이터를 가져오는 함수
enabled	boolean	true	false면 쿼리 자동 실행 안 됨
staleTime	number	0	데이터가 fresh 상태로 유지되는 시간 (ms)
gcTime	number	5분	캐시 보관 시간 (구 cacheTime)
retry	boolean | number | function	3	실패 시 재시도 횟수
retryDelay	number | function	지수 증가	재시도 간격
refetchOnMount	boolean | "always"	true	마운트 시 리페치 여부
refetchOnWindowFocus	boolean | "always"	true	윈도우 포커스 시 리페치
refetchOnReconnect	boolean | "always"	true	재연결 시 리페치
refetchInterval	number | false	false	주기적 리페치 간격 (ms)
select	(data: T) => U	undefined	데이터 변환 함수
placeholderData	T | function	undefined	로딩 중 표시할 임시 데이터
initialData	T | function	undefined	초기 데이터 (캐시에 저장됨)

useMutation 옵션

옵션	타입	설명
mutationFn	(variables) => Promise<T>	mutation 실행 함수 (필수)
mutationKey	unknown[]	mutation의 고유 키
onMutate	(variables) => Promise<Context> | Context	mutation 시작 전 실행 (낙관적 업데이트)
onSuccess	(data, variables, context) => void	성공 시 콜백
onError	(error, variables, context) => void	실패 시 콜백
onSettled	(data, error, variables, context) => void	성공/실패 후 항상 실행
retry	boolean | number	재시도 횟수
retryDelay	number | function	재시도 간격

4. 상태 플래그

useQuery 상태

플래그	타입	설명
status	'pending' | 'error' | 'success'	쿼리 상태
fetchStatus	'fetching' | 'paused' | 'idle'	fetch 상태
isLoading	boolean	처음 로딩 중 (isPending && isFetching)
isPending	boolean	아직 데이터가 없음
isSuccess	boolean	성공적으로 데이터 로드
isError	boolean	에러 발생
isFetching	boolean	현재 fetching 중 (백그라운드 포함)
isStale	boolean	데이터가 stale 상태
isPlaceholderData	boolean	placeholder 데이터 표시 중

useMutation 상태

플래그	타입	설명
status	'idle' | 'pending' | 'error' | 'success'	mutation 상태
isIdle	boolean	아직 실행 안 됨
isPending	boolean	실행 중
isSuccess	boolean	성공
isError	boolean	실패
data	T	mutation 결과 데이터
error	Error	에러 객체

5. 유틸리티 함수

함수	용도	예시
hashKey	queryKey를 해시로 변환	import { hashKey } from '@tanstack/react-query'
matchQuery	쿼리 매칭	filters에서 사용
matchMutation	mutation 매칭	filters에서 사용

6. 필터 옵션

invalidateQueries, refetchQueries 등에서 사용:

필터	타입	설명
queryKey	unknown[]	특정 쿼리 키 매칭
exact	boolean	정확히 일치하는 쿼리만
predicate	(query) => boolean	커스텀 매칭 함수
type	'active' | 'inactive' | 'all'	쿼리 타입 필터
stale	boolean	stale 상태 필터
fetchStatus	'fetching' | 'paused' | 'idle'	fetch 상태 필터