Skip to content

Commit

Permalink
Merge pull request #1604 from appwrite/update-pagination-doc
Browse files Browse the repository at this point in the history
Docs: clarify no hard limit on pagination size
  • Loading branch information
stnguyen90 authored Jan 6, 2025
2 parents e301138 + 6d12013 commit 40bfdd1
Showing 1 changed file with 9 additions and 9 deletions.
18 changes: 9 additions & 9 deletions src/routes/docs/products/databases/pagination/+page.markdoc
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,15 @@ As your database grows in size, you'll need to paginate results returned.
Pagination improves performance by returning a subset of results that match a query at a time, called a page.

By default, list operations return 25 items per page, which can be changed using the `Query.limit(25)` operator.
Beware that **large pages can degrade performance**.
There is no hard limit on the number of items you can request. However, beware that **large pages can degrade performance**.

# Offset pagination {% #offset-pagination %}

Offset pagination works by dividing documents into `M` pages containing `N` documents.
Every page is retrieved by skipping `offset = M * (N - 1)` items and reading the following `M` pages.

Using `Query.limit()` and `Query.offset()` you can achieve offset pagination.
With `Query.limit()` you can define how many documents can be returned from one request.
Using `Query.limit()` and `Query.offset()` you can achieve offset pagination.
With `Query.limit()` you can define how many documents can be returned from one request.
The `Query.offset()` is number of records you wish to skip before selecting records.

{% multicode %}
Expand Down Expand Up @@ -143,15 +143,15 @@ suspend fun main() {
{% /multicode %}

{% info title="Drawbacks" %}
While traditional offset pagination is familiar, it comes with some drawbacks.
The request gets slower as the number of records increases because the database has to read up to the offset number `M * (N - 1)` of rows to know where it should start selecting data.
While traditional offset pagination is familiar, it comes with some drawbacks.
The request gets slower as the number of records increases because the database has to read up to the offset number `M * (N - 1)` of rows to know where it should start selecting data.
If the data changes frequently, offset pagination will also produce **missing and duplicate** results.
{% /info %}

# Cursor pagination {% #cursor-pagination %}

The cursor is a unique identifier for a document that points to where the next page should start.
After reading a page of documents, pass the last document's ID into the `Query.cursorAfter(lastId)` query method to get the next page of documents.
The cursor is a unique identifier for a document that points to where the next page should start.
After reading a page of documents, pass the last document's ID into the `Query.cursorAfter(lastId)` query method to get the next page of documents.
Pass the first document's ID into the `Query.cursorBefore(firstId)` query method to retrieve the previous page.

{% multicode %}
Expand Down Expand Up @@ -288,10 +288,10 @@ suspend fun main() {

# When to use what? {% #when-to-use %}
Offset pagination should be used for collections that rarely change.
Offset paginations allow you to create indicator of the current page number and total page number.
Offset paginations allow you to create indicator of the current page number and total page number.
For example, a list with up to 20 pages or static data like a list of countries or currencies.
Using offset pagination on large collections and frequently updated collections may result in slow performance and **missing and duplicate** results.

Cursor pagination should be used for frequently updated collections.
It is best suited for lazy-loaded pages with infinite scrolling.
It is best suited for lazy-loaded pages with infinite scrolling.
For example, a feed, comment section, chat history, or high volume datasets.

0 comments on commit 40bfdd1

Please sign in to comment.