Paginate

Paginate( input, [ts], [after], [before], [size], [events], [sources] )
Paginate( input, [ts], [after], [before], [size], [events], [sources] )
Paginate( input, [ts], [after], [before], [size], [events], [sources] )
Paginate( input, [ts], [after], [before], [size], [events], [sources] )
paginate( input, [ts], [after], [before], [size], [events], [sources] )
paginate  input, [ts], [after], [before], [size], [events], [sources]
Paginate( input, [ts], [after], [before], [size], [events], [sources] )
Paginate( input, [ts], [after], [before], [size], [events], [sources] )

Description

The Paginate function simplifies the traversal of a query’s results. It is best utilized when the result of a query returns more than one object or an unknown number of objects. It provides cursor like semantics allowing the caller to walk both forward and backward in configurable sized pages through the results.

Parameter

Field Name Field Type Definition and Requirements

input

Set or Ref

ts

Integer or time value

Optional, default current. Return the result set at the specified point in time (number of UNIX microseconds or a Timestamp).

after

Cursor

Optional - Return the next page of results after this cursor (inclusive).

before

Cursor

Optional - Return the previous page of results before this cursor (exclusive).

size

Integer

Optional, default 16. Maximum number of results to return in a single page. The maximum page size is 1024.

events

Boolean

Optional, default false. If true, return a page from the event history of the set.

sources

Boolean

Optional, default false. If true, includes the source of truth providing why this object was included in the result set.

The type of pagination cursor depends on whether the page is from a set or events timeline. Set cursors may be a single scalar value, or an array of values.

Events timeline cursors may be one of:

  • An Integer representing a timestamp.

  • A @ts value.

  • A @date value. Dates are interpreted as midnight on that date, in UTC.

  • An partial Event object: ts, ts and action, or all of ts, action, and resource must be specified.

It’s possible to dead-reckon through a set by specifying a synthetic cursor. For a set in descending order, { "before": null } or { "after": 0 } yields the first and last pages of the set, respectively.

Returns

An object containing both the data and metadata about the results of create operations.

Field Name Field Type Definition and Requirements

page

Page

The page contains data array along with before and after cursors.

Examples

Simple page get:

curl https://db.fauna.com/ \
    -u fnAChGwBcAACAO70ziE0cfROosNJHdgBmJU1PgpL: \
    -d '{
          "paginate": {
            "union": [
              {
                "match": { "index": "spells_by_element" },
                "terms": "fire"
              },
              {
                "match": { "index": "spells_by_element" },
                "terms": "water"
              }
            ]
          }
        }'
client.Query(
  Paginate(
    Union(
      Match(Index("spells_by_element"), "fire"),
      Match(Index("spells_by_element"), "water"))));
System.out.println(
      client.query(
          Paginate(
              Union(
                   Match(Index(Value("spells_by_element")), Value("fire")),
                   Match(Index(Value("spells_by_element")), Value("water"))
              )
          )
      ).get());
result, _ := client.Query(
    f.Paginate(
        f.Union(
            f.MatchTerm(f.Index("spells_by_element"), "fire"),
            f.MatchTerm(f.Index("spells_by_element"), "water"),
        ),
    ),
)

fmt.Println(result)
client.query(
  Paginate(
    Union(
      Match(Index("spells_by_element"), "fire"),
      Match(Index("spells_by_element"), "water"))))
client.query(
  q.paginate(
    q.union(
      q.match(q.index("spells_by_element"), "fire"),
      q.match(q.index("spells_by_element"), "water")
    )
  ))
$client.query do
  paginate union(match(index('spells_by_element'), 'fire'),
                 match(index('spells_by_element'), 'water'))
