Pagination

Pagination lets you iterate through large sets returned by a query.

This guide covers default pagination, customizing page size, and accessing paginated results within FQL queries.

Default pagination

Fauna automatically paginates result sets with 16 or more elements:

// Returns all `Product` collection documents.
// The collection contains more than 16 documents.
Product.all()

If a set is paginated and a subsequent page is available, the result includes an after cursor:

{
  // The returned set contains 16 elements.
  data: [
    {
      id: "393605620096303168",
      coll: Product,
      ts: Time("2099-03-28T12:53:40.750Z"),
      name: "limes",
      ...
    },
    {
      id: "393605620102594624",
      coll: Product,
      ts: Time("2099-03-28T12:53:40.750Z"),
      name: "cilantro",
      ...
    }
  ],
 // Use the `after` cursor to get the next page of results.
  after: "hdWCxmd..."
}

Iterate through pages

Reference: Set.paginate()

To iterate through paginated results, pass the after cursor to Set.paginate():

Set.paginate("hdWCxmd...")

The Fauna client drivers also include methods for automatically iterating through pages. See:

Customize page size

Reference: pageSize()

Use pageSize() to change the maximum number of elements per page:

// Calls `pageSize()` with a size of `2`.
Product.all().pageSize(2)
{
  // The returned set contains two elements or fewer.
  data: [
    {
      id: "393605620096303168",
      coll: Product,
      ts: Time("2099-03-28T12:53:40.750Z"),
      name: "limes",
      ...
    },
    {
      id: "393605620102594624",
      coll: Product,
      ts: Time("2099-03-28T12:53:40.750Z"),
      name: "cilantro",
      ...
    }
  ],
  after: "hdaExad..."
}

pageSize() should typically be the last method call in an FQL statement. pageSize() only affects the rendering of a set, not subsequent operations. Methods chained to pageSize() access the entire calling set, not a page of results.

Access pages and cursors within a query

Reference: paginate()

If you need to access an after cursor or paginated results within an FQL query, use paginate():

Product.all().pageSize(2).paginate()

For example, you can use paginate() to return the after cursor for use as a URL in a client application.

Alternatively, you can use paginate() to iteratively update a large set of collection documents over several transactions. For an example, see the paginate() reference docs.

Considerations for using paginate()

paginate() accepts an optional argument to control page size. In most cases, you should not use paginate() in place of pageSize(). Unlike pageSize(), paginate():

  • Returns an Object, not a Set.

  • Uses eager loading and fetches results instantly, even if the results aren’t returned or used. This can produce slower and more wasteful queries.

  • Is not compatible with Fauna client driver pagination methods.

Cursor state and expiration

If a paginated set contains documents, the after cursor fetches historical snapshots of the documents at the time of the original query.

You can control the retention of document snapshots using the collection schema’s history_days field. An after cursor is valid for history_days plus 15 minutes. If history_days is 0 or unset, the cursor is valid for 15 minutes.

If a document’s snapshot is no longer available, a NullDoc is returned instead:

{
  data: [
    {
      id: "393605620096303168",
      coll: Product,
      ts: Time("2099-03-28T12:53:40.750Z"),
      name: "limes",
      ...
    },
    Product("401942927818883138") /* not found */
  ],
  after: "hdWCxmd..."
}
See Document history

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!