GraphQL Pagination
Shallow Pagination VS Deep Pagination
The story
Hi friends! As I usually say, there is always a story behind a blog article, and this one is a tale as old as Papyrus, I’d say. Don’t worry. This piece is not about the history of paper but rather the evolution from paper rolls into paginated books and, more specifically, the next step in this evolutionary process, the digital pages.
Pagination, pagination, pagination. It’s like a spell we all have to cast at some point. And there are so many variations to this spell and so many different wands you could use to perform it…, that it gets confusing and even overwhelming for us wizards, I mean, developers.
This article will discuss pagination in the GraphQL kingdom and explain its two dimensions. I’ve come to call these dimensions: Shallow and Deep Pagination because of the depth they go and the pagination surface they cover.
What is Pagination?
Pagination, or paging, is breaking down large data sets into smaller chunks we call a page, just like in the good old books. We read or consume one page or subset at a time. I wonder how they even bookmarked the long scrolls back in those days before books came into the picture. 🤔
Nowadays, for digital pages, UX presents paginated data all the time in many different forms, for example:
- The Infinite scroll, here it feels like there is no pagination, but there is. In this case, you don’t need to click any button to load more data. You simply scroll down. The downside of this option is the lack of information regarding the data set size and current location.
But this all happens in the UI, and we’re here to talk backend pagination, how to implement and offer backend pagination for the UI to show it in a user-friendly and efficient way because pagination is also a way to improve the performance and loading speed of the pages in your applications.
What is Pagination in GraphQL?
It is the same, except GraphQL is in the middle to help mitigate the lack of paginated downstream services.
With GraphQL in the middle, we encounter two ways of implementing pagination. I call them Shallow Pagination and Deep Pagination.
The Terms Shallow and Deep in Other Pagination Contexts
I have found the term Deep used before to refer to pagination. But instead, it alludes to the start offset of the pagination query. For example, deep paging would refer to a distant page number, like asking to return ten items starting at 1,000,000. That would yield items 1,000,000 to 1,000,009.
But this is not the meaning we’ll be giving these terms in this article. We’ll instead use them to refer to how deep will a paginated request in GraphQL go.
I’m sorry for overloading these terms here. Looking at the following diagram, you’ll know it’s worth it. It shows the basic idea of what they are and what areas they cover.
Deep Pagination
In the previous diagram, we can see the life cycle of an end-to-end paginated request. The client application sends a paginated request to GraphQL. This request looks something like this:
Then in GraphQL, we send another paginated request to the underlying REST API. This request looks something like this:
The request comes back from the REST API with ONLY the subset of data we need, and GraphQL sends it back to the client application. I call this dimension Deep Pagination because the pagination goes deep down to the downstream API request. It is the most efficient way to do pagination in GraphQL. It keeps us from loading big datasets that jeopardize the client application’s performance.
Shallow Pagination
Now, let’s say your downstream REST API is not paginated. Meaning it does not offer pagination options in the request. Believe it or not, this is a frequent scenario. But don’t despair; GraphQL is here to help. You can offer out-of-the-box pagination at the GraphQL server level to improve the client application’s performance.
In this scenario, things play out differently. GraphQL gets a paginated request from the client application. But GraphQL won’t send a paginated request to the underlying REST API because this is not supported. Instead, GraphQL will send a non-paginated request to the REST API, and the REST API will return the entire dataset at once. Then GraphQL will process this significant response and paginate these results for the client app, and instead of sending the whole dataset, it sends back ONLY the chunk of data the application requested.
I’ve called it Shallow Pagination because, in reality, GraphQL does its magic spell, loads the whole dataset, does the pagination itself, and returns only the requested subset of data. The data partitioning in chunks is happening at the GraphQL server level. It does not propagate any deeper than that.
The performance of the paginated query to GraphQL will depend heavily on the performance of the request to the underlying REST API. Some APIs provide pagination options, and some don’t, but the beauty of GraphQL allows us to have pagination regardless.
Deep Pagination would be ideal, but it may or may not be possible or available. But regardless, we can easily offer Shallow Pagination at the GraphQL server level. Shallow Pagination is better than no pagination.
The End
Alas, we’ve reached the end of this scroll. Or have we? Keep tuned for specific details of how we offer cursor-based pagination out-of-the-box in GraphQL.
