Skip to content

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.

A #[crud] list — REST or GraphQL — is keyset-paginated out of the box:

crates/features/src/posts/http/controller.rs
#[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.

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.

Terminal window
$ curl -si '/posts?first=20'
HTTP/1.1 200 OK
link: </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:

Terminal window
$ curl -si '/posts?first=20&after=0193f1b2'
HTTP/1.1 400 Bad Request
content-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.

The generated list query takes the same two cursor arguments and returns a plain list of judged wire rows, exactly like REST:

the query a client sends
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.

The keyset shape, before serialization:

nest_rs::seaorm::Page
#[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).

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:

crates/features/src/posts/service.rs
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:

crates/features/src/posts/http/controller.rs
#[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).

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.

  • Database — the entity behind the generated list.
  • CRUD — the paginate knob on #[crud(...)].
  • Repo and executor — Repo::scoped and the ambient executor behind the cursor query.
  • GraphQL — the list query on a resolver.