Pagination
Keyset pages over the primary key — one cursor story, REST and GraphQL, on by default.
One paginator ships in the box: keyset, a cursor over the primary key.
It is O(1) on the index, stable under concurrent inserts, and pairs
naturally with UUID-v7 keys. Every #[crud]-generated list is
keyset-paginated unless you opt out.
SeaORM’s Cursor API drives it.
Pagination is the default
Section titled “Pagination is the default”A #[crud] list — REST or GraphQL — is keyset-paginated out of the box:
#[crud(service = PostsService)]impl PostsController {}No paginate knob needed — paginate = cursor is the default. The one
other value is paginate = none, which opts out into the full
(ability-scoped) collection in one response. Even then the backstop holds:
CrudService::list never returns more than LIST_CAP (1 000) rows, and
logs a warn when it truncates. Reserve none for small, finite
collections.
Keyset, the REST shape
Section titled “Keyset, the REST shape”The generated GET /posts returns a plain Vec<Post> body and, when more rows
remain, the next page as an RFC 8288 Link. The body stays a flat array of
wire rows, each judged for the caller. The link is in the
OpenAPI document and, under CORS, exposed to a browser on another
origin without being listed.
$ curl -si '/posts?first=20'HTTP/1.1 200 OKlink: </posts?first=20&after=0193f1b2-...>; rel="next"
[ { "id": "...", "title": "..." }, ... ]
$ curl -si '/posts?first=20&after=0193f1b2-...'Following the link is the whole protocol: it keeps the page size, carries the
cursor, and is built on the path the caller addressed, global prefix and
version included. The last page has no Link.
The query carries first (page size, defaulting to 20, clamped to
1..=100) and after (the cursor the previous page’s link carries, passed
back as given; absent or empty for the first page). A cursor no page issued
is a 400, never the first page — a sync loop following next never
restarts the collection silently:
$ curl -si '/posts?first=20&after=0193f1b2'HTTP/1.1 400 Bad Requestcontent-type: application/problem+json
{"type":"about:blank","title":"Bad Request","status":400,"detail":"query parameter `after`: not a cursor this endpoint issued","code":"INVALID_ARGUMENT"}The refusal names the parameter as a value its type refused is named, never the value it was sent.
Keyset, the GraphQL shape
Section titled “Keyset, the GraphQL shape”The generated list query takes the same two cursor arguments and returns a plain list of judged wire rows, exactly like REST:
query { posts(first: 20) { id title }}# next page: posts(first: 20, after: "<last id of the previous page>")UUID-v7 keys are time-ordered, so the cursor is the previous page’s last
id, as its text — no opaque encoding. An after that is not one is a
field error naming the argument as GraphQL names one its type refused —
Invalid value for argument "after", not a cursor this endpoint issued —
never the first page; its extensions.code is INVALID_ARGUMENT, as for a
malformed id. An empty page means you reached the end.
What Page<M> carries
Section titled “What Page<M> carries”The keyset shape, before serialization:
#[non_exhaustive]pub struct Page<M> { pub items: Vec<M>, pub next_cursor: Option<PageCursor>, pub has_more: bool,}The implementation fetches limit + 1 rows, truncates the probe row from
items, and uses its presence to set has_more and next_cursor. The
cursor is the last visible row’s primary key — present only when there is
more to fetch. A later 7.x may add a field, so a page is read field by field
and built through Page::new(items, next_cursor, has_more), as a service
does when it hands on a page whose rows it mapped.
PageCursor is that key as a type. It writes the key’s own text
(Display), reads any spelling of a UUID back (FromStr), and refuses
anything else with a PipeError saying it is not a cursor this endpoint issued — the refusal every edge answers as its native client error, after
where it read the cursor. PageParams::cursor() reads the query’s after
that way, an empty one as the first page, and names the query parameter.
CrudService::page(first, after) returns a Page<E::Model> directly;
callers paginating a query of their own reach for Repo::<E>::page(first, after, extra).
A custom paginated query
Section titled “A custom paginated query”When the auto-emitted list does not match — say you want only one author’s
posts — pass the filter to Repo::page as its extra condition. It is
ANDed onto the ability scope, so the keyset, the clamp and the over-fetch
stay the framework’s:
impl PostsService { pub async fn page_by_author( &self, author_id: Uuid, first: u64, after: Option<PageCursor>, ) -> Result<Page<entity::Model>, ServiceError> { let by_author = Condition::all().add(entity::Column::AuthorId.eq(author_id)); Ok(Repo::<Posts>::page(first, after, by_author).await?) }}The route reads the query as PageParams, answers a cursor no page issued
with the 400 every list answers, through pipe_error, and returns a
Paginated answer, which writes the Link on the path the caller addressed
and documents it, as the generated list does:
#[get("/by-author/{author_id}")]#[authorize(Read, PostEntity)]async fn by_author( &self, author_id: Path<Uuid>, params: Query<PageParams>,) -> Result<Paginated<Json<Vec<Post>>>> { let after = params.cursor().map_err(|refused| pipe_error(&refused))?; let page = self.svc.page_by_author(author_id.0, params.limit(), after).await?; let posts: Vec<Post> = page.items.iter().map(Post::from).collect(); Ok(Paginated::new(Json(posts), params.limit(), page.next_cursor))}Repo::page runs under scoped(Action::Read) — the ability filter
applies, and a request without one denies every row (fail-closed).
Limits
Section titled “Limits”Keyset buys stability under concurrent inserts and O(1) reads on the PK index by giving up two things: no total count, and no jump-to-page.
There is no offset paginator in the framework, and no paginate = page
mode — one pagination story, one wire shape per surface. A consumer that genuinely needs page numbers and a total — typically an
admin table — writes that operation by hand: a Repo::scoped(Action::Read)
query with .offset()/.limit() plus a .count(), returning a shape you
own. The cost is OFFSET n, which makes the database walk and discard n
rows, so past a few thousand it is a scan.
Going further
Section titled “Going further”- Database — the entity behind the generated list.
- CRUD — the
paginateknob on#[crud(...)]. - Repo and executor —
Repo::scopedand the ambient executor behind the cursor query. - GraphQL — the list query on a resolver.