🔖 커서 페이지네이션으로 책갈피 펴듯 데이터 탐색하기

웹 애플리케이션을 개발하다 보면 많은 양의 데이터를 효율적으로 보여주어야 하는 상황을 자주 마주치게 됩니다. 이때 가장 먼저 떠오르는 해결책이 바로 페이지네이션이죠. 하지만 전통적인 페이지 번호 기반의 페이지네이션은 몇 가지 한계점을 안고 있습니다. 예를 들어, 데이터가 중간에 추가되거나 삭제되면 사용자가 보고 있던 페이지의 내용이 뒤죽박죽 꼬여버릴 수 있죠 😵‍💫💫

이러한 문제를 해결하기 위해 등장한 것이 바로 커서(Cursor) 기반 페이지네이션입니다. 마치 책갈피처럼 특정 위치를 표시해두고, 그 지점부터 다음 데이터를 가져오는 방식인데요, 이번 글에서는 커서 페이지네이션의 개념과 프론트엔드에서 TanStack Query와 결합하여 이를 구현하는 방법을 살펴보도록 하겠습니다.

커서 페이지네이션이란?

커서 페이지네이션은 데이터의 특정 지점을 기준으로 그 이후의 데이터를 요청하는 방식입니다. 기존의 offset/limit 방식이 "5페이지의 데이터 주세요"라고 요청한다면, 커서 방식은 "이 항목 이후의 데이터 20개를 주세요"라고 요청하는 셈이죠. 마치 긴 문서를 읽다가 책갈피를 꽂아두고, 나중에 그 지점부터 다시 읽기 시작하는 것과 비슷합니다 🔖

가령, SNS 피드나 무한 스크롤을 구현할 때 커서 페이지네이션이 특히 유용합니다. 사용자가 스크롤을 내릴 때마다 마지막으로 본 게시물의 ID를 커서로 사용하여 그 이후의 게시물을 요청하는 식이죠.

// 기존의 offset/limit 방식
const fetchUsers = (page, limit) => {
  const offset = (page - 1) * limit;
  return db.users.findMany({
    skip: offset,
    take: limit
  });
};

// 커서 기반 페이지네이션
const fetchUsers = (cursor, limit) => {
  return db.users.findMany({
    take: limit,
    cursor: {
      id: cursor
    },
    orderBy: {
      id: 'desc'
    }
  });
};

커서 페이지네이션의 장점

커서 방식의 가장 큰 장점은 데이터의 일관성을 유지할 수 있다는 점입니다. offset 방식은 중간에 데이터가 추가되거나 삭제되면 페이지의 내용이 밀리거나 중복될 수 있는 문제가 있습니다. 하지만 커서 방식은 각 데이터 항목에 부여된 고유 식별자(고유 ID나 타임스탬프 등)를 기준으로 데이터를 가져오기 때문에 데이터의 물리적인 위치나 순서가 바뀌어도 문제가 발생하지 않습니다.

또한 커서 방식은 대용량 데이터를 처리할 때 효율성이 극대화 됩니다. PostgreSQL 환경에서 진행한 벤치마크 테스트 결과를 살펴보면 그 차이를 확인할 수 있습니다. 위 그래프는 100만 건의 사용자 데이터를 대상으로, 페이지당 20개 항목을 기준으로 다양한 위치에서 반복 측정한 결과를 나타냅니다.

그래프에서 볼 수 있듯이, offset 방식은 레코드 수가 증가할수록 응답 시간이 기하급수적으로 증가합니다. 특히 50만 건을 넘어가는 지점부터 성능 저하가 뚜렷해지며, 100만 건에 가까워질 때는 평균 2초 이상이 소요됩니다. 반면 커서 방식은 데이터 크기와 관계없이 일관되게 50ms 이내의 응답 시간을 유지합니다.

이러한 성능 차이는 데이터베이스의 작동 방식에서 기인합니다. offset 방식에서는 지정된 offset만큼의 레코드를 순차적으로 스캔한 후 건너뛰어야 하지만, 커서 방식에서는 인덱스를 통해 특정 위치에 직접 접근할 수 있기 때문입니다. 게다가 offset 방식은 메모리 사용량도 offset 크기에 비례하여 증가하는데, 100만 건 기준으로 최대 128MB까지 임시 메모리를 사용하는 것으로 측정되었습니다.

이러한 커서 페이지네이션의 장점을 최대한으로 활용하려면 효과적인 데이터 관리가 필수적입니다. 여기서 TanStack Query가 등장하는데요, TanStack Query를 활용하면 커서 기반의 데이터를 훨씬 더 효과적으로 다룰 수 있습니다.

쿼리 키로 시작하는 데이터 관리