end
client.query(
    Paginate(
        Union(
            Match(
                index: Index("spells_by_element"),
                terms: "fire"
            ),
            Match(
                index: Index("spells_by_element"),
                terms: "water"
            )
        )
    )
)
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));
HTTP/1.1 200 OK
{
  "resource": {
    "data": [
      { "@ref": "classes/spells/181388642046968320" },
      { "@ref": "classes/spells/181388642071085568" },
      { "@ref": "classes/spells/181388642088911360" }
    ]
  }
}
{
  "data": [
    { "@ref": "classes/spells/181388642046968320" },
    { "@ref": "classes/spells/181388642071085568" },
    { "@ref": "classes/spells/181388642088911360" }
  ]
}
{
  data: [
    ref(id = "181388642046968320", class = ref(id = "spells", class = ref(id = "classes"))),
    ref(id = "181388642071085568", class = ref(id = "spells", class = ref(id = "classes"))),
    ref(id = "181388642088911360", class = ref(id = "spells", class = ref(id = "classes")))
  ]
}
map[data:[{181388642046968320 0xc4201c7dc0 <nil>} {181388642071085568 0xc4201c7fe0 <nil>} {181388642088911360 0xc42021c220 <nil>}]]
{
  "data": [
    { "@ref": "classes/spells/181388642046968320" },
    { "@ref": "classes/spells/181388642071085568" },
    { "@ref": "classes/spells/181388642088911360" }
  ]
}
{
  "data": [
    { "@ref": "classes/spells/181388642046968320" },
    { "@ref": "classes/spells/181388642071085568" },
    { "@ref": "classes/spells/181388642088911360" }
  ]
}
{
  "data": [
    { "@ref": "classes/spells/181388642046968320" },
    { "@ref": "classes/spells/181388642071085568" },
    { "@ref": "classes/spells/181388642088911360" }
  ]
}
{
  "data": [
    { "@ref": "classes/spells/181388642046968320" },
    { "@ref": "classes/spells/181388642071085568" },
    { "@ref": "classes/spells/181388642088911360" }
  ]
}
{ data:
  [ Ref(id=181388642046968320, class=Ref(id=spells, class=Ref(id=classes))),
    Ref(id=181388642071085568, class=Ref(id=spells, class=Ref(id=classes))),
    Ref(id=181388642088911360, class=Ref(id=spells, class=Ref(id=classes))) ] }

With sources:

curl https://db.fauna.com/ \
    -u fnAChGwBcAACAO70ziE0cfROosNJHdgBmJU1PgpL: \
    -d '{
          "paginate": {
            "union": [
              {
                "match": { "index": "spells_by_element" },
                "terms": "fire"
              },
              {
                "match": { "index": "spells_by_element" },
                "terms": "water"
              }
            ]
          },
          "sources": true
        }'
client.Query(
  Paginate(
    Union(
      Match(Index("spells_by_element"), "fire"),
      Match(Index("spells_by_element"), "water")),
    sources: true));
System.out.println(
    client.query(
        Paginate(
            Union(
                Match(Index(Value("spells_by_element")), Value("fire")),
                Match(Index(Value("spells_by_element")), Value("water"))
            )
        ).sources(Value(true))
    ).get());
result, _ := client.Query(
    f.Paginate(
        f.Union(
            f.MatchTerm(f.Index("spells_by_element"), "fire"),
            f.MatchTerm(f.Index("spells_by_element"), "water"),
        ),
        f.Sources(true),
    ),
)

fmt.Println(result)
client.query(
  Paginate(
    Union(
      Match(Index("spells_by_element"), "fire"),
      Match(Index("spells_by_element"), "water")),
    sources = true))
client.query(
  q.paginate(
    q.union(
      q.match(q.index("spells_by_element"), "fire"),
      q.match(q.index("spells_by_element"), "water")
    ),
    sources=True
  ))
$client.query do
  paginate union(match(index('spells_by_element'), 'fire'),
                 match(index('spells_by_element'), 'water')),
           sources: true
