Pagination is one of the most common problems that we have to solve when implementing our backend. Often, sets of data are too large to pass them directly to the consumer of our service.

Pagination solves this problem by giving the consumer the ability to fetch a set in chunks.

Connections

Connections are a standardized way to expose pagination to clients.

Instead of returning a list of entries, we return a Connection.

type Query {
  users(first: Int after: String last: Int before: String): UsersConnection
}

type UsersConnection {
  pageInfo: PageInfo!
  edges: [UsersEdge!]
  nodes: [User!]
}

type UsersEdge {
  cursor: String!
  node: User!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

You can learn more about this in the GraphQL Cursor Connections Specification.

Note: Connections are often associated with cursor-based pagination, due to the use of a cursor. Nonetheless, since the specification describes the cursor as opaque, it can be used to facilitate an offset as well.

Definition

Adding pagination capabilties to our fields is a breeze. All we have to do is add the UsePaging middleware.

public class Query
{
    [UsePaging]
    public IEnumerable<User> GetUsers([Service] IUserRespository repository)
        => repository.GetUsers();
}

If we need to specify the concrete node type of our pagination, we can do so by passing a Type as the constructor argument [UsePaging(typeof(User))].

For the UsePaging middleware to work, our resolver needs to return an IEnumerable<T> or an IQueryable<T>. The middleware will then apply the pagination arguments to what we have returned. In the case of an IQueryable<T> this means that the pagination operations can be directly translated to native database queries.

Naming

The name of the Connection and Edge type is automatically inferred from the field name. If our field is called users, a UsersConnection and UsersEdge type is automatically generated.

We can also specify a custom name for our Connection like the following.

public class Query
{
    [UsePaging(ConnectionName = "CustomUsers")]
    public IEnumerable<User> GetUsers([Service] IUserRespository repository)
    {
        // Omitted code for brevity
    }
}

The strings Connection and Edge are automatically appended to this user specified value to form the names of the Connection and Edge types.

Options

We can define a number of options on a per-field basis.

In the Annotation-based approach we can define these options using properties on the [UsePaging] attribute.

[UsePaging(MaxPageSize = 100)]

Learn more about the possible PagingOptions

Customization

If we need more control over the pagination process we can do so, by returning a Connection<T>.

public class Query
{
    [UsePaging]
    public Connection<User> GetUsers(string? after, int? first, string sortBy)
    {
        // get users using the above arguments
        IEnumerable<User> users = null;

        var edges = users.Select(user => new Edge<User>(user, user.Id))
                            .ToList();
        var pageInfo = new ConnectionPageInfo(false, false, null, null);

        var connection = new Connection<User>(edges, pageInfo,
                            ct => ValueTask.FromResult(0));

        return connection;
    }
}

Total count

Sometimes we might want to return the total number of pageable entries.

For this to work we need to enable the IncludeTotalCount flag on the UsePaging middleware.

[UsePaging(IncludeTotalCount = true)]

This will add a new field called totalCount to our Connection.

type UsersConnection {
  pageInfo: PageInfo!
  edges: [UsersEdge!]
  nodes: [User!]
  totalCount: Int!
}

If our resolver returns an IEnumerable<T> or an IQueryable<T> the totalCount will be automatically computed, if it has been specified as a subfield in the query.

If we have customized our pagination and our resolver now returns a Connection<T>, we have to explicitly declare how the totalCount value is computed.

var connection = new Connection<User>(
    edges,
    pageInfo,
    getTotalCount: cancellationToken => ValueTask.FromResult(0));

Offset Pagination

Note: While we support offset-based pagination, we highly encourage the use of Connections instead. Connections provide an abstraction which makes it easier to switch to another pagination mechanism later on.

Besides Connections we can also expose a more traditional offset-based pagination.

type Query {
  users(skip: Int take: Int): UserCollectionSegment
}

type UserCollectionSegment {
  items: [User!]
  pageInfo: CollectionSegmentInfo!
}

type CollectionSegmentInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
}

Definition

To add offset-based pagination capabilties to our fields we have to add the UseOffsetPaging middleware.

public class Query
{
    [UseOffsetPaging]
    public IEnumerable<User> GetUsers([Service] IUserRespository repository)
        => repository.GetUsers();
}

If we need to specify the concrete node type of our pagination, we can do so by passing a Type as the constructor argument [UseOffsetPaging(typeof(User))].

For the UseOffsetPaging middleware to work, our resolver needs to return an IEnumerable<T> or an IQueryable<T>. The middleware will then apply the pagination arguments to what we have returned. In the case of an IQueryable<T> this means that the pagination operations can be directly translated to native database queries.

Options

We can define a number of options on a per-field basis.

In the Annotation-based approach we can define these options using properties on the [UseOffsetPaging] attribute.

[UseOffsetPaging(MaxPageSize = 100)]

Learn more about the possible PagingOptions

Customization

If we need more control over the pagination process we can do so, by returning a CollectionSegment<T>.

public class Query
{
    [UseOffsetPaging]
    public CollectionSegment<User> GetUsers(int? skip, int? take, string sortBy)
    {
        /// get users using the above arguments
        IEnumerable<User> users = null;

        var pageInfo = new CollectionSegmentInfo(false, false);

        var collectionSegment = new CollectionSegment<User>(
            users,
            pageInfo,
            ct => ValueTask.FromResult(0));

        return collectionSegment;
    }
}

