본문으로 건너뛰기

useQuery

const {
  data,
  dataUpdatedAt,
  error,
  errorUpdateCount,
  errorUpdatedAt,
  failureCount,
  failureReason,
  fetchStatus,
  isError,
  isFetched,
  isFetchedAfterMount,
  isFetching,
  isInitialLoading,
  isLoading,
  isLoadingError,
  isPaused,
  isPending,
  isPlaceholderData,
  isRefetchError,
  isRefetching,
  isStale,
  isSuccess,
  isEnabled,
  refetch,
  status,
} = useQuery(
  {
    queryKey,
    queryFn,
    gcTime,
    enabled,
    networkMode,
    initialData,
    initialDataUpdatedAt,
    meta,
    notifyOnChangeProps,
    placeholderData,
    queryKeyHashFn,
    refetchInterval,
    refetchIntervalInBackground,
    refetchOnMount,
    refetchOnReconnect,
    refetchOnWindowFocus,
    retry,
    retryOnMount,
    retryDelay,
    select,
    staleTime,
    structuralSharing,
    subscribed,
    throwOnError,
  },
  queryClient,
)

매개변수 1(옵션)

  • queryKey: unknown[]
    • Required
    • 이 쿼리에 사용할 쿼리 키입니다.
    • 쿼리 키는 안정적인 해시로 해싱됩니다. 자세한 내용은 쿼리 키를 참조합니다.
    • 이 키가 변경되면 쿼리가 자동으로 업데이트됩니다(enabled가 false로 설정되지 않은 경우).
  • queryFn: (context: QueryFunctionContext) => Promise<TData>
    • 필수이지만 기본 쿼리 함수가 정의되지 않은 경우에만 해당합니다 자세한 내용은 기본 쿼리 함수를 참조하세요.
    • 쿼리가 데이터를 요청하는 데 사용할 함수입니다.
    • QueryFunctionContext를 받습니다
    • 데이터를 이행하거나 오류를 발생시키는 Promise를 반환해야 합니다. 데이터는 undefined일 수 없습니다.
  • enabled: boolean | (query: Query) => boolean
    • 이 쿼리가 자동으로 실행되지 않도록 하려면 이를 false로 설정합니다.
    • 종속 쿼리에 사용할 수 있습니다.
  • networkMode: 'online' | 'always' | 'offlineFirst'
    • 선택 사항
    • 기본값은 'online'입니다
    • 자세한 내용은 네트워크 모드를 참조하세요.
  • retry: boolean | number | (failureCount: number, error: TError) => boolean
    • false이면 실패한 쿼리는 기본적으로 재시도하지 않습니다.
    • true이면 실패한 쿼리는 무한히 재시도됩니다.
    • 예를 들어 3과 같은 number로 설정하면 실패한 쿼리 횟수가 해당 숫자에 도달할 때까지 실패한 쿼리를 재시도합니다.
    • 함수로 설정하면 재시도 여부를 결정하기 위해 failureCount(첫 번째 재시도는 0부터 시작) 및 error와 함께 호출됩니다.
    • 클라이언트에서는 기본값이 3이고 서버에서는 0입니다
  • retryOnMount: boolean | (query: Query) => boolean
    • false로 설정하면 쿼리에 오류가 있고 데이터가 없을 때 마운트 시 재시도하지 않습니다. 기본값은 true입니다.
    • 함수로 설정하면 값을 계산하기 위해 쿼리를 인수로 이 함수를 실행합니다.
  • retryDelay: number | (retryAttempt: number, error: TError) => number
    • 이 함수는 retryAttempt 정수와 실제 Error를 받아 다음 시도 전에 적용할 지연 시간을 밀리초 단위로 반환합니다.
    • attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)과 같은 함수는 지수 백오프를 적용합니다.
    • attempt => attempt * 1000과 같은 함수는 선형 백오프를 적용합니다.
  • staleTime: number | 'static' | ((query: Query) => number | 'static')
    • 선택 사항
    • 기본값은 0입니다
    • 데이터가 stale 상태로 간주되기까지의 시간(밀리초)입니다. 이 값은 정의된 훅에만 적용됩니다.
    • Infinity로 설정하면 수동으로 무효화하지 않는 한 데이터가 stale 상태로 간주되지 않습니다
    • 함수로 설정하면 쿼리와 함께 함수가 실행되어 staleTime을 계산합니다.
    • 'static'으로 설정하면 데이터가 절대 stale 상태로 간주되지 않습니다
  • gcTime: number | Infinity
    • 기본값은 5 * 60 * 1000(5분)이며, SSR 중에는 Infinity입니다
    • 사용되지 않거나 비활성 상태인 캐시 데이터가 메모리에 유지되는 시간(밀리초)입니다. 쿼리의 캐시가 사용되지 않거나 비활성 상태가 되면 이 시간이 지난 후 해당 캐시 데이터가 가비지 컬렉션됩니다. 서로 다른 가비지 컬렉션 시간이 지정되면 가장 긴 시간이 사용됩니다.
    • 참고: 허용되는 최대 시간은 약 24일이지만, timeoutManager.setTimeoutProvider를 사용하면 이 제한을 우회할 수 있습니다.
    • Infinity로 설정하면 가비지 컬렉션이 비활성화됩니다
  • queryKeyHashFn: (queryKey: QueryKey) => string
    • 선택 사항
    • 지정하면 이 함수를 사용하여 queryKey를 문자열로 해시합니다.
  • refetchInterval: number | false | ((query: Query) => number | false | undefined)
    • 선택 사항
    • 숫자로 설정하면 모든 쿼리가 이 밀리초 단위 주기로 계속 다시 가져옵니다
    • 함수로 설정하면 빈도를 계산하기 위해 해당 쿼리를 인수로 함수가 실행됩니다.
  • refetchIntervalInBackground: boolean
    • 선택 사항
    • true로 설정하면 refetchInterval을 사용해 지속적으로 다시 가져오도록 설정된 쿼리는 해당 탭/창이 백그라운드에 있는 동안에도 계속 다시 가져옵니다
  • refetchOnMount: boolean | "always" | ((query: Query) => boolean | "always")
    • 선택 사항
    • 기본값은 true입니다
    • true로 설정하면 데이터가 stale 상태일 경우 쿼리가 마운트 시 다시 가져옵니다.
    • false로 설정하면 쿼리가 마운트 시 다시 가져오지 않습니다.
    • "always"로 설정하면 쿼리는 마운트 시 항상 다시 가져옵니다(staleTime: 'static'를 사용하는 경우 제외).
    • 함수로 설정하면 값을 계산하기 위해 쿼리를 인자로 해당 함수가 실행됩니다
  • refetchOnWindowFocus: boolean | "always" | ((query: Query) => boolean | "always")
    • 선택 사항
    • 기본값은 true입니다
    • true로 설정하면 데이터가 stale 상태일 때 창에 포커스가 맞춰질 경우 쿼리를 다시 가져옵니다.
    • false로 설정하면 창에 포커스될 때 쿼리를 다시 가져오지 않습니다.
    • "always"로 설정하면 창에 포커스될 때 쿼리가 항상 다시 가져옵니다(staleTime: 'static'을 사용하는 경우 제외).
    • 함수로 설정하면 값을 계산하기 위해 쿼리를 인자로 해당 함수가 실행됩니다
  • refetchOnReconnect: boolean | "always" | ((query: Query) => boolean | "always")
    • 선택 사항
    • 기본값은 true입니다
    • true로 설정하면 데이터가 stale 상태인 경우 다시 연결될 때 쿼리를 다시 가져옵니다.
    • false로 설정하면 다시 연결될 때 쿼리를 다시 가져오지 않습니다.
    • "always"로 설정하면 쿼리는 다시 연결될 때 항상 다시 가져옵니다(staleTime: 'static'을 사용하는 경우 제외).
    • 함수로 설정하면 값을 계산하기 위해 쿼리를 인자로 해당 함수가 실행됩니다
  • notifyOnChangeProps: string[] | "all" | (() => string[] | "all" | undefined)
    • 선택 사항
    • 설정하면 나열된 속성 중 하나라도 변경될 때만 컴포넌트가 다시 렌더링됩니다.
    • 예를 들어 ['data', 'error']으로 설정하면 data 또는 error 속성이 변경될 때만 컴포넌트가 다시 렌더링됩니다.
    • "all"으로 설정하면 컴포넌트가 스마트 추적을 사용하지 않으며 쿼리가 업데이트될 때마다 다시 렌더링됩니다.
    • 함수로 설정하면 속성 목록을 계산하기 위해 해당 함수가 실행됩니다.
    • 기본적으로 속성 접근이 추적되며, 추적된 속성 중 하나가 변경될 때만 컴포넌트가 다시 렌더링됩니다.
  • select: (data: TData) => unknown
    • 선택 사항
    • 이 옵션은 쿼리 함수가 반환한 데이터의 일부를 변환하거나 선택하는 데 사용할 수 있습니다. 반환되는 data 값에는 영향을 주지만, 쿼리 캐시에 저장되는 내용에는 영향을 주지 않습니다.
    • select 함수는 data가 변경되거나 select 함수 자체에 대한 참조가 변경된 경우에만 실행됩니다. 최적화하려면 함수를 useCallback으로 래핑합니다.
  • initialData: TData | () => TData
    • 선택 사항
    • 설정하면 이 값이 쿼리 캐시의 초기 데이터로 사용됩니다(쿼리가 아직 생성되거나 캐시되지 않은 경우에 한함)
    • 함수로 설정하면 공유/루트 쿼리 초기화 중에 함수가 한 번 호출되며, initialData를 동기적으로 반환해야 합니다.
    • staleTime이 설정되지 않은 한 초기 데이터는 기본적으로 stale 상태로 간주됩니다.
    • initialData 이 캐시에 영구 저장됩니다
  • initialDataUpdatedAt: number | (() => number | undefined)
    • 선택 사항
    • 설정하면 이 값은 initialData 자체가 마지막으로 업데이트된 시간(밀리초 단위)으로 사용됩니다.
  • placeholderData: TData | (previousValue: TData | undefined, previousQuery: Query | undefined) => TData
    • 선택 사항
    • 설정하면 쿼리가 아직 pending 상태인 동안 이 값이 해당 쿼리 observer의 placeholder 데이터로 사용됩니다.
    • placeholderData는 캐시에 영구 저장되지 않습니다
    • placeholderData에 함수를 제공하면 첫 번째 인수로 이전에 관찰한 쿼리 데이터가 있는 경우 해당 데이터를 받고, 두 번째 인수로 완전한 previousQuery 인스턴스를 받습니다.
  • structuralSharing: boolean | (oldData: unknown | undefined, newData: unknown) => unknown
    • 선택 사항
    • 기본값은 true입니다
    • false로 설정하면 쿼리 결과 간의 구조적 공유가 비활성화됩니다.
    • 함수로 설정하면 이전 데이터 값과 새 데이터 값이 이 함수에 전달되며, 함수는 이를 쿼리의 이행된 데이터로 결합해야 합니다. 이렇게 하면 데이터에 직렬화할 수 없는 값이 포함되어 있어도 성능 향상을 위해 이전 데이터의 참조를 유지할 수 있습니다.
  • subscribed: boolean
    • 선택 사항
    • 기본값은 true입니다
    • false로 설정하면 이 useQuery 인스턴스는 캐시를 구독하지 않습니다. 즉, 자체적으로 queryFn을 트리거하지 않으며 다른 방식으로 데이터가 캐시에 들어와도 업데이트를 받지 않습니다.
  • throwOnError: undefined | boolean | (error: TError, query: Query) => boolean
    • 선택 사항
    • 기본값은 false입니다
    • 렌더링 단계에서 오류를 발생시키고 가장 가까운 error boundary로 전파하려면 이를 true로 설정하세요
    • 함수로 설정하면 오류와 쿼리가 전달되며, 오류를 오류 경계에 표시할지(true) 또는 오류를 상태로 반환할지(false)를 나타내는 boolean을 반환해야 합니다.
  • meta: Record<string, unknown>
    • 선택 사항
    • 설정하면 필요에 따라 사용할 수 있는 추가 정보를 쿼리 캐시 항목에 저장합니다. 이 정보는 query를 사용할 수 있는 모든 곳에서 접근할 수 있으며, queryFn에 제공되는 QueryFunctionContext의 일부이기도 합니다.

