Comment paginer en GraphQL : offset contre cursor ?

Question

IT Interview Practice · Accepted Answer

Deux stratégies : **basée sur l'offset** (`limit`/`offset`) et **basée sur le cursor**. GraphQL n'a pas de pagination intégrée, mais le standard de la communauté est la spécification **Relay Connection**, qui formalise la pagination par cursor.

## Offset contre cursor

- L'**offset** (`items(limit: 10, offset: 20)`) est simple mais se casse sur des données vivantes : si une ligne est insérée pendant que l'utilisateur pagine, les éléments se décalent et vous voyez des doublons ou des trous. Il devient aussi lent aux offsets profonds (la DB parcourt quand même les lignes ignorées).
- Le **cursor** pointe vers une position stable (« donne-moi les 10 après cet élément »). Il est insensible aux insertions et passe à l'échelle sur les pages profondes, au prix de l'impossibilité de « sauter à la page 50 » aléatoirement.

## Les connections Relay

Une connection enveloppe la liste dans des `edges` (chacun avec un `cursor` et un `node`) plus un `pageInfo` :

```graphql
type Query {
  posts(first: Int!, after: String): PostConnection!   # first = taille de page, after = cursor
}

type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
}
type PostEdge {
  cursor: String!        # jeton opaque pour la position de CE node
  node: Post!            # l'élément réel
}
type PageInfo {
  endCursor: String      # à renvoyer comme 'after' pour la page suivante
  hasNextPage: Boolean!  # pour que le client sache quand s'arrêter
}
```

```js
// resolver : récupère UNE ligne supplémentaire pour calculer hasNextPage à moindre coût
const rows = await db.posts.find({ after: args.after, limit: args.first + 1 });
const hasNextPage = rows.length > args.first;
const page = rows.slice(0, args.first);
return {
  edges: page.map((p) => ({ node: p, cursor: encodeCursor(p.id) })),
  pageInfo: { endCursor: page.at(-1) && encodeCursor(page.at(-1).id), hasNextPage },
};
```

Le cursor est **opaque** — généralement un base64 de la clé de tri — afin que les clients le traitent comme un jeton, pas comme un nombre.

## Pourquoi c'est important

Choisir entre offset et cursor montre que vous comprenez la **cohérence en cas d'écritures concurrentes** et les **performances sur les pages profondes**. Connaître la forme des connections Relay compte, car les clients Apollo/Relay disposent d'une gestion de cache intégrée pour elle.

Offset contre cursor

Les connections Relay

Pourquoi c'est important

Questions connexes