Pagination

This is the documentation of the GraphQL Library version 7. For the long-term support (LTS) version 5, refer to GraphQL Library version 5 LTS.

The Neo4j GraphQL Library offers two mechanisms for pagination:

  • Offset-based pagination - Pagination based on offsets, often associated with navigation via pages.

  • Cursor-based pagination - Pagination based on cursors, often associated with infinitely-scrolling applications.

Offset-based pagination

Offset-based pagination, often associated with navigation via pages, can be achieved through the use of the offset and limit options available when querying for data.

Using the following type definition:

type User @node {
    name: String!
}

Fetch the first page of 10 by executing:

query {
    users(limit: 10) {
        name
    }
}

And then on subsequent calls, introduce the offset argument and increment it by 10 on each call.

Fetch the second page with:

query {
    users(offset: 10, limit: 10) {
        name
    }
}

Fetch the third page with:

query {
    users(offset: 20, limit: 10) {
        name
    }
}

And so on.

Total number of pages

You can fetch the total number of records for a certain type using its count query, and then divide that number by your entries per page in order to calculate the total number of pages. This determines what the last page is, and whether there is a next page.

See Count queries for details on how to execute these queries.

Paginating relationship fields

Say that in addition to the User type above, there is also a Post type which a User has many of. You can also fetch a User and then paginate through their posts:

query {
  users(where: { name: { eq: "Billy" } }) {
    name
    posts(offset: 20, limit: 10) {
      content
    }
  }
}

Cursor-based pagination

On relationship fields, you are able to take advantage of cursor-based pagination, which is often associated with infinitely-scrolling applications.

Using the following type definition:

type User @node {
    name: String!
    posts: [Post!]! @relationship(type: "HAS_POST", direction: OUT)
}

type Post @node {
    content: String!
}

If you wanted to fetch the posts of user "John Smith" 10 at a time, you would first fetch 10:

query {
  users(where: { name: { eq: "John Smith" } }) {
    name
    postsConnection(first: 10) {
      edges {
        node {
          content
        }
      }
      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
}

In the return value, if hasNextPage is true, you would pass endCursor into the next query of 10. You can do this with a variable, for example, $after in the following query:

query Users($after: String) {
    users(where: { name: { eq: "John Smith"} }) {
        name
        postsConnection(first: 10, after: $after) {
            edges {
                node {
                    content
                }
            }
            pageInfo {
                endCursor
                hasNextPage
            }
        }
    }
}

You may continue until hasNextPage is false in the return - this is when you have reached the end of the data.

totalCount

The Connection fields also offer a totalCount field which can be used to calculate page numbers. This is useful if you want to paginate by cursor but use page numbers in your application.

Add the totalCount field which returns the total number of results matching the filter used, for example:

query Users {
  users(where: { name: { eq: "John Smith" } }) {
    name
    postsConnection(first: 10) {
      edges {
        node {
          content
        }
      }
      pageInfo {
        endCursor
        hasNextPage
      }
      totalCount
    }
  }
}