end
client.query(
    Paginate(
        Union(
            Match(
                index: Index("spells_by_element"),
                terms: "fire"
            ),
            Match(
                index: Index("spells_by_element"),
                terms: "water"
            )
        ),
        sources: true
    )
)
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));
HTTP/1.1 200 OK
{
  "resource": {
    "data": [
      {
        "value": { "@ref": "classes/spells/181388642046968320" },
        "sources": [
          {
            "@set": {
              "match": { "@ref": "indexes/spells_by_element" },
              "terms": "fire"
            }
          }
        ]
      },
      {
        "value": { "@ref": "classes/spells/181388642071085568" },
        "sources": [
          {
            "@set": {
              "match": { "@ref": "indexes/spells_by_element" },
              "terms": "fire"
            }
          },
          {
            "@set": {
              "match": { "@ref": "indexes/spells_by_element" },
              "terms": "water"
            }
          }
        ]
      },
      {
        "value": { "@ref": "classes/spells/181388642088911360" },
        "sources": [
          {
            "@set": {
              "match": { "@ref": "indexes/spells_by_element" },
              "terms": "water"
            }
          }
        ]
      }
    ]
  }
}
{
  "data": [
    {
      "value": { "@ref": "classes/spells/181388642046968320" },
      "sources": [
        {
          "@set": {
            "match": { "@ref": "indexes/spells_by_element" },
            "terms": "fire"
          }
        }
      ]
    },
    {
      "value": { "@ref": "classes/spells/181388642071085568" },
      "sources": [
        {
          "@set": {
            "match": { "@ref": "indexes/spells_by_element" },
            "terms": "fire"
          }
        },
        {
          "@set": {
            "match": { "@ref": "indexes/spells_by_element" },
            "terms": "water"
          }
        }
      ]
    },
    {
      "value": { "@ref": "classes/spells/181388642088911360" },
      "sources": [
        {
          "@set": {
            "match": { "@ref": "indexes/spells_by_element" },
            "terms": "water"
          }
        }
      ]
    }
  ]
}
{
  data: [
    {
      value: ref(id = "181388642046968320", class = ref(id = "spells", class = ref(id = "classes"))),
      sources: [
        {
          @set = {
            match: ref(id = "spells_by_element", class = ref(id = "indexes")),
            terms: "fire"
          }
        }
      ]
    },
    {
      value: ref(id = "181388642071085568", class = ref(id = "spells", class = ref(id = "classes"))),
      sources: [
        {
          @set = {
            match: ref(id = "spells_by_element", class = ref(id = "indexes")),
            terms: "fire"
          }
        },
        {
          @set = {
            match: ref(id = "spells_by_element", class = ref(id = "indexes")),
            terms: "water"
          }
        }
      ]
    },
    {
      value: ref(id = "181388642088911360", class = ref(id = "spells", class = ref(id = "classes"))),
      sources: [
        {
          @set = {
            match: ref(id = "spells_by_element", class = ref(id = "indexes")),
            terms: "water"
          }
        }
      ]
    }
  ]
}
map[data:[
  map[value:{181388642046968320 0xc42024a960 <nil>} sources:[{map[match:{spells_by_element 0xc42024ab00 <nil>} terms:fire]}]]
  map[value:{181388642071085568 0xc42024ada0 <nil>} sources:[{map[terms:fire match:{spells_by_element 0xc42024af40 <nil>}]} {map[match:{spells_by_element 0xc42024b100 <nil>} terms:water]}]]
  map[value:{181388642088911360 0xc42024b3e0 <nil>} sources:[{map[match:{spells_by_element 0xc42024b580 <nil>} terms:water]}]]
]]
{
  "data": [
    {
      "value": { "@ref": "classes/spells/181388642046968320" },
      "sources": [
        {
          "@set": {
            "match": { "@ref": "indexes/spells_by_element" },
            "terms": "fire"
          }
        }
      ]
    },
    {
      "value": { "@ref": "classes/spells/181388642071085568" },
      "sources": [
        {
          "@set": {
            "match": { "@ref": "indexes/spells_by_element" },
            "terms": "fire"
          }
        },
        {
          "@set": {
            "match": { "@ref": "indexes/spells_by_element" },
            "terms": "water"
          }
        }
      ]
    },
    {
      "value": { "@ref": "classes/spells/181388642088911360" },
      "sources": [
        {
          "@set": {
            "match": { "@ref": "indexes/spells_by_element" },
            "terms": "water"
          }
        }
      ]
    }
  ]
}
{
  "data": [
    {
      "value": { "@ref": "classes/spells/181388642046968320" },
      "sources": [
        {
          "@set": {
            "match": { "@ref": "indexes/spells_by_element" },
            "terms": "fire"
          }
        }
      ]
    },
    {
      "value": { "@ref": "classes/spells/181388642071085568" },
      "sources": [
        {
          "@set": {
            "match": { "@ref": "indexes/spells_by_element" },
            "terms": "fire"
          }
        },
        {
          "@set": {
            "match": { "@ref": "indexes/spells_by_element" },
            "terms": "water"
          }
        }
      ]
    },
    {
      "value": { "@ref": "classes/spells/181388642088911360" },
      "sources": [
        {
          "@set": {
            "match": { "@ref": "indexes/spells_by_element" },
            "terms": "water"
          }
        }
      ]
    }
  ]
}
{
  "data": [
    {
      "value": { "@ref": "classes/spells/181388642046968320" },
      "sources": [
        {
          "@set": {
            "match": { "@ref": "indexes/spells_by_element" },
            "terms": "fire"
          }
        }
      ]
    },
    {
      "value": { "@ref": "classes/spells/181388642071085568" },
      "sources": [
        {
          "@set": {
            "match": { "@ref": "indexes/spells_by_element" },
            "terms": "fire"
          }
        },
        {
          "@set": {
            "match": { "@ref": "indexes/spells_by_element" },
            "terms": "water"
          }
        }
      ]
    },
    {
      "value": { "@ref": "classes/spells/181388642088911360" },
      "sources": [
        {
          "@set": {
            "match": { "@ref": "indexes/spells_by_element" },
            "terms": "water"
          }
        }
      ]
    }
  ]
}
{
  "data": [
    {
      "value": { "@ref": "classes/spells/181388642046968320" },
      "sources": [
        {
          "@set": {
            "match": { "@ref": "indexes/spells_by_element" },
            "terms": "fire"
          }
        }
      ]
    },
    {
      "value": { "@ref": "classes/spells/181388642071085568" },
      "sources": [
        {
          "@set": {
            "match": { "@ref": "indexes/spells_by_element" },
            "terms": "fire"
          }
        },
        {
          "@set": {
            "match": { "@ref": "indexes/spells_by_element" },
            "terms": "water"
          }
        }
      ]
    },
    {
      "value": { "@ref": "classes/spells/181388642088911360" },
      "sources": [
        {
          "@set": {
            "match": { "@ref": "indexes/spells_by_element" },
            "terms": "water"
          }
        }
      ]
    }
  ]
}
{ data:
   [ { value: Ref(id=181388642046968320, class=Ref(id=spells, class=Ref(id=classes))),
       sources: [Object] },
     { value: Ref(id=181388642071085568, class=Ref(id=spells, class=Ref(id=classes))),
       sources: [Object] },
     { value: Ref(id=181388642088911360, class=Ref(id=spells, class=Ref(id=classes))),
       sources: [Object] } ] }

