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.
Examples
Basic example
-
The page includes a pagination cursor:
Product.all().pageSize(2) { name }
{ data: [ { name: "cups" }, { name: "pinata" } ], after: "hdWC1Y..." }
-
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:
-
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..." }
-
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..." }
-
To reverse paginate, run the original query with:
-
A range search with a
to
argument containing the previous document ID. -
set.reverse()
: Append this to the query. -
set.pageSize()
: If used, place it afterset.reverse()
.
// "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) }
-
-
Repeat the previous step to continue paginating in reverse:
Product.all({ to: "333" }).reverse().pageSize(2)
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!