Contents

# Page

Pagination

## Signature

page(operand: Relation, ordering: Ordering, nth: Integer) -> Relation

## Examples

page(suppliers, [:status, :sid], 1, page_size: 3)

page(suppliers, [:status, :sid], -1, page_size: 3)

## Description

Computes a relation by restricting the tuples of `operand` to those
belonging to the `nth` page (starting at 1). When `nth` is negative, returns
tuples that belong to the `nth` page from the end (e.g., -1 is last page).

Formally, the page is defined by those tuples whose ranking according to
`order` is such that `(nth-1)*page_size <= rank < nth*page_size`. In other
words, this operator is almost equivalent to the following definition
(ignoring negative page indexes for simplicity):

def page(operand, order, nth, page_size)
  allbut(
    restrict(
      rank(operand, order, :rank),
      lte((nth-1)*page_size, :rank) & lt(:rank, nth*page_size)),
    [:rank])
end
page(suppliers, [:status, :sid], 1, 3)

As of current Alf version, for this operator to be semantically sound and
deterministic, `order` MUST be a total order, that is, it must at least
cover a candidate key. As of current Alf version, no error is raised if
this is not the case but that might change in future versions.

## Implementation notes

Contrary to the longer expression shown above, this operator compiles to
SQL (rank does not, so far) at the cost of having to provide a total
order.

As the result is a relation and relations are not ordered by definition,
the order in which tuples can be observed in the result (e.g. through
explicit tuple iteration, casting to an array, json encoding) is NOT
guaranteed to follow `order`.

Version data entries

5 entries across 5 versions & 1 rubygems

Version	Path
alf-shell-0.16.4	doc/txt/page.txt
alf-shell-0.16.3	doc/txt/page.txt
alf-shell-0.16.2	doc/txt/page.txt
alf-shell-0.16.1	doc/txt/page.txt
alf-shell-0.16.0	doc/txt/page.txt