Paginação por cursor em vez de offset: páginas que permanecem estáveis quando os dados mudam

O que é

Paginação por offset significa algo como ORDER BY erstellt DESC LIMIT 20 OFFSET 400. A documentação do PostgreSQL observa que as linhas ignoradas pelo OFFSET ainda precisam ser calculadas no servidor, por isso um OFFSET grande pode ser ineficiente. Observa também que LIMIT sem uma cláusula ORDER BY que imponha uma ordem única devolve um subconjunto imprevisível. A paginação por cursor (também chamada de método keyset ou seek) guarda, em vez disso, o último item da página anterior e consulta apenas o que vem depois dele, como Markus Winand descreve na versão alemã citada de «SQL Performance Explained»: WHERE (erstellt, id) < (?, ?) ORDER BY erstellt DESC, id DESC FETCH FIRST 20 ROWS ONLY. A comparação com row values (sintaxe de valor de linha) trata o par como uma unidade, para a qual um índice composto consegue saltar diretamente.

Por que importa

Entre duas requisições com offset, cada linha inserida ou removida desloca todas as páginas seguintes: o cliente vê itens em duplicidade ou deixa de ver alguns. Para uma pessoa isso é incômodo; para um agente que deve processar um conjunto de dados por completo, é um erro de corretude. Além disso, o custo por página cresce com a profundidade, de modo que as últimas páginas de uma lista grande são as requisições mais caras da API. Um cursor baseado em uma chave de ordenação estável entrega cada item exatamente uma vez e custa o mesmo na página 5000 que na página 1.

Como aplicar

• Ordenar por uma chave única e indexada, ou por uma combinação que termine em um campo único (erstellt, id); o índice deve conter as mesmas colunas, na mesma ordem e direção.
• Devolver ao cliente um next_cursor opaco que codifique os valores de chave da última linha (Base64 de uma tupla JSON é suficiente); assinar ou cifrar o cursor se os clientes não puderem construir cursores por conta própria.
• Incluir filtro e ordenação no cursor ou rejeitá-lo quando os parâmetros divergirem; um cursor vale para exatamente uma consulta.
• Limitar o tamanho da página com um valor padrão e um máximo; indicar o fim da lista pela ausência de next_cursor, não por uma página vazia.
• Para navegar para trás, oferecer um prev_cursor com a direção de comparação invertida, ou abrir mão disso e documentar a decisão.

Armadilhas

Ordenar por uma coluna não única, sem critério de desempate, perde ou repete linhas nos limites das páginas. Cursores não permitem saltar «para a página 37»; se a interface precisa de números de página, offset com profundidade máxima limitada continua sendo a escolha mais honesta. Timestamps com resolução de segundos geram empates, por isso a chave única entra como segundo campo. Um cursor que carrega IDs internos em texto puro revela taxas de crescimento e convida à manipulação.