pageSize()
Description
The pageSize() method modifies the page size of a Set in a query
result. It limits the size of each page to a maximum size number of items.
pageSize() renders the calling set as a Set value that includes the
first page of results and an after cursor for fetching subsequent pages.
Fauna’s official drivers include a paginate method to handle the cursor and
asynchronously iterate over the entire set. pageSize() controls the page size
used during iteration.
Lazy loading
pageSize() uses lazy loading. It
only fetches results to return a query response or to call a method that uses
eager loading. It does not perform any reads on the underlying Set's
data.
Differences with paginate()
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.
after cursor
The after 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.
Return value
| Type | Description | ||
|---|---|---|---|
Set that includes the following field:
|
Examples
{
data: [
{
id: "393466615439556672",
coll: Product,
ts: Time("2024-03-27T00:04:15.593Z"),
name: "pinata",
...
},
...
],
after: "hdWCxmd..."
}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!