[React Query] 쿼리 옵션 (options) - 1

React Query 의 useQuery 옵션은 아주 다양한데 개발을 하면서 자주 쓰이는 옵션들을 우선적으로 정리해보려 한다.

 

 

1. select

---

select 옵션은 가져온 데이터를 변형하거나 선택해 최종 데이터로 반환해주는 옵션이다.

* 반환되는 최종 데이터 값에는 영향을 주지만 쿼리 캐시에 저장되는 내용에는 영향을 주지 않음

-  타입 : (data: TData) => unknown

import { useQuery } from "@tanstack/react-query";

function Component() {
    const { data } = useQuery({
        queryKey: ["libraries"],
        queryFn: () => fetchData()
        select: (res) => res.features.map((feature) => feature.attributes);
    })
    ...
}

 

 

2. enabled

---

enabled 옵션은 쿼리를 자동으로 실행할지 여부를 boolean 값으로 제어하는 옵션이다.

enabled 값이 false 면 마운트되어도 자동으로 데이터를 가져오지 않는다.

refetch() 를 호출하거나, enabled 값이 true로 변할 때 데이터를 가져오는 것이다.

// refetch()
function component() {
    const { data, refetch } = useQuery({
    	queryKey: ["libraries"],
        queryFn: () => fetchData(),
        enabled: false
    });
	
    return <button onClick={() => refetch()}>{data.name}</button>
}

// enabled : false -> true (의존데이터)
function component({id}) {
    const { data } = useQuery({
    	queryKey: ["libraries", id],
        queryFn: () => fetchData(id),
        enabled: !!id
    });
	
    return <button>{data.name}</button>
}

 

 

3. placeholderData

---

placeholderData 옵션은 쿼리 함수가 호출되는 pending 상태에서 임시로 표시할 데이터를 지정해주는 옵션이다.

캐시에 저장되지 않고, 서버 데이터와 관계없는 일시적인 UI 데이터이다.

function Component() {
    const { data } = useQuery({
        queryKey: ["libraries"],
        queryFn: () => fetchData(),
        placeholaderData: [{ id: 0, name: "도서관명" }]
    });
    
    return (
    	<ul>
            {data.map((library) => (
                <li>{library.name)</li>
            ))}
        </ul>
}

위 코드는 데이터를 가져오기 전이나 pending 상태에서는 placeholderData가 먼저 화면에 표시되고, 응답이 오면 실제 데이터로 교체되는 예이다.

새로운 데이터를 가져오는 과정에서 쿼리가 무효화되어 일시적으로 데이터가 없는 상태가 되었을 때 캐시 데이터에 영향 없이 화면깜빡임을 방지해 줄 수 있는 것이다.

 

 

4. staleTime

---

stale 의 용어 의미는 '신선하지 않은' 이라는 뜻으로, 데이터가 최신 상태가 아니라는 것을 의미한다.

그래서 staleTime 옵션은 데이터가 fresh 상태에서 stale 상태로 변경되는 데까지 걸리는 시간을 설정해주는 옵션이다.

React Query 에서는 캐시된 데이터가 stale 상태가 되면 새로 데이터를 가져오기 위해 네트워크 요청(fetch)이 일어나는 것이다.

* fresh 상태 → stale 상태 전환 시점만 결정하고, 캐시된 데이터는 여전히 메모리에 존재

- 타입 : numer | ((query: Query) => numer)

useQuery({
    queryKey: ["libraries"],
    queryFn: () => fetchData(),
    staleTime: 3 * 60 * 1000	// 3분
})

 

위 코드처럼 staleTime 을 설정하면 데이터를 가져온 후에 3분 동안은 캐시된 데이터를 사용기 때문에 불필요한 네트워크 요청을 줄이고, 성능을 최적화할 수 있는 것이다.

 

 

5. gcTime

---

gcTime 옵션은 비활성 캐시 데이터가 메모리에서 삭제되기까지의 시간을 설정해주는 옵션이다.

기본값은 5분으로 쿼리 인스턴스가 언마운트되면 캐시 데이터의 상태가 inactive 상태로 변경되며, 이 데이터는 5분 뒤에 삭제되고 가비지 컬렉터(GC)로 수집된다.

useQuery({
    queryKey: ["libraries"],
    queryFn: () => fetchData(),
    gcTime: 10 * 60 * 1000	// 10분
})

 

위 코드처럼 gcTime 을 설정하면 inactive 상태의 데이터가 10분이 지나면 메모리에서 삭제되기 때문에 메모리 누수를 방지하고, 효율적으로 사용할 수 있어 애플리케이션 안정성을 높일 수 있다.