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:
// Uses the `Product` collection's `sortedByPriceLowToHigh()` index to
// return all `Product` collection documents.
// The collection contains more than 16 documents.
Product.sortedByPriceLowToHigh()
If a subsequent page is available, the paginated results include an after
cursor:
{
// The results contain 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..."
}
Customize page size
Reference: pageSize() |
---|
Use pageSize()
to change the
maximum number of elements per page:
// Calls `pageSize()` with a size of `2`.
Product.sortedByPriceLowToHigh().pageSize(2)
{
// The results contain 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.
Iterate through pages
Reference: Set.paginate() |
---|
To iterate through paginated results, pass the after
cursor to
Set.paginate()
:
Set.paginate("hdWCxmd...")
Example implementation
The following example shows how you can iterate through paginated results using the JavaScript driver:
import { Client, fql } from "fauna";
const client = new Client({
secret: '<FAUNA_SECRET>'
});
// Defines a function that accepts a Fauna `after` cursor as
// an optional argument.
async function getProducts(afterCursor) {
// Initial FQL query.
const query = fql`Product.sortedByPriceLowToHigh().pageSize(2)`;
const response = await client.query(
// If an `after` cursor is provided, use `Set.paginate()`
// to get the next page of results.
// Otherwise, use the initial FQL query.
afterCursor ? fql`Set.paginate(${afterCursor})` : query
);
const data = response.data.data;
const nextCursor = response.data.after;
// Print the results and the after cursor.
console.log("Data:", data);
console.log("Next cursor:", nextCursor);
return { data, nextCursor };
}
// Defines a function to loop through paginated results.
async function getAllProducts() {
let afterCursor;
do {
const { data, nextCursor } = await getProducts(afterCursor);
afterCursor = nextCursor;
} while (afterCursor);
}
// Call the function to loop through the results.
getAllProducts();
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.sortedByPriceLowToHigh().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.
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!