Paginate
Paginate( input, { ["ts": timestamp], ["before": before], ["after": after], ["size": size], ["events": events], ["sources": sources] })
Description
Pagination refers to the process of breaking a large set of results into smaller chunks, or pages, that are easier to process. This means that processing an entire result set can involve multiple queries.
A page is a list of results from input
(which has an implicit sort
order) that has a limited size. By default, a page contains up to 64
results, but you can request up to 100,000 results. The limited page
size prevents queries involving many documents from consuming enough
server or client resources that overall performance would be impacted.
When input
is larger than the current page size, only the page size’s
number of results are returned, but the page contains one or two
cursors that can be used in subsequent queries to access the following
or previous pages in the result set. If there are results that follow
the current page, the page contains the after
cursor, which points to
the first entry in the next page. If there are results that come before
the current page, the page contains the before
cursor, which points to
the first entry in the current page.
The other optional parameters influence the pagination in various ways.
ts
can be used to specify a point in time for the results; results
newer than ts
are not included. size
lets you specify the number of
results returned. events
causes the history of the result set to be
reported, rather than just the entries in the set. sources
causes the
result set to include the source for each entry, which is useful when
multiple indexes and/or collections are used.
Parameters
Field name | Field type | Definition and requirements | ||
---|---|---|---|---|
|
A set, or ref, to paginate. |
|||
. |
Optional, default
|
|||
. |
Optional - Return the previous page of results before this cursor (exclusive). |
|||
. |
Optional - Return the next page of results after this cursor (inclusive). |
|||
. |
Optional - default |
|||
. |
Optional - default |
|||
. |
Optional - default |
The parameters Other FQL functions accept a This means that you cannot compose an object, assign it to a variable,
and then use
|
Returns
A Page object.
Page object
A Page
contains an array of results and other decorated elements.
In some cases the entire result set may not fit into the array, so other
fields (the cursor fields) allow you to walk the results set in blocks
(like pages in a book). The cursor fields retrieve blocks of results
before or after the current page of results. When Pages are passed to
functions that accept arrays, only the array element of the Page is
examined or transformed. Other elements of the Page, such as the cursor,
remain unaffected and are passed directly through to the output.
Field | Type | Description |
---|---|---|
|
The elements in the page. |
|
|
The cursor for the next page, inclusive. Optional. |
|
|
The cursor for the previous page, exclusive. Optional. |
Cursor
A cursor is an object used as a marker to indicate a position within a
set. The cursor has a structure identical to the associated index’s
values
field; the same fields with the same types, in the same order.
Cursor matching is prefix-based. That means that if your index contains two or more fields, you only need to specify the first field to achieve a match. You may have to specify additional fields if there are multiple index entries that would match the first field.
A before
cursor indicates the first item in a page of results. It is
used to compute the page of results prior to the before
cursor. The
page before the current page excludes the before
cursor.
An after
cursor indicates the item after the last item in a page of
results. It is used to compute the page of results beginning with the
after
cursor. The page after the current pages includes the after
cursor.
The type of pagination cursor depends on whether the page is from a set, or from an events timeline. Set cursors may be a single scalar value, or an Array of values.
Events timeline cursors may be one of:
It is possible to fetch the last page of a set without knowing how many
pages are available by specifying a synthetic
When you are using the JavaScript driver, which only supports 53-bit
signed integers (instead of 64-bit), the minimum integer to use is
These cursor values work due to the sort precedence. You can always fetch the first page by not specifying a cursor. |
Examples
The following query paginates the set of letters (established in the
Index tutorials), but sets the size
option to 3 to reduce the size of the result set:
client.query(
q.Paginate(
q.Match(q.Index('allLetters')),
{ size: 3 }
)
)
.then((ret) => console.log(ret))
{ after: [ Ref(Collection("Letters"), "104") ],
data:
[ Ref(Collection("Letters"), "101"),
Ref(Collection("Letters"), "102"),
Ref(Collection("Letters"), "103") ] }
The following query repeats the previous query, with the addition of
applying the after
cursor from the previous result to return the next
page of results:
client.query(
q.Paginate(
q.Match(q.Index('all_letters')),
{
size: 3,
after: [ q.Ref(q.Collection('Letters'), '104') ],
}
)
)
.then((ret) => console.log(ret))
{ before: [ Ref(Collection("Letters"), "104") ],
after: [ Ref(Collection("Letters"), "107") ],
data:
[ Ref(Collection("Letters"), "104"),
Ref(Collection("Letters"), "105"),
Ref(Collection("Letters"), "106") ] }
The following query paginates the set of distinct "spells" documents
with a fire
or water
element:
client.query(
q.Paginate(
q.Union(
q.Match(q.Index('spells_by_element'), 'fire'),
q.Match(q.Index('spells_by_element'), 'water'),
)
)
)
.then((ret) => console.log(ret))
{ data:
[ Ref(id=181388642046968320, collection=Ref(id=spells, collection=Ref(id=collections))),
Ref(id=181388642071085568, collection=Ref(id=spells, collection=Ref(id=collections))),
Ref(id=181388642088911360, collection=Ref(id=spells, collection=Ref(id=collections))) ] }
The following query returns the same set of results as the previous
query, but by setting the sources
option to true
, the source of the
match that included the entry in the set is included in the result:
client.query(
q.Paginate(
q.Union(
q.Match(q.Index('spells_by_element'), 'fire'),
q.Match(q.Index('spells_by_element'), 'water'),
),
{ sources: true },
)
)
.then((ret) => console.log(ret))
{ data:
[ { value: Ref(id=181388642046968320, collection=Ref(id=spells, collection=Ref(id=collections))),
sources: [Object] },
{ value: Ref(id=181388642071085568, collection=Ref(id=spells, collection=Ref(id=collections))),
sources: [Object] },
{ value: Ref(id=181388642088911360, collection=Ref(id=spells, collection=Ref(id=collections))),
sources: [Object] } ] }
The following query returns the same set of results as the first
"spells" query, but by setting the events
option to true
, the events
associated with each item in the set are included in the result:
client.query(
q.Paginate(
q.Union(
q.Match(q.Index('spells_by_element'), 'fire'),
q.Match(q.Index('spells_by_element'), 'water'),
),
{ events: true },
)
)
.then((ret) => console.log(ret))
{ data:
[ { ts: 1509244539203043,
create: 'add',
document: Ref(id=181388642046968320, collection=Ref(id=spells, collection=Ref(id=collections))) },
{ ts: 1509244539203043,
create: 'add',
document: Ref(id=181388642071085568, collection=Ref(id=spells, collection=Ref(id=collections))) },
{ ts: 1509244539203043,
create: 'add',
document: Ref(id=181388642088911360, collection=Ref(id=spells, collection=Ref(id=collections))) } ] }
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!