paginate()

Learn: Pagination

Returns the calling Set as an Object with pagination.

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

Signature

paginate(): Object<A>

paginate(size: Int): Object<A>

Description

The paginate() method 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()

Unlike pageSize(), paginate():

  • Returns an Object, not a Set.

  • Uses eager loading and fetches results instantly, even if the results aren’t returned or used. This can produce slower and more wasteful queries.

  • Isn’t compatible with Fauna client driver pagination methods.

  • Doesn’t support projection or set instance methods.

If you need to access an after cursor or paginated results within an FQL query, use paginate(). Otherwise, you should use pageSize().

after cursor

See Cursor state and expiration.

Parameters

Parameter Type Required Description

size

Int

Number of Set values to include in the returned page. The size parameter must be in the range 1 to 16,000.

Return value

Type Description

Object

Object that includes the following fields:

data

Array of values.

after

(optional) Cursor pointing to next page when more pages exist. The cursor is valid for history_days plus 15 minutes.

Examples

Transactions are subject to size limits.

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

The first transaction 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 transactions 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!