Check out v4 of the Fauna CLI

v4 of the Fauna CLI is now in beta.

The new version introduces enhancements to the developer experience, including an improved authentication workflow. To get started, check out the CLI v4 quick start.

set.paginate()

Learn: Pagination

Convert a Set to an Object with pagination.

In most cases, you should use set.pageSize() instead of paginate(). See Differences with pageSize().

Signature

paginate(() => { data: Array<A>, after: String | Null })

paginate((size: Number) => { data: Array<A>, after: String | Null })

Description

Returns the calling Set as an Object.

If the Set is paginated and a subsequent page is available, the result includes an after cursor. To iterate through paginated results, pass the after cursor to Set.paginate().

paginate() accepts an optional size argument to control page size. In most cases, you should not use paginate() in place of pageSize(). See Differences with pageSize().

Differences with pageSize()

The following table outlines differences between set.pageSize() and set.paginate():

Difference set.pageSize() set.paginate()

Use case

Use in most cases.

Use when needing to access an 'after' cursor or paginated results within an FQL query.

Return type

Returns a set.

Returns an object.

Loading strategy

Lazy loading. Only fetches results as needed.

Eager loading. Fetches results instantly, even if the results aren’t returned or used.

Client driver methods

Compatible with driver pagination methods.

Incompatible with driver pagination methods.

Projection

Supports projections.

Doesn’t support projections.

Set instance methods

Supports set instance methods.

Doesn’t support set instance methods.

after cursor

See Cursor state and expiration.

Parameters

Parameter Type Required Description

size

Int

Maximum number of Set elements to include in the returned page. The size parameter must be in the range 1 to 16000 (inclusive).

Return value

Type Description

Object

Object that includes the following fields:

Field Type Description

data

Array<Generic>

Array representing a page of elements from the calling Set. The number of elements is limited by the size parameter.

after

String | Null

Cursor for the next page of results. The cursor is valid for history_days plus 15 minutes.

If no additional pages exist, after is Null.

Examples

Queries are subject to size limits.

If you’re performing bulk writes on a large dataset, you can use set.pageSize() and paginate() to perform the write over several queries instead of one.

The first query uses paginate() to fetch the results and generate an initial after cursor:

// Get a Set of `Customer` collection documents with an
// `address` in the `state` of `DC`. Use `pageSize()`
// and`paginate()` to paginate results and
// limit each page to two documents.
let page = Customer.where( .address?.state == "DC" )
                          .pageSize(2).paginate()

// `paginate()` returns an object. The object's `data` property
// contains an Array of `Customer` documents.
let data = page.data

// Use `forEach()` to update each `Customer` document in the
// `data` Array.
data.forEach(doc => doc.update({
  address: {
    state: "District of Columbia"
  }
}))

// Project the `after` cursor returned by `paginate()`.
// You can use the cursor to iterate through the remaining
// pages.
page {
  after
}
{
  after: "hdWDxoq..."
}

Subsequent queries use the cursor and Set.paginate() to iterate through the remaining pages:

// Uses `Set.paginate()` to iterate through pages.
let page = Set.paginate("hdWDxoq...")

let data = page.data

data.forEach(doc => doc.update({
  address: {
    state: "District of Columbia"
  }
}))

page {
  after
}

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!