paginate()
|
In most cases, you should use
|
Description
The paginate() method paginates the calling Set. It returns
the first page of size Set values as an Object.
When size is omitted, the default page size is 16.
When the Set has more than size values, a pagination cursor is
included as the last entry on the page. Use the
Set.paginate() method
with the provided cursor to sequentially access subsequent pages.
The pagination 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.
Differences with pageSize()
pageSize() is similar to
paginate(). In most cases, you
should use pageSize().
pageSize() tends to produce
faster queries with less compute.
Major differences between the methods include:
-
pageSize()only affects the page size used when rendering a Set. Methods chained topageSize(), such asforEach(), access the entire set, not a page of results.paginate()returns an Object. Methods chained topaginate()access this object, not the calling set. -
pageSize()uses lazy loading. It only fetches results to return a query response or to call a method that uses eager loading.paginate()uses eager loading and fetches results instantly, even if the results aren’t returned or used. This can produce slower and more wasteful queries thanpageSize(). -
pageSize()supports projection and can call other Set instance methods.paginate()doesn’t support projection or Set instance methods. -
You can’t use projection or dot notation to access
pageSize()'saftercursor in an FQL query. The cursor is typically handled by the client. For example, Fauna’s client drivers include a paginate method to handle the cursor.You can use dot notation to access
paginate()'saftercursor in an FQL query. For example:// Paginate query using `paginate()` let page = Product.all().paginate(2) // Get `after` cursor page?.after -
pageSize()requires a size argument.paginate()supports size but doesn’t require it. See Pass a size argument.
Examples
In most cases, you should use
pageSize() instead of
paginate(). However, paginate() is still useful if:
-
You want to access the results as an object, not a Set.
-
You need to directly access the
aftercursor in an FQL query.
The following example uses paginate() to update the ttl of a large
collection of documents over several transactions.
The first transaction uses paginate() to fetch the results and generate an
initial after cursor. Subsequent transactions use
Set.paginate() to iterate
through the remaining pages.
{
after: "hdWC1YLGZ..."
}Pass a size argument
Passing a size argument to paginate() is equivalent to calling
paginate() on pageSize().
For example:
// Gets first 10 products
Product.sortedByPriceHighToLow()
.paginate(10)
// Equivalent to:
// Product.sortedByPriceHighToLow()
// .pageSize(10)
// .paginate()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!