Order and pages

order: lists fields, each with asc or desc. When the order could tie, the compiler adds id as the last field, so records with equal values never swap places between pages.

Every list has a bound: limit: is a number, or a value whose type has a max:.

Pages

A page is found by keyset pagination: each page starts after the last record of the page before, by its order: values, rather than by counting past an offset. Page<T> is a standard type holding items: List<T> and next: PageCursor?. next is an opaque cursor, which the client sends back as after: to get the next page. A request's input for a page looks like this:

type ListTodos = Input {    status: TodoStatus {        optional: true    }    due_before: Instant {        optional: true    }    page_size: PageSize {        default: 25    }    after: PageCursor {        optional: true    }}

Page<T>, PageCursor and PageSize (an Int from 1 to 100) are built in. A page size must have an upper limit, so an app that needs a different maximum declares its own Int type with a max:.

There is no offset, because a large offset is slow, and it skips or repeats records when rows are added.

A cursor records which query made it, so a cursor from another query is refused as invalid input: the runtime's 422 invalid_input. A page's order fields must be required fields, since the next page starts after the last record's values.

What can be sorted

Text sorts by code point, as Jadpo compares it, whatever the database's collation. An enum, a Bool or a structured field can't be sorted by, since the database and Jadpo would disagree on their order.

Nearest first

A vector field is ordered by nearness instead: order: [F nearest v]. That is the only order of a query returning List<Nearest<T>>, and it goes with ai.distance(F, v) compared with a bound in where: (The nearest-neighbour query).

A point field is ordered by distance, nearest first, with order: [geo.distance(F, p) asc]. That must be the list's only order, and it goes with where: geo.within(F, p, distance: d) on the same field and point, which bounds what is sorted. Records are sorted by the distance geo.distance gives, then by id (Queries).