O que é Paginação?

Consultar uma lista por partes

Paginação é a divisão de um conjunto de resultados em partes recuperáveis. Em uma API, cada chamada pode devolver um trecho da lista e informações para continuar. Na interface, isso pode aparecer como páginas numeradas, um botão para carregar mais ou rolagem contínua.

Uma consulta de contatos pode encontrar milhares de linhas, mas a tela precisa apresentar apenas uma parte por vez. Limitar a resposta reduz o conteúdo transportado e interpretado naquele momento. O trabalho realizado no banco ainda depende da consulta, dos filtros e dos índices.

Ler a primeira resposta não equivale a obter a coleção completa. Uma integração de exportação, por exemplo, precisa percorrer a continuação prevista pelo serviço. O encerramento deve seguir o contrato, sem presumir que uma página representa tudo o que existe.

Tamanho, ordem e continuação

O tamanho define quantos itens podem aparecer em cada trecho. A ordenação estabelece a sequência, e a continuação informa como acessar o próximo trecho. Esses três elementos precisam funcionar juntos para que o percurso seja compreensível.

Ordenar apenas por um campo que se repete pode deixar empates. Uma consulta por data, por exemplo, pode acrescentar o identificador como desempate. Sem ordem determinística, chamadas sucessivas podem apresentar sobreposição mesmo quando usam os mesmos parâmetros.

SELECT id, nome
FROM contatos
ORDER BY id
LIMIT 10 OFFSET 0;

Nesse exemplo, id deve identificar a linha de forma única. LIMIT restringe a quantidade, e OFFSET define quantas linhas do resultado ordenado serão puladas. A página seguinte usa outro deslocamento, mantendo os filtros e a ordenação.

Dois mecanismos de continuação

Paginação por offset usa uma posição numérica. Ela facilita calcular um deslocamento para páginas numeradas, mas páginas distantes podem exigir trabalho significativo para pular linhas. Mudanças na coleção também podem deslocar os resultados entre chamadas.

Paginação por cursor utiliza uma referência de continuação definida pela API. O cursor pode representar os valores do último item ou outro estado do serviço. Ele não é necessariamente um número de página nem garante uma fotografia imutável da coleção.

O total pode ser desconhecido

Algumas APIs informam o número total de resultados, e outras apenas indicam se há mais páginas. Calcular esse total também pode ter custo. A interface deve trabalhar com os campos retornados, sem inventar quantas páginas restam.

Uma página menor que o limite não comprova o término. A orientação AIP-158 do Google permite respostas com menos itens que o solicitado, inclusive nenhum, antes do fim da coleção. Nesse contrato, você verifica o campo next_page_token para saber se deve continuar. Outras APIs podem adotar outro sinal, que deve estar documentado.

Como conferir o percurso

Prepare um conjunto conhecido e percorra todas as partes, comparando os identificadores recebidos. Repita com filtros e empates na ordenação. Depois, teste alterações na coleção se esse comportamento fizer parte do uso esperado.

Os verbetes de offset e cursor de paginação detalham as diferenças entre as duas formas de continuar a leitura.

Aplicação na formação

Developer Workspace

A paginação organiza a entrega de listas e informa como continuar a consulta na interface ou na integração.

Conhecer a formação →