export const metadata = { title: "Relay vs Offset vs Traditional Pagination with GraphQL", description: "Learn the key differences between Relay, Offset, and Traditional pagination techniques using a GraphQL API.", openGraph: { title: "Relay vs Offset vs Traditional Pagination with GraphQL", description: "Learn the key differences between Relay, Offset, and Traditional pagination techniques using a GraphQL API.", }, twitter: { card: "summary_large_image", title: "Relay vs Offset vs Traditional Pagination with GraphQL", description: "Learn the key differences between Relay, Offset, and Traditional pagination techniques using a GraphQL API.", }, alternates: { canonical: "/p/pagination", }, }; import { P, H2, H3 } from "@/components/ui/typography"; import { PostLayout } from "@/app/components/Posts/PostLayout"; import { CustomLink } from "@/app/components/Posts/CustomComponents/CustomLink"; import { CustomImage as Image } from "@/app/components/Posts/CustomComponents/Image"; import { OffsetTable } from "./OffsetTable"; import { RelayTable } from "./RelayTable";

{" "}

Introduction

Pagination is crucial when working with large datasets. GraphQL APIs often support different styles of pagination to manage data retrieval efficiently. In this post, we'll explore three common techniques: Relay Pagination, Offset Pagination, and Traditional Pagination. Each has its pros, cons, and use cases.

{" "}

Offset Pagination

Offset pagination is a straightforward technique that uses page and pageSize (or limit) to determine which data to fetch. It's common in REST APIs and simple database queries.

Example: Offset Pagination with GraphQL

```graphql query GetCountries($page: Int!, $pageSize: Int!) { countries(page: $page, pageSize: $pageSize) { code name capital currency } pagination { total page pageSize totalPages } } ``` {" "}

With this approach, you specify which page you want and how many items per page:

```json { "page": 2, "pageSize": 10 } ``` {" "}

Pros and Cons of Offset Pagination

✅ Simple to implement and easy to understand.

✅ Works well with UI elements like page selectors.

❗️ Can lead to performance issues on large datasets.

❗️ Risk of missing or duplicated data if records change during pagination.

{" "}

Relay Pagination

Relay pagination is a cursor-based technique that ensures consistent data retrieval, even if records are added or removed during pagination. This method is ideal for dynamic datasets.

{" "}

Example: Relay Pagination with GraphQL

```graphql query GetCountries($first: Int, $after: String, $last: Int, $before: String) { countries(first: $first, after: $after, last: $last, before: $before) { edges { cursor node { code name capital currency } } pageInfo { hasNextPage endCursor hasPreviousPage startCursor } } } ``` {" "}

In this example, \`first\` controls the number of items to fetch, and \`after\` is a cursor that points to the starting position for the next set of data. For backwards pagination, you can use \`last\` and \`before\`.

```json { "first": 10, "after": "next-cursor-1" } ``` {" "}

Pros and Cons of Relay Pagination

✅ Efficient for large datasets and dynamic data updates.

✅ Prevents data duplication or gaps when records change.

✅ Supports bi-directional pagination (forward and backward).

❗️ More complex to implement than offset pagination.

❗️ Cursor format may vary between APIs.

{" "}

Traditional Pagination

Traditional pagination relies on sending \`page\` and \`pageSize\` values, similar to offset pagination but with simpler implementation. It's commonly seen in older APIs or custom-built systems.

{" "}

Example: Traditional Pagination with GraphQL

```typescript const currentPage = 3; const pageSize = 10; fetch('/api/countries', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ query: \`query GetCountries($page: Int!, $pageSize: Int!) { countries(page: $page, pageSize: $pageSize) { code name capital currency } }\`, variables: { page: currentPage, pageSize: pageSize } }), }) .then(response => response.json()) .then(data => console.log(data.data.countries)); ``` {" "}

Pros and Cons of Traditional Pagination

✅ Simple to integrate with UI elements like page numbers.

✅ Intuitive for users who are used to seeing page numbers.

❗️ Data can become inconsistent if records change between requests.

❗️ Less efficient for very large datasets.

{" "}

Key Differences

{" "}

Choosing the right pagination method depends on your data size, expected updates, and UI experience:

Relay Pagination: Best for large, dynamic datasets where consistency is critical.
Offset Pagination: Good for smaller datasets where simplicity is more important than performance.
Traditional Pagination: Ideal for user interfaces that need explicit page numbers.

{" "}

Live Examples

Relay Pagination Example

Here's a live example of Relay-style cursor-based pagination using the Countries API:

{" "}

Offset Pagination Example

And here's the same data using offset-based pagination:

{" "}

Conclusion

Understanding the differences between these pagination methods can improve both performance and user experience in your GraphQL applications. For large dynamic datasets, Relay pagination is often the best choice for scalability, while offset pagination provides simplicity for smaller applications.

{" "}

The examples above demonstrate how you can implement both approaches with a GraphQL API, allowing you to choose the most suitable method for your specific requirements.

{" "}

Have questions or want to share your pagination strategy? Feel free to connect with me!