Django Keyset 페이지네이션: created_at 하나로는 부족한 커서 설계
첫 페이지는 빠른데 수천 번째 페이지가 느리다. OFFSET이 커질수록 DB는 건너뛸 행도 계산해야 한다. 다음 위치를 행 수로 표현하는 대신 마지막으로 본 정렬 값으로 표현하면 이 비용을 줄일 수 있다.
기준: Django 5.2 · PostgreSQL 17.
Event.created_at은 NULL이 아니며 생성 후 바뀌지 않는다. 예제는 최신순 단방향 탐색이다.
정렬은 반드시 유일해야 한다
order_by("-created_at")만 있으면 같은 시각의 행 사이 순서가 불분명하다. 마지막 시각보다 작은 행만 읽으면 같은 시각의 남은 행을 누락할 수 있다. (created_at, id)처럼 최종적으로 유일한 순서를 만든다. PostgreSQL도 LIMIT 사용 시 예측 가능한 부분집합을 위해 유일한 정렬을 요구한다. LIMIT과 OFFSET 문서
from django.db.models import Q
def event_page(tenant_id, cursor_values=None, page_size=50):
if not 1 <= page_size <= 100:
raise ValueError("invalid page size")
qs = Event.objects.filter(tenant_id=tenant_id)
if cursor_values is not None:
last_created, last_id = cursor_values
qs = qs.filter(
Q(created_at__lt=last_created)
| Q(created_at=last_created, pk__lt=last_id)
)
rows = list(qs.order_by("-created_at", "-pk")[:page_size + 1])
has_next = len(rows) > page_size
items = rows[:page_size]
next_values = None
if has_next:
tail = items[-1]
next_values = (tail.created_at, tail.pk)
return items, next_values
커서는 추가로 읽은 한 행이 아니라 실제로 반환한 마지막 행에서 만든다. 다음 페이지에서 그 뒤의 구간을 읽어야 하기 때문이다. 실제 HTTP 응답에서는 datetime을 정밀도가 유지되는 형식으로 직렬화한다.
커서는 클라이언트가 믿고 보내는 권한 정보가 아니다
실서비스의 커서에는 정렬 값뿐 아니라 정렬 버전과 필터 식별자를 넣는 편이 좋다. 서명으로 변조를 검출하되, 서명된 커서라도 현재 사용자의 권한 검증을 대신하지 않는다. tenant는 인증된 요청 컨텍스트에서 얻고 쿼리에 다시 적용한다.
이 예제의 cursor_values는 서버에서 이미 검증한 값이다. 임의 문자열을 그대로 넣지 말고 서명, 만료, 타입, 시간대, 페이지 크기를 검사한다. 검색어·상태 필터가 바뀌면 이전 커서를 거부하거나 새 탐색을 시작한다. 서명은 암호화가 아니므로 커서 내부에 비밀 값을 넣지 않는다.
인덱스는 WHERE와 ORDER BY를 함께 본다
tenant로 범위를 제한하고 최신순으로 읽는다면 (tenant_id, created_at, id) 계열 복합 인덱스를 후보로 삼는다. 실제 선택은 데이터 분포와 실행 계획으로 확인한다. created_at 단일 인덱스만 추가해 모든 필터 조합이 빨라질 것이라 기대해서는 안 된다.
복합 OR 조건이 어떤 계획으로 풀리는지도 본다. 높은 선택도의 필터가 추가되면 다른 인덱스가 필요할 수 있고, 큰 tenant와 작은 tenant의 계획이 다를 수 있다. 목표는 “커서 썼음”이 아니라 페이지가 깊어져도 읽는 행 수와 지연이 과도하게 늘지 않는 상태다.
Keyset은 스냅샷을 제공하지 않는다
페이지 사이에 새 행이 추가되면 최신순 탐색에서 이미 지나온 영역에 들어갈 수 있다. 정렬 키가 수정되거나 조회 조건이 바뀌면 중복·누락 가능성도 있다. 따라서 관리자 목록 탐색과 회계 보고서 내보내기를 같은 일관성 요구로 취급하지 않는다.
조회 시작 시점의 상한 키를 커서에 포함하면 그 이후 생성된 최신 영역을 제외하는 데 도움은 된다. 그러나 늦게 커밋된 행이나 과거 시각으로 입력된 행까지 완벽히 고정하지는 않는다. 정확한 스냅샷이 필요하면 별도 스냅샷 데이터나 내보내기 작업의 범위를 설계한다.
경계값으로 검증한다
같은 created_at을 가진 행을 페이지 크기보다 많이 만든다. 모든 페이지를 순회했을 때 각 ID가 한 번씩 나오는지 검사한다. 그다음 첫 페이지를 읽은 뒤 새 행을 추가하고, 마지막 반환 행을 삭제하고, 필터를 바꾸는 경우를 각각 검증한다.
Keyset의 대가는 임의의 “1000페이지로 이동”이 자연스럽지 않다는 점이다. 정확한 전체 개수도 별도 계산이다. 제품이 요구하는 것이 다음·이전 탐색인지, 임의 페이지 이동인지 먼저 정하고 적용하자.
댓글
댓글 쓰기