Relay-Style Connections
You'll learn to
- -Read the Connection shape: edges, node, cursor and pageInfo
- -Page through seven users, three at a time, by passing endCursor back as after
- -Explain why the wrapper exists instead of a plain list with a separate cursor
GraphQL needs pagination for the same reason REST does: an unbounded list does not scale. But a plain [User!]! list has no natural place to attach paging information, such as a cursor for the next page. The Relay Connection specification is the standard structure the GraphQL world settled on to solve that. (Relay is a GraphQL client library from Facebook, and the spec took its name from it.)
An Analogy: Postcards in a Photo Album
Imagine a photo album where each photo has a small numbered sticker on it, and the cover has a note saying "there are more pages" and the sticker of the last photo shown. To continue, you say "start after sticker 3". The sticker on each photo is its cursor, the cover note is the page info, and the photo plus its sticker is an edge.
The Connection Shape
type UserConnection {
edges: [UserEdge!]!
pageInfo: PageInfo!
}
type UserEdge {
node: User!
cursor: String!
}
type PageInfo {
hasNextPage: Boolean!
hasPreviousPage: Boolean!
endCursor: String
startCursor: String
}
type Query {
users(first: Int, after: String): UserConnection!
}- -edges: a wrapper around each result, pairing the actual item (node) with its own cursor, a stable position marker for that item, as in REST cursor pagination.
- -node: the actual User the client wants.
- -pageInfo: facts about the page as a whole: whether more pages exist in either direction, and the cursors to fetch them.
- -first and after: the standard arguments for paging forward. last and before page backward.
The demo builds a small connection over seven users and walks through it three at a time. Each call passes the previous page's endCursor as after, until hasNextPage is false.
Why Not Just a Plain Array Plus a Cursor Argument?
query {
users(first: 10, after: "cursor_abc") {
edges {
node { id name }
cursor
}
pageInfo {
hasNextPage
endCursor
}
}
}A simpler users(first: Int, after: String): [User!]! returns a bare array, and cannot say anywhere in its own response whether there is another page or which cursor to use next. That information would have to live elsewhere, breaking the self-describing property GraphQL responses otherwise have. The wrapper exists to carry paging metadata as a queryable part of the schema, and a cursor per edge lets a client resume from any item, not only a page boundary.
The structure is more verbose than a plain array, a real and deliberate trade-off. The ecosystem converged on it because the alternative, ad hoc paging fields invented per API or per field, was worse for tooling and for client libraries.
Interview Signal is part of Pro
See a real weak answer next to a real strong one for this exact topic.
Quiz is part of Pro
Test what you just read with a short quiz, and bank the XP.
Design Relay Connections in the API Design Lab's GraphQL Mastery act.
Discussion0
Join the Discussion
Sign in to leave comments, reply to others, or like insights.
No comments yet. Be the first to start the thread!