파라미터2(QueryClient)

  • queryClient?: QueryClient
    • 사용자 지정 QueryClient를 사용하려면 이를 사용합니다. 그렇지 않으면 가장 가까운 context의 항목이 사용됩니다.

반환값

  • status: QueryStatus
    • 다음과 같습니다:
      • 캐시된 데이터가 없고 아직 완료된 쿼리 시도도 없다면 pending입니다.
      • 쿼리 시도에서 오류가 발생한 경우 error입니다. 해당 error 속성에는 가져오기 시도에서 받은 오류가 있습니다
      • 쿼리가 오류 없이 응답을 받아 데이터를 표시할 준비가 되었으면 success입니다. 쿼리의 해당 data 속성은 성공적인 가져오기로 받은 데이터이며, 쿼리의 enabled 속성이 false로 설정되어 있고 아직 가져오지 않았다면 data는 초기화 시 쿼리에 제공된 첫 번째 initialData입니다.
  • isPending: boolean
    • 편의를 위해 제공되는, 위 status 변수에서 파생된 boolean 값입니다.
  • isSuccess: boolean
    • 편의를 위해 제공되는, 위 status 변수에서 파생된 boolean 값입니다.
  • isError: boolean
    • 편의를 위해 제공되는, 위 status 변수에서 파생된 boolean 값입니다.
  • isLoadingError: boolean
    • 쿼리가 처음으로 가져오는 동안 실패하면 true가 됩니다.
  • isRefetchError: boolean
    • 다시 가져오는 동안 쿼리가 실패하면 true입니다.
  • data: TData
    • 기본값은 undefined입니다.
    • 쿼리에서 마지막으로 성공적으로 이행된 데이터입니다.
  • dataUpdatedAt: number
    • 쿼리가 가장 최근에 status를 "success"로 반환한 시점의 타임스탬프입니다.
  • error: null | TError
    • 기본값은 null입니다
    • 오류가 발생한 경우 쿼리의 오류 객체입니다.
  • errorUpdatedAt: number
    • 쿼리가 가장 최근에 status를 "error"로 반환한 시점의 타임스탬프입니다.
  • isStale: boolean
    • 캐시의 데이터가 무효화되었거나 데이터가 지정된 staleTime보다 오래된 경우 true가 됩니다.
  • isPlaceholderData: boolean
    • 표시된 데이터가 플레이스홀더 데이터이면 true입니다.
  • isFetched: boolean
    • 쿼리를 가져온 경우 true가 됩니다.
  • isFetchedAfterMount: boolean
    • 컴포넌트가 마운트한 후 쿼리를 가져왔다면 true가 됩니다.
    • 이 속성을 사용하면 이전에 캐시된 데이터를 표시하지 않을 수 있습니다.
  • fetchStatus: FetchStatus
    • fetching: 초기 pending과 백그라운드 다시 가져오기를 포함하여 queryFn이 실행 중일 때마다 true입니다.
    • paused: 쿼리가 가져오기를 시도했지만 paused되었습니다.
    • idle: 쿼리가 데이터를 가져오고 있지 않습니다.
    • 자세한 내용은 네트워크 모드를 참조하세요.
  • isFetching: boolean
    • 편의를 위해 제공되는, 위 fetchStatus 변수에서 파생된 boolean 값입니다.
  • isPaused: boolean
    • 편의를 위해 제공되는, 위 fetchStatus 변수에서 파생된 boolean 값입니다.
  • isRefetching: boolean
    • 백그라운드 다시 가져오기가 진행 중일 때마다 true이며, 초기 pending은 여기에 포함되지 않습니다.
    • isFetching && !isPending과 동일합니다
  • isLoading: boolean
    • 쿼리의 첫 번째 가져오기가 진행 중일 때마다 true입니다
    • isFetching && isPending과 동일합니다
  • isInitialLoading: boolean
    • 사용 중단됨
    • isLoading의 별칭이며, 다음 major 버전에서 제거됩니다.
  • isEnabled: boolean
    • 이 쿼리 옵저버가 활성화되어 있으면 true이고, 그렇지 않으면 false입니다.
  • failureCount: number
    • 쿼리의 실패 횟수입니다.
    • 쿼리가 실패할 때마다 증가합니다.
    • 쿼리가 성공하면 0으로 재설정합니다.
  • failureReason: null | TError
    • 쿼리 재시도의 실패 원인입니다.
    • 쿼리가 성공하면 null로 재설정합니다.
  • errorUpdateCount: number
    • 모든 오류의 합계입니다.
  • refetch: (options: { throwOnError: boolean, cancelRefetch: boolean }) => Promise<UseQueryResult>
    • 쿼리를 수동으로 다시 가져오는 함수입니다.
    • 쿼리에서 오류가 발생하면 오류는 로그에만 기록됩니다. 오류를 발생시키려면 throwOnError: true 옵션을 전달합니다
    • cancelRefetch?: boolean
      • 기본값은 true입니다
        • 기본적으로 새 요청을 보내기 전에 현재 실행 중인 요청이 취소됩니다
      • false로 설정하면 이미 요청이 실행 중일 때 다시 가져오기를 수행하지 않습니다.