Total count

Sometimes we might want to return the total number of pageable entries.

For this to work we need to enable the IncludeTotalCount flag on the UseOffsetPaging middleware.

[UseOffsetPaging(IncludeTotalCount = true)]

This will add a new field called totalCount to our CollectionSegment.

type UserCollectionSegment {
  pageInfo: CollectionSegmentInfo!
  items: [User!]
  totalCount: Int!
}

If our resolver returns an IEnumerable<T> or an IQueryable<T> the totalCount will be automatically computed, if it has been specified as a subfield in the query.

If we have customized our pagination and our resolver now returns a CollectionSegment<T>, we have to explicitly declare how the totalCount value is computed.

var collectionSegment = new CollectionSegment<User>(
    items,
    pageInfo,
    getTotalCount: cancellationToken => ValueTask.FromResult(0));

Providers

The UsePaging and UseOffsetPaging middleware provide a unified way of applying pagination to our resolvers. Depending on the data source used within the resolver the pagination mechanism needs to be different though. Hot Chocolate includes so called paging providers that allow us to use the same API, e.g. UsePaging, but for different data sources, e.g. MongoDB and SQL.

Paging providers can be registered using various methods on the IRequestExecutorBuilder. For example the MongoDB paging provider can be registered like the following.

services
    .AddGraphQLServer()
    .AddMongoDbPagingProviders();

Consult the specific integration documentation for more details

When registering paging providers we can name them to be able to explicitly reference them.

services
    .AddGraphQLServer()
    .AddMongoDbPagingProviders(providerName: "MongoDB");

They can then be referenced like the following.

[UsePaging(ProviderName = "MongoDB")]
public IEnumerable<User> GetUsers()

If no ProviderName is specified, the correct provider is selected based on the return type of the resolver. If the provider to use can't be inferred from the return type, the first (default) provider is used automatically. If needed we can mark a paging provider as the explicit default.

services
    .AddGraphQLServer()
    .AddMongoDbPagingProviders(defaultProvider: true);

If no paging providers have been registered, a default paging provider capable of handling IEnumerable<T> and IQueryable<T> is used.

PagingOptions

PagingOptions can either be defined on a per-field basis or globally.

The following options can be configured.

Pagination defaults

If we want to enforce consistent pagination defaults throughout our app, we can do so by setting the global PagingOptions.

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services
            .AddGraphQLServer()
            .SetPagingOptions(new PagingOptions
            {
                MaxPageSize = 100
            });
    }
}

Learn more about possible PagingOptions

Types of pagination

In this section we will look at the most common pagination approaches and their downsides. There are mainly two concepts we find today: offset-based and cursor-based pagination.

Note: This section is intended as a brief overview and should not be treated as a definitive guide or recommendation.

Offset Pagination

Offset-based pagination is found in many server implementations whether the backend is implemented in SOAP, REST or GraphQL.

It is so common, since it is the simplest form of pagination we can implement. All it requires is an offset (start index) and a limit (number of entries) argument.

SELECT * FROM Users
ORDER BY Id
LIMIT %limit OFFSET %offset

Problems

But whilst offset-based pagination is simple to implement and works relatively well, there are also some problems:

• Using OFFSET on the database-side does not scale well for large datasets. Most databases work with an index instead of numbered rows. This means the database always has to count offset + limit rows, before discarding the offset and only returning the requested number of rows.

• If new entries are written to or removed from our database at high frequency, the offset becomes unreliable, potentially skipping or returning duplicate entries.

Cursor Pagination

Contrary to the offset-based pagination, where we identify the position of an entry using an offset, cursor-based pagination works by returning the pointer to the next entry in our pagination.

To understand this concept better, let's look at an example: We want to paginate over the users in our application.

First we execute the following to receive our first page:

SELECT * FROM Users
ORDER BY Id
LIMIT %limit

%limit is actually limit + 1. We are doing this to know wether there are more entries in our dataset and to receive the cursor of the next entry (in this case its Id). This additional entry will not be returned to the consumer of our pagination.

To now receive the second page, we execute:

SELECT * FROM Users
WHERE Id >= %cursor
ORDER BY Id
LIMIT %limit

Using WHERE instead of OFFSET is great, since now we can leverage the index of the Id field and the database does not have to compute an offset.

For this to work though, our cursor needs to be unique and sequential. Most of the time the Id field will be the best fit.

But what if we need to sort by a field that does not have the aforementioned properties? We can simply combine the field with another field, which has the needed properties (like Id), to form a cursor.

Let's look at another example: We want to paginate over the users sorted by their birthday.

After receiving the first page, we create a combined cursor, like "1435+2020-12-31" (Id + Birthday), of the next entry. To receive the second page, we convert the cursor to its original values (Id + Birthday) and use them in our query:

SELECT * FROM Users
WHERE (Birthday >= %cursorBirthday
OR (Birthday = %cursorBirthday AND Id >= %cursorId))
ORDER BY Birthday, Id
LIMIT %limit

Problems

Even though cursor-based pagination can be more performant than offset-based pagination, it comes with some downsides as well:

• When using WHERE and ORDER BY on a field without an index, it can be slower than using ORDER BY with OFFSET.

• Since we now only know of the next entry, there is no more concept of pages. If we have a feed or only Next and Previous buttons, this works great, but if we depend on page numbers, we are in a tight spot.