Pagination

Control how many results are returned and navigate through large datasets efficiently.

Overview

Pagination - Retrieve data in manageable chunks for better performance and user experience. All list operations support pagination with consistent metadata.

---

Pagination Parameters

Use either limit/offset or page/per_page approach:

Using limit/offset:

{
  "op": "db.find",
  "collection": "products",
  "filter": { "status": "active" },
  "limit": 50,
  "offset": 0,
  "sort": "_created_at desc"
}

Using page/per_page:

{
  "op": "db.find",
  "collection": "products",
  "filter": { "status": "active" },
  "page": 1,
  "per_page": 50,
  "sort": "_created_at desc"
}

Parameters:

• limit / per_page - Number of documents to return (default: 100, max: 1000)
• offset - Number of documents to skip (default: 0)
• page - Page number, 1-based (default: 1)
• sort - Sort order for consistent results

Important: Use parameters in pairs - either limit/offset OR page/per_page, not both. If both provided, page/per_page takes precedence.

---

Response Structure

Every paginated response includes data and pagination metadata:

{
  "data": [
    {
      "_key": "doc_123",
      "name": "Product 1",
      "price": 29.99
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total_pages": 10,
      "size": 500,
      "count": 50,
      "has_next": true,
      "next_page": 2,
      "has_prev": false,
      "prev_page": null,
      "page_showing_start": 1,
      "page_showing_end": 50
    }
  }
}

Pagination metadata:

• page - Current page number
• per_page - Documents per page
• total_pages - Total number of pages
• size - Total documents matching query
• count - Documents in current response
• has_next - More pages available
• next_page - Next page number (null if none)
• has_prev - Previous pages available
• prev_page - Previous page number (null if none)
• page_showing_start - First document position
• page_showing_end - Last document position