[react-query v5] 공식 문서 번역 - useQuery

프로젝트로 react-query 의 v5버전을 쓰게 되었다.

근데 공식 번역이 없음

 

영어 문서인 채로 읽는 것이 가장 좋지만... 빠른 이해를 위해 한번 번역해 기록해 두기로

 

---

https://tanstack.com/query/v5/docs/framework/react/reference/useQuery

useQuery | TanStack Query React Docs

 

 

 

 

파라미터1 (옵션)

queryKey: unknown[]

필수
이 쿼리에 사용할 쿼리 키입니다.
쿼리 키는 안정적인 해시로 변환됩니다. 자세한 내용은 Query Keys를 참고하세요.
이 키가 변경되면 쿼리는 자동으로 업데이트됩니다(단, enabled가 false로 설정되지 않은 경우).

---

queryFn: (context: QueryFunctionContext) => Promise<TData>

필수 (기본 쿼리 함수가 정의되지 않은 경우)
쿼리가 데이터를 요청할 때 사용할 함수입니다.
QueryFunctionContext를 인자로 받습니다.
반환값은 데이터가 해결되거나 오류가 발생하는 Promise여야 합니다. 반환 데이터는 undefined일 수 없습니다.

---

enabled: boolean | (query: Query) => boolean

자동 실행을 비활성화하려면 false로 설정하세요.
종속 쿼리(Dependent Queries)에서 사용할 수 있습니다.

---

networkMode: 'online' | 'always' | 'offlineFirst'

선택 사항
기본값은 'online'입니다.
자세한 내용은 Network Mode를 참고하세요.

---

retry: boolean | number | (failureCount: number, error: TError) => boolean

기본값: 클라이언트에서는 3, 서버에서는 0

• false: 실패한 쿼리를 기본적으로 재시도하지 않습니다.
• true: 실패한 쿼리를 무한히 재시도합니다.
• 숫자: 예를 들어 3으로 설정하면, 실패한 쿼리를 세 번 재시도합니다.

---

retryOnMount: boolean

기본값: true
false로 설정하면 오류가 있는 경우 마운트 시 쿼리를 재시도하지 않습니다.

---

retryDelay: number | (retryAttempt: number, error: TError) => number

다음 재시도까지의 지연 시간을 밀리초 단위로 설정합니다.

• 예: attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)는 지수적 백오프를 적용합니다.
• 예: attempt => attempt * 1000는 선형 백오프를 적용합니다.

---

staleTime: number | ((query: Query) => number)

선택 사항
기본값: 0
데이터가 오래되었다고 간주되기 전의 시간(밀리초 단위)입니다.

• Infinity로 설정하면 데이터는 절대 오래되지 않습니다.
• 함수로 설정하면 쿼리를 사용하여 staleTime을 계산합니다.

---

gcTime: number | Infinity

기본값: 5분 (SSR 시 Infinity)
미사용 또는 비활성 캐시 데이터가 메모리에 남아 있는 시간(밀리초 단위)입니다.

• Infinity로 설정하면 가비지 수집을 비활성화합니다.
  참고: 최대 허용 시간은 약 24일입니다.

---

queryKeyHashFn: (queryKey: QueryKey) => string

선택 사항
지정된 경우, 쿼리 키를 해시 문자열로 변환하는 데 사용됩니다.

---

refetchInterval: number | false | ((query: Query) => number | false | undefined)

선택 사항

• 숫자: 지정된 주기(밀리초)마다 쿼리를 다시 가져옵니다.
• 함수: 함수가 쿼리를 사용하여 주기를 계산합니다.

---

refetchIntervalInBackground: boolean

선택 사항
true로 설정하면, 탭/창이 백그라운드에 있을 때도 쿼리를 계속 다시 가져옵니다.

---

refetchOnMount: boolean | "always" | ((query: Query) => boolean | "always")

선택 사항
기본값: true

• true: 데이터가 오래되었으면 마운트 시 쿼리를 다시 가져옵니다.
• false: 마운트 시 쿼리를 다시 가져오지 않습니다.
• "always": 항상 마운트 시 쿼리를 다시 가져옵니다.

---

refetchOnWindowFocus: boolean | "always" | ((query: Query) => boolean | "always")

선택 사항
기본값: true

• true: 데이터가 오래되었으면 창 포커스 시 쿼리를 다시 가져옵니다.
• false: 창 포커스 시 쿼리를 다시 가져오지 않습니다.
• "always": 항상 창 포커스 시 쿼리를 다시 가져옵니다.

---

refetchOnReconnect: boolean | "always" | ((query: Query) => boolean | "always")

선택 사항
기본값: true

• true: 데이터가 오래되었으면 다시 연결 시 쿼리를 다시 가져옵니다.
• false: 다시 연결 시 쿼리를 다시 가져오지 않습니다.
• "always": 항상 다시 연결 시 쿼리를 다시 가져옵니다.

---

notifyOnChangeProps: string[] | "all" | (() => string[] | "all" | undefined)

선택 사항
특정 속성이 변경될 때만 컴포넌트를 다시 렌더링합니다.

• 예: ['data', 'error']로 설정하면 data나 error가 변경될 때만 렌더링합니다.
• "all"로 설정하면 스마트 추적을 비활성화하고 쿼리가 업데이트될 때마다 다시 렌더링합니다.

---

select: (data: TData) => unknown

선택 사항

• 이 옵션은 쿼리 함수에서 반환된 데이터의 일부를 변환하거나 선택하는 데 사용됩니다.
• 반환되는 데이터 값에 영향을 주지만, 쿼리 캐시에 저장되는 데이터에는 영향을 주지 않습니다.
• select 함수는 데이터가 변경되거나 함수 참조가 변경될 때만 실행됩니다.
• 최적화를 위해, useCallback으로 함수를 감싸는 것이 권장됩니다.

