Pagination_
Implement pagination for large data sets in Appwrite VectorsDB. Explore techniques for splitting and displaying documents across multiple pages.
3 min read
As your collection grows in size, you'll need to paginate the documents returned. Pagination improves performance by returning a subset of documents that match a query at a time, called a page.
By default, list operations return 25 documents per page, which can be changed using the Query.limit() query method. There is no hard limit on the number of documents you can request. However, beware that large pages can degrade performance.
Offset pagination
Offset pagination divides documents into pages of N documents each. To read page number P, skip offset = N * (P - 1) documents, then read the next N.
Using Query.limit() and Query.offset() you can achieve offset pagination. With Query.limit() you define how many documents can be returned from one request. The Query.offset() is the number of documents you wish to skip before selecting documents.
While traditional offset pagination is familiar, it comes with some drawbacks. The request gets slower as the offset increases because the database has to skip over all the preceding documents before it can start selecting data. If the data changes frequently, offset pagination will also produce missing and duplicate results.
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. Pass the first document's ID into the Query.cursorBefore(firstId) query method to retrieve the previous page.
When to use what?
Offset pagination should be used for collections that rarely change. Offset pagination lets you build an indicator of the current page number and the total page count. For example, a list with up to 20 pages or static data like a list of countries or currencies. Using offset pagination on large 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. For example, a feed, comment section, chat history, or high volume datasets.
Cache list responses
You can cache list responses by passing a ttl (time-to-live) value in seconds. Subsequent identical requests return the cached result until the TTL expires. The cache is permission-aware, so users with different roles never see each other's cached data.
Set ttl between 1 and 86400 (24 hours). The default is 0 (caching disabled). The response includes an X-Appwrite-Cache header with value hit or miss.
Document writes do not invalidate the cache, so cached responses may contain stale data until the TTL expires. Use a short TTL for collections that change often, or skip caching entirely when you always need the latest documents.
Was this page helpful?
Share what worked or what we should fix. Once approved, our agents automatically apply suggested updates to the docs.