With events:

curl https://db.fauna.com/ \
    -u fnAChGwBcAACAO70ziE0cfROosNJHdgBmJU1PgpL: \
    -d '{
          "paginate": {
            "union": [
              {
                "match": { "index": "spells_by_element" },
                "terms": "fire"
              },
              {
                "match": { "index": "spells_by_element" },
                "terms": "water"
              }
            ]
          },
          "events": true
        }'
client.Query(
  Paginate(
    Union(
      Match(Index("spells_by_element"), "fire"),
      Match(Index("spells_by_element"), "water")),
    events: true));
System.out.println(
      client.query(
         Paginate(
             Union(
               Match(Index(Value("spells_by_element")), Value("fire")),
               Match(Index(Value("spells_by_element")), Value("water"))
             )
         ).events(Value(true))
      ).get());
result, _ := client.Query(
    f.Paginate(
        f.Events(
            f.Union(
                f.MatchTerm(f.Index("spells_by_element"), "fire"),
                f.MatchTerm(f.Index("spells_by_element"), "water"),
            ),
        ),
    ),
)

fmt.Println(result)
client.query(
  Paginate(
    Union(
      Match(Index("spells_by_element"), "fire"),
      Match(Index("spells_by_element"), "water")),
    events = true))
client.query(
  q.paginate(
    q.union(
      q.match(q.index("spells_by_element"), "fire"),
      q.match(q.index("spells_by_element"), "water")
    ),
    events=True
  ))
$client.query do
  paginate union(match(index('spells_by_element'), 'fire'),
                 match(index('spells_by_element'), 'water')),
           events: true
