Offset Pagination in GraphQL: What It Is and How It Works

Offset pagination in GraphQL is a way to fetch a subset of data by specifying a starting point (offset) and how many items to retrieve (limit). It works like flipping pages in a book by skipping a number of items and then taking the next set. This method helps manage large lists efficiently in queries.

How It Works

Offset pagination works by telling the server to skip a certain number of items and then return the next set of items. Imagine you have a long list of books and you want to see them 10 at a time. You start by asking for the first 10 books (offset 0, limit 10). To see the next 10, you skip the first 10 (offset 10, limit 10), and so on.

This method is simple and easy to understand because you just count how many items to skip and how many to take. However, it can be slower for very large lists because the server has to count and skip items each time.

Example

This example shows a GraphQL query using offset pagination to get 5 users starting from the 11th user.

graphql

query GetUsers($offset: Int!, $limit: Int!) {
  users(offset: $offset, limit: $limit) {
    id
    name
  }
}

# Variables:
# {
#   "offset": 10,
#   "limit": 5
# }

Output

{
  "data": {
    "users": [
      { "id": "11", "name": "User 11" },
      { "id": "12", "name": "User 12" },
      { "id": "13", "name": "User 13" },
      { "id": "14", "name": "User 14" },
      { "id": "15", "name": "User 15" }
    ]
  }
}

When to Use

Use offset pagination when you want a simple way to load data in chunks, like showing pages of search results or lists of items. It works well if your data doesn't change often and you want users to jump to any page quickly.

However, if your data changes frequently or you want better performance with large datasets, cursor-based pagination might be better. Offset pagination can be slower and less reliable in those cases.

Key Points

• Offset pagination uses offset and limit to fetch data slices.
• It is easy to implement and understand.
• Performance can degrade with large offsets.
• Best for stable datasets and simple paging needs.
• Cursor pagination is often preferred for dynamic or large data.

Key Takeaways

Offset pagination fetches data by skipping a set number of items and then taking the next set.

It is simple and good for stable data with predictable paging.

Performance may slow down with large offsets due to skipping many items.

Use offset pagination for basic paging like page numbers in lists.

Consider cursor pagination for large or frequently changing data.