Cursor-based pagination with connections

The simplest way to expose a relationship between objects is a field returning a plural List type, but list fields that may return a lot of data should be paginated, starting with slicing arguments such as friends(first: 2). Offset-based pagination like friends(first: 2, offset: 2) has performance and security downsides on larger data sets, and offsets become ambiguous when records are inserted between requests, so cursor-based pagination — friends(first: 2, after: $friendCursor) — is the recommended model; opaque cursors can still encode an offset or ID internally, and base64-encoding them reinforces that clients must not rely on their format. Because a cursor is a property of the connection rather than the object, the field returns edges, each holding a cursor and the underlying node, which is also the natural place for edge-specific data like friendship time. A connection object wraps the edges with information about the connection itself: totalCount, and a pageInfo object with startCursor, endCursor, and hasNextPage so clients know when the list ends without an extra request. The Relay project publishes a formal cursor connection specification worth following whether or not you use Relay. Scope: GraphQL. Reviewed October 4, 2026.