TanStack Query는 쿼리 키를 기반으로 데이터를 캐싱합니다. 검색어, 필터, 페이지 번호, 그리고 커서 정보까지 포함된 배열을 쿼리 키로 사용하면 각각의 고유한 검색 상태에 대한 데이터를 정확하게 캐시할 수 있죠.

const queryKey = [
  "getSearch",// 검색 도메인
  debouncedQuery,// 검색어
  filter,// 필터 조건
  page,// 현재 페이지
  pageSize,// 페이지당 항목 수
  cursor// 커서 정보
];

이렇게 설계된 쿼리 키는 마치 데이터의 주민등록번호처럼 작동합니다. 사용자가 검색어를 변경하거나, 필터를 바꾸거나, 페이지를 이동할 때마다 TanStack Query는 해당하는 캐시를 정확히 찾아내서 재사용할 수 있죠. 이는 불필요한 API 호출을 줄이고 애플리케이션의 성능을 크게 향상시킵니다.

데이터 동기화와 캐싱 전략

커서 데이터는 Zustand와 같은 상태 관리 도구와 만나면 더욱 빛을 발합니다. 서버에서 받아온 커서 정보를 전역 상태로 관리하면서도, TanStack Query의 캐싱 메커니즘을 동시에 활용할 수 있죠.

const useSearchStore = create<SearchState>((set) => ({
  cursor: { preData: null, nextIndex: null },
  setCursor: (cursor) => set({
    preData: cursor?.preData || null,
    nextIndex: cursor?.nextIndex || null,
  }),
}));

// 컴포넌트에서의 활용
const { data, isLoading } = useQuery({
  queryKey: ["getSearch", debouncedQuery, filter, page, pageSize, cursor],
  queryFn: () => getSearch({
    query: debouncedQuery,
    filter,
    page,
    pageSize,
    cursor,
  }),
  staleTime: 5 * ONE_MINUTE,
});

이 코드에서는 Zustand와 TanStack Query를 결합하여 커서 데이터를 효율적으로 관리하고 있습니다. Zustand는 서버에서 반환된 커서 정보를 전역적으로 관리하여 여러 컴포넌트가 동일한 상태를 공유할 수 있도록 도와줍니다. TanStack Query는 쿼리 키에 커서 정보를 포함시켜, 각 상태를 고유하게 구분하고 캐싱 메커니즘을 통해 불필요한 네트워크 요청을 줄입니다. 이처럼 상태 관리와 캐싱 전략의 결합은 데이터 요청을 최적화하고, 사용자 경험을 개선하는 데 중요한 역할을 합니다.

페이지 전환 최적화하기

커서 기반의 페이지 전환은 특정 지점을 기준으로 이전과 다음 데이터를 자연스럽게 탐색할 수 있게 해줍니다. 이때 TanStack Query의 invalidateQueries를 활용하면 필요한 데이터만 선택적으로 갱신할 수 있습니다.

const handlePage = (mode: "prev" | "next") => {
  const cursor = {
    curPage: page,
    preData,
    nextIndex,
  };

  if (mode === "next" && nextIndex) {
    setPage(page + 1);
    queryClient.invalidateQueries({
      queryKey: ["getSearch", searchParam, currentFilter, page + 1, 10,
        { ...cursor, preData: null }],
    });
  }
};

invalidateQueries는 특정 쿼리 키를 기반으로 필요한 데이터만 갱신하도록 설계되었습니다. 이는 전체 데이터를 다시 가져오는 대신, 변경된 부분만 업데이트하여 네트워크 부하를 줄이고 성능을 최적화합니다. 이렇게 구성된 페이지 전환 로직은 데이터 변경이 빈번한 환경에서도 안정적으로 작동하며, 사용자가 부드럽고 빠르게 페이지를 탐색할 수 있도록 지원합니다. TanStack Query와 커서 기반 설계는 대규모 데이터 관리에서도 이러한 장점을 극대화합니다.

마무리하며

커서 페이지네이션과 TanStack Query 콤비는 대규모 데이터를 다루는 효과적인 해결책을 제시합니다. 기존의 offset 기반 페이지네이션이 가진 성능과 데이터 일관성 문제를 해결하면서도, TanStack Query의 캐싱 시스템을 활용해 서버 부하까지 효과적으로 관리할 수 있게 되었죠. 특히 실시간으로 데이터가 추가되고 변경되는 웹 애플리케이션에서 무한 스크롤이나 실시간 피드와 같은 기능을 구현할 때도, 커서 기반 페이지네이션은 데이터의 일관성을 자연스럽게 보장하면서도 부드러운 사용자 경험을 제공할 수 있습니다. 페이지네이션을 통해 데이터를 보여주고 계시다면, 커서 방식을 도입 해보는 건 어떠신가요? 페이지 이동마다 깜빡이고 멈추지 않는 로딩 스피너에서 벗어나서 대규모 데이터 관리의 갈피를 잡을 수 있을거예요 🦾