---
name: hashgraph-online/django-pagination-performance
source: https://app.decimal.ai/s/hashgraph-online-django-pagination-performance@1/SKILL.md
source_sha256: 79e824864018
---

# Django Pagination Performance

Use this skill when a Django list view or API slows down as pages get deeper or result sets grow. Pagination is a query-design problem as much as a response-shaping problem.

## Workflow

1. Confirm the list contract.
   - Is arbitrary page access required, or only next/previous?
   - Does the UI need a total count?
   - Can ordering be fixed and stable?
   - What page size limit is acceptable?

2. Measure the current query.
   - Capture SQL for the page query and count query.
   - Check ordering, indexes, and high page numbers.
   - Use `QuerySet.explain()` for deep pages.

3. Choose the pagination style.
   - Use Django `Paginator` for moderate result sets and arbitrary page access.
   - Use capped offset pagination when page numbers are useful but deep pages should be limited.
   - Use keyset/cursor pagination for large feeds, timelines, logs, and infinite scroll.
   - Use DRF `CursorPagination` for API next/previous navigation with stable ordering.

4. Make ordering deterministic.
   - Use a unique or nearly unique immutable ordering field.
   - Add a primary-key tie breaker when needed.
   - Ensure the index matches filters plus ordering.

See [pagination-patterns.md](references/pagination-patterns.md) for Django and DRF examples.

## Safety Notes

- Deep `LIMIT/OFFSET` pages can be slow because the database still walks skipped rows.
- Unordered querysets produce inconsistent pages.
- Cursor pagination restricts arbitrary page jumps and user-controlled ordering.
- Large exact counts can dominate list latency.

## Verification

Measure first page, representative deep page, count query, and insertion/deletion consistency for the chosen pagination contract.