Pagination par curseur plutôt que par décalage : des pages stables face aux modifications

Ce que c'est

La pagination par décalage s'écrit : ORDER BY erstellt DESC LIMIT 20 OFFSET 400. La documentation de PostgreSQL précise à ce sujet que les lignes sautées par OFFSET doivent quand même être calculées sur le serveur, ce qui peut rendre un grand OFFSET inefficace — et qu'un LIMIT sans clause ORDER BY imposant un ordre unique fournit un sous-ensemble imprévisible. La pagination par curseur (aussi appelée méthode par ensemble de clés ou seek) retient au contraire la dernière entrée de la page précédente et n'interroge que celles qui suivent, comme le décrit Markus Winand dans l'édition allemande citée de « SQL Performance Explained » : WHERE (erstellt, id) < (?, ?) ORDER BY erstellt DESC, id DESC FETCH FIRST 20 ROWS ONLY. La comparaison par valeurs de ligne (row values) fait de la paire une unité vers laquelle un index composé peut sauter directement.

Pourquoi c'est important

Entre deux requêtes par décalage, chaque ligne insérée ou supprimée déplace toutes les pages ultérieures : un client voit des entrées en double ou les manque — ennuyeux pour une personne, mais une erreur d'exactitude pour un agent censé traiter un ensemble de données de façon exhaustive. De plus, le coût par page croît avec la profondeur, si bien que les dernières pages d'une grande liste sont les requêtes les plus coûteuses de l'API. Un curseur accroché à une clé de tri stable fournit chaque entrée exactement une fois et coûte, à la page 5000, la même chose qu'à la page 1.

Comment l'appliquer

• Trier selon une clé unique et indexée, ou selon une combinaison qui se termine par un champ unique (erstellt, id) ; l'index doit porter les mêmes colonnes dans le même ordre et la même direction.
• Renvoyer au client un next_cursor opaque qui encode les valeurs de clé de la dernière ligne (le Base64 d'un tuple JSON suffit) ; signer ou chiffrer si les clients ne doivent pas pouvoir construire leurs propres curseurs.
• Faire porter au curseur le filtre et le tri, ou rejeter les paramètres qui diffèrent ; un curseur n'est valide que pour une seule requête donnée.
• Limiter la taille de page avec une valeur par défaut et un plafond ; signaler la fin de la liste par l'absence de next_cursor, pas par une page vide.
• Pour la pagination arrière, proposer un prev_cursor avec un sens de comparaison inversé, ou y renoncer et le documenter.

Pièges

Trier selon une colonne non unique sans départage perd ou répète des lignes aux limites de page. Les curseurs ne peuvent pas sauter « à la page 37 » ; si l'interface a besoin de numéros de page, le décalage avec une profondeur maximale limitée reste le choix le plus honnête. Les horodatages à résolution de la seconde créent des égalités — d'où la clé comme second champ. Un curseur qui porte des identifiants internes en clair révèle les taux de croissance et invite au bricolage.