Set.paginate()

Gets a page of paginated results using an after cursor.

Signature

Set.paginate(cursor: String): Page<any>

Set.paginate(cursor: String, count: Number): Page<any>

Description

The Set.paginate() method gets a page of paginated results using an after cursor.

The default page size of 16 can be changed using the set.paginate() or set.pageSize() method, in the range 1 to 16000 (inclusive).

The cursor is stable in the sense that pagination through a set is done for a fixed snapshot time, giving you a view of your data as it existed across the whole set at the instant you started paginating. For example, given set [a, b, c] when you start paginating, one item at a time, even if you delete item c after you started reading the set, item c is returned.

The exception is if the history is no longer available for the deleted item because history_days is set to the default value of 0 or is less than the minimum valid time needed. In that case, the deleted item is not returned with the paginated results and an error is returned:
Requested timestamp <time> less than minimum allowed timestamp..

A cursor is valid for history_days plus 15 minutes.

Parameters

Parameter Type Required Description

cursor

String

Yes

Encoded string representing a pagination cursor, a Base64-encoded object representing the state of a Set during pagination.

count

Number

Number of Set values to return in a page.

Return value

Type Description

Page

An object with:

data

Set values as an Array or page.

after

A cursor that is included when there are more pages available. The cursor is valid for history_days plus 15 minutes.

Examples

Basic example

  1. The page includes a pagination cursor:

    Product.all().pageSize(2) { name }
    {
  data: [
    {
      name: "cups"
    },
    {
      name: "pinata"
    }
  ],
  after: "hdWC1Y..."
}

  2. Use the cursor to access the next page:

    Set.paginate("hdWC1Y...")
    {
  data: [
    {
      name: "pizza"
    },
    {
      name: "avocados"
    }
  ],
  after: "hdWC1Y..."
}

Paginate in reverse

Paginated queries don’t include a before cursor. Instead, you can use a range search and document IDs or other unique field values to paginate in reverse. For example:

  1. Run an initial paginated query:

    Product.all().pageSize(2)
    {
  data: [
    {
      id: "111",
      coll: Product,
      ts: Time("2099-08-16T14:00:59.075Z"),
      name: "cups",
      ...
    },
    {
      id: "222",
      coll: Product,
      ts: Time("2099-08-16T14:00:59.075Z"),
      name: "donkey pinata",
      ...
    }
  ],
  after: "hdW..."
}

  2. Page forward until you find the document you want to start reversing from:

    Set.paginate("hdW...")

    Copy the ID of the document:

    {
  data: [
    {
      id: "333",
      coll: Product,
      ts: Time("2099-08-16T14:00:59.075Z"),
      name: "pizza",
      ...
    },
    {
      // Begin reverse pagination from this doc ID.
      id: "444",
      coll: Product,
      ts: Time("2099-08-16T14:00:59.075Z"),
      name: "avocados",
      ...
    }
  ],
  after: "hdW..."
}

  3. To reverse paginate, run the original query with:

    // "444" is the ID of the document to reverse from.
Product.all({ to: "444" }).reverse().pageSize(2)
    {
  data: [
    {
      // The results of the previous query are reversed.
      id: "444",
      coll: Product,
      ts: Time("2099-08-16T14:00:59.075Z"),
      name: "avocados",
      ...
    },
    {
      id: "333",
      coll: Product,
      ts: Time("2099-08-16T14:00:59.075Z"),
      name: "pizza",
      ...
    }
  ],
  after: "hdW..."
}

    To get historical snapshots of documents at the time of the original query, use an at expression:

    // Time of the original query.
let originalQueryTime = Time.fromString("2099-08-16T14:30:00.000Z")
at (originalQueryTime) {
  // "444" is the ID of the document to reverse from.
  Product.all({ to: "444" }).reverse().pageSize(2)
}

  4. Repeat the previous step to continue paginating in reverse:

    Product.all({ to: "333" }).reverse().pageSize(2)

See also

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!