What is Cursor Pagination: Explanation and Example

Cursor pagination is a technique to split large sets of data into smaller parts using a cursor that marks the position in the data. Instead of page numbers, it uses a unique identifier from the last item fetched to get the next set, making it efficient and reliable for APIs.

How It Works

Cursor pagination works like a bookmark in a book. Imagine you are reading a long story and want to stop at a certain page. Instead of remembering the page number, you place a bookmark on the last sentence you read. When you come back, you start reading right after that bookmark.

In APIs, the cursor is this bookmark. It usually holds a unique ID or timestamp of the last item you received. When you ask for more data, you send this cursor back to the server, which then returns the next items after that cursor. This avoids problems like missing or repeating items if the data changes while you are paging through it.

Example

This example shows a simple Python function simulating cursor pagination over a list of items.

python

def get_items_after_cursor(items, cursor=None, limit=3):
    start_index = 0
    if cursor is not None:
        try:
            start_index = items.index(cursor) + 1
        except ValueError:
            start_index = 0
    return items[start_index:start_index + limit]

# Sample data
items = ['a', 'b', 'c', 'd', 'e', 'f', 'g']

# First page (no cursor)
page1 = get_items_after_cursor(items)
# Use last item of page1 as cursor for next page
cursor = page1[-1] if page1 else None
page2 = get_items_after_cursor(items, cursor=cursor)

print('Page 1:', page1)
print('Page 2:', page2)

Output

Page 1: ['a', 'b', 'c']
Page 2: ['d', 'e', 'f']

When to Use

Use cursor pagination when you need to handle large or changing data sets efficiently. It is especially useful in APIs where data can be added or removed while users are browsing, like social media feeds or product listings.

Cursor pagination avoids issues like skipping or repeating items that can happen with simple page number pagination. It also performs better with large data because it doesn't require counting or skipping many records.

Key Points

• Cursor pagination uses a unique marker (cursor) to track position.
• It is more reliable than page numbers when data changes.
• It improves performance for large data sets.
• Commonly used in APIs for continuous scrolling or infinite feeds.

Key Takeaways

Cursor pagination uses a unique cursor to mark the last item fetched for the next request.

It prevents missing or repeating data when the underlying data changes during pagination.

Ideal for APIs with large or frequently updated data sets like social feeds or product catalogs.

Cursor pagination is more efficient and reliable than traditional page number pagination.