---

initialData: TData | () => TData

선택 사항

• 설정된 경우, 이 값이 쿼리 캐시의 초기 데이터로 사용됩니다. (쿼리가 생성되거나 캐시되지 않은 경우에만)
• 함수로 설정된 경우, 공유/루트 쿼리 초기화 중 한 번 호출되며, initialData를 동기적으로 반환해야 합니다.
• 초기 데이터는 기본적으로 오래된(stale) 상태로 간주되지만, staleTime이 설정된 경우는 예외입니다.
• initialData는 캐시에 저장됩니다.

---

initialDataUpdatedAt: number | (() => number | undefined)

선택 사항

• 설정된 경우, 이 값이 초기 데이터가 마지막으로 업데이트된 시간을 나타내는 밀리초 단위의 값으로 사용됩니다.

---

placeholderData: TData | (previousValue: TData | undefined; previousQuery: Query | undefined) => TData

선택 사항

• 설정된 경우, 쿼리가 대기 상태(pending)일 동안 해당 쿼리 옵저버의 플레이스홀더 데이터로 사용됩니다.
• placeholderData는 캐시에 저장되지 않습니다.
• 함수로 제공된 경우, 첫 번째 인수로 이전에 조회된 쿼리 데이터를, 두 번째 인수로 완전한 이전 쿼리 객체를 받습니다.

---

structuralSharing: boolean | (oldData: unknown | undefined, newData: unknown) => unknown)

선택 사항

• 기본값은 true입니다.
• false로 설정된 경우, 쿼리 결과 간의 구조적 공유가 비활성화됩니다.
• 함수로 설정된 경우, 이전 데이터와 새 데이터 값을 전달받아 이를 결합한 결과를 반환해야 합니다. 이를 통해 직렬화할 수 없는 값이 포함된 경우에도 성능을 개선할 수 있습니다.

---

throwOnError: undefined | boolean | (error: TError, query: Query) => boolean

선택 사항

• 기본값은 글로벌 쿼리 설정의 throwOnError 값(기본적으로 undefined)입니다.
• true로 설정하면, 렌더링 단계에서 오류가 발생 시 이를 인근 오류 경계로 전파합니다.
• false로 설정하면, Suspense의 기본 동작(오류를 오류 경계로 전파)을 비활성화합니다.
• 함수로 설정된 경우, 오류와 쿼리를 전달받아 오류 경계에서 오류를 표시할지(true) 또는 상태로 반환할지(false)를 결정해야 합니다.

---

meta: Record<string, unknown>

선택 사항

• 설정된 경우, 쿼리 캐시 항목에 추가 정보를 저장합니다.
• 이는 쿼리에서 접근 가능하며, queryFn에 제공되는 QueryFunctionContext의 일부로도 사용할 수 있습니다.

---

Parameter2 (QueryClient)

queryClient?: QueryClient

• 사용자 정의 QueryClient를 사용하려면 설정하십시오. 그렇지 않으면 가장 가까운 컨텍스트의 클라이언트가 사용됩니다.

---

반환값

---

status: QueryStatus

• 다음 값 중 하나를 반환합니다:
  • pending: 캐시된 데이터가 없고 쿼리가 완료되지 않았을 때.
  • error: 쿼리 시도가 오류로 끝났을 때. 오류는 error 속성에 포함됩니다.
  • success: 오류 없이 응답을 수신한 경우.

---

isPending: boolean

• 위의 status에서 파생된 boolean 값입니다.

---

isSuccess: boolean

• status에서 파생된 boolean 값입니다.

---

isError: boolean

• status에서 파생된 boolean 값입니다.

---

isLoadingError: boolean

• 쿼리가 첫 번째 요청 중 실패했을 때 true입니다.

---

isRefetchError: boolean

• 다시 요청하는 동안 실패한 경우 true입니다.

---

data: TData

• 기본값은 undefined입니다.
• 쿼리의 마지막으로 성공적으로 해결된 데이터입니다.

---

dataUpdatedAt: number

• 쿼리가 마지막으로 성공 상태를 반환한 시간의 타임스탬프입니다.

---

error: null | TError

• 기본값은 null입니다.
• 쿼리 중 발생한 오류 객체입니다.

---

errorUpdatedAt: number

• 쿼리가 마지막으로 오류 상태를 반환한 시간의 타임스탬프입니다.

---

isStale: boolean

• 캐시의 데이터가 무효화되었거나, staleTime보다 오래된 경우 true입니다.

---

isPlaceholderData: boolean

• 표시된 데이터가 플레이스홀더 데이터인 경우 true입니다.

---

isFetched: boolean

• 쿼리가 실행된 경우 true입니다.

---

fetchStatus: FetchStatus

• 상태:
  • fetching: 쿼리 함수가 실행 중일 때.
  • paused: 쿼리가 데이터를 요청했지만 일시 중지된 경우.
  • idle: 쿼리가 데이터를 요청하지 않을 때.

---

failureCount: number

• 쿼리 실패 횟수입니다. 성공 시 0으로 초기화됩니다.

---

refetch: (options: { throwOnError: boolean, cancelRefetch: boolean }) => Promise<UseQueryResult>

• 쿼리를 수동으로 다시 요청하는 함수입니다.

---

promise: Promise<TData>

• 쿼리 데이터를 포함한 안정적인 Promise 객체입니다. experimental_prefetchInRender 플래그를 활성화해야 합니다.