Como você pagina resultados em Django e DRF?

Question

Accepted Answer

**Paginação** divide um grande conjunto de resultados em páginas discretas, para que você não carregue milhares de registros de uma vez. É essencial para desempenho e usabilidade. Django fornece uma classe `Paginator` para templates/views, e DRF oferece paginação integrada para APIs. ## O problema que a paginação resolve ```python # ❌ loading everything — slow, memory-heavy, bad UX with thousands of rows articles = Article.objects.all() # could be 100,000 records ``` ## Paginator do Django (para views/templates tradicionais) ```python from django.core.paginator import Paginator def article_list(request): articles = Article.objects.all().order_by("-created_at") # ORDER matters for consistent pages paginator = Paginator(articles, 20) # 20 items per page page_number = request.GET.get("page") # ?page=2 page_obj = paginator.get_page(page_number) # the requested page return render(request, "list.html", {"page_obj": page_obj}) ``` ```html {% for article in page_obj %}

{% endfor %} {% if page_obj.has_previous %}Prev{% endif %} Page {{ page_obj.number }} of {{ page_obj.paginator.num_pages }} {% if page_obj.has_next %}Next{% endif %} ``` O `Paginator` divide um queryset em páginas e `get_page()` retorna um objeto de página com assistentes de navegação (`has_next`, `next_page_number`, etc.) — note que adiciona `LIMIT`/`OFFSET` à query, portanto apenas uma página é buscada do banco de dados. ## Paginação DRF (para APIs) ```python # global default in settings.py REST_FRAMEWORK = { "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.PageNumberPagination", "PAGE_SIZE": 20, } # now list endpoints are automatically paginated, returning: # { "count": 1000, "next": "...?page=3", "previous": "...?page=1", "results": [...] } ``` DRF pagina automaticamente os endpoints de listagem uma vez configurado, retornando metadados de página (contagem, links próximo/anterior) junto com os resultados — clientes navegam através das URLs fornecidas. ## Estilos de paginação DRF ```text PageNumberPagination → ?page=2 (simple page numbers) LimitOffsetPagination → ?limit=20&offset=40 (flexible offsets) CursorPagination → opaque cursor; consistent & performant for large/changing data (avoids OFFSET performance issues on huge datasets) ``` ## A nuance de desempenho ```text ⚠️ OFFSET-based pagination (page/offset) gets SLOWER on deep pages of huge tables (the DB must skip OFFSET rows). For very large datasets, CURSOR pagination (keyset, using a WHERE on an indexed column) is far more efficient. ⚠️ Always ORDER BY a stable field, or pages can be inconsistent/repeat items. ``` ## Por que isso importa Paginação é essencial para construir aplicações performáticas e usáveis que lidam com volumes reais de dados — sem ela, endpoints de listagem e páginas que carregam tabelas inteiras (potencialmente milhares ou milhões de linhas) se tornam lentos, intensivos em memória e inutilizáveis, tanto sobrecarregando o banco de dados quanto sobrecarregando usuários e clientes. Entender paginação é conhecimento prático cotidiano: o **Paginator** do Django lida com views/templates tradicionais (dividindo querysets em páginas com assistentes de navegação, buscando eficientemente apenas uma página via LIMIT/OFFSET), e a **paginação integrada** de DRF lida com APIs (paginando automaticamente endpoints de listagem com metadados e links de navegação uma vez configurados) — ambos são necessários dependendo se você está construindo páginas renderizadas no servidor ou APIs. Saber como implementar paginação em ambos os contextos é necessário para quase qualquer funcionalidade de listagem de dados. A **nuance de desempenho** é particularmente conhecimento valioso em nível sênior: paginação baseada em OFFSET padrão se degrada em páginas profundas de tabelas muito grandes (o banco de dados deve pular todas as linhas anteriores), portanto **paginação por cursor (keyset)** é a escolha eficiente para conjuntos de dados enormes ou em rápida mudança, e sempre **ordenar por um campo estável** é necessário para evitar resultados inconsistentes ou duplicados entre páginas. Entender tanto a mecânica básica (Paginator, classes de paginação DRF) quanto essas considerações de desempenho (paginação OFFSET vs cursor, ordenação consistente) é importante para construir aplicações que permanecem rápidas e corretas à medida que os dados crescem — paginação é um requisito onipresente, e fazê-la bem, especialmente em escala, é uma habilidade prática que afeta diretamente o desempenho da aplicação e a experiência do usuário.