end
client.query(
    Paginate(
        Union(
            Match(
                index: Index("spells_by_element"),
                terms: "fire"
            ),
            Match(
                index: Index("spells_by_element"),
                terms: "water"
            )
        ),
        events: true
    )
)
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));
HTTP/1.1 200 OK
{
  "resource": {
    "data": [
      {
        "ts": 1509244539203043,
        "action": "create",
        "resource": { "@ref": "classes/spells/181388642046968320" }
      },
      {
        "ts": 1509244539223511,
        "action": "create",
        "resource": { "@ref": "classes/spells/181388642071085568" }
      },
      {
        "ts": 1509244539235128,
        "action": "create",
        "resource": { "@ref": "classes/spells/181388642088911360" }
      }
    ]
  }
}
{
  "data": [
    {
      "ts": 1509244539203043,
      "action": "create",
      "resource": { "@ref": "classes/spells/181388642046968320" }
    },
    {
      "ts": 1509244539223511,
      "action": "create",
      "resource": { "@ref": "classes/spells/181388642071085568" }
    },
    {
      "ts": 1509244539235128,
      "action": "create",
      "resource": { "@ref": "classes/spells/181388642088911360" }
    }
  ]
}
{
  data: [
    {
      ts: 1526663274438247,
      action: "add",
      instance: ref(id = "181388642071085568", class = ref(id = "spells", class = ref(id = "classes")))
    },
    {
      ts: 1526663274504812,
      action: "add",
      instance: ref(id = "181388642046968320", class = ref(id = "spells", class = ref(id = "classes")))
    },
    {
      ts: 1526663274516453,
      action: "add",
      instance: ref(id = "181388642088911360", class = ref(id = "spells", class = ref(id = "classes")))
    }
  ]
}
map[data:[
  map[instance:{181388642046968320 0xc420205300 <nil>} action:add ts:1509244539203043]
  map[instance:{181388642071085568 0xc4202055c0 <nil>} action:add ts:1509244539223511]
  map[instance:{181388642088911360 0xc4202058a0 <nil>} action:add ts:1509244539235128]
]]
{
  "data": [
    {
      "ts": 1509244539203043,
      "action": "create",
      "resource": { "@ref": "classes/spells/181388642046968320" }
    },
    {
      "ts": 1509244539223511,
      "action": "create",
      "resource": { "@ref": "classes/spells/181388642071085568" }
    },
    {
      "ts": 1509244539235128,
      "action": "create",
      "resource": { "@ref": "classes/spells/181388642088911360" }
    }
  ]
}
{
  "data": [
    {
      "ts": 1509244539203043,
      "action": "create",
      "resource": { "@ref": "classes/spells/181388642046968320" }
    },
    {
      "ts": 1509244539223511,
      "action": "create",
      "resource": { "@ref": "classes/spells/181388642071085568" }
    },
    {
      "ts": 1509244539235128,
      "action": "create",
      "resource": { "@ref": "classes/spells/181388642088911360" }
    }
  ]
}
{
  "data": [
    {
      "ts": 1509244539203043,
      "action": "create",
      "resource": { "@ref": "classes/spells/181388642046968320" }
    },
    {
      "ts": 1509244539223511,
      "action": "create",
      "resource": { "@ref": "classes/spells/181388642071085568" }
    },
    {
      "ts": 1509244539235128,
      "action": "create",
      "resource": { "@ref": "classes/spells/181388642088911360" }
    }
  ]
}
{
  "data": [
    {
      "ts": 1509244539203043,
      "action": "create",
      "resource": { "@ref": "classes/spells/181388642046968320" }
    },
    {
      "ts": 1509244539223511,
      "action": "create",
      "resource": { "@ref": "classes/spells/181388642071085568" }
    },
    {
      "ts": 1509244539235128,
      "action": "create",
      "resource": { "@ref": "classes/spells/181388642088911360" }
    }
  ]
}
{ data:
   [ { ts: 1509244539203043,
       create: 'add',
       instance: Ref(id=181388642046968320, class=Ref(id=spells, class=Ref(id=classes))) },
     { ts: 1509244539203043,
       create: 'add',
       instance: Ref(id=181388642071085568, class=Ref(id=spells, class=Ref(id=classes))) },
     { ts: 1509244539203043,
       create: 'add',
       instance: Ref(id=181388642088911360, class=Ref(id=spells, class=Ref(id=classes))) } ] }

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve! documentation@fauna.com

Thank you for your feedback!