Pagination and limits

The builder supports two pagination styles. Both map to plain JSON body fields on /gateway/fetch (and the same fields are forwarded on update/delete where applicable). Pick the style that matches your UI and backend.

Offset and limit

Use for infinite scroll or sequential windows without a page index.

// rows 51..75
const { data } = await athena
  .from("orders")
  .select("id, total")
  .limit(25)
  .offset(50);

range(from, to) shorthand

Equivalent to .offset(from).limit(to - from + 1):

const { data: firstTen } = await athena
  .from("orders")
  .select()
  .range(0, 9);

Page-based pagination

.currentPage is 1-based. Pair with .pageSize. Optionally pass .totalPages if your gateway expects a total-page hint in the envelope.

const { data } = await athena
  .from("orders")
  .select("id, total")
  .currentPage(2)
  .pageSize(25);

const { data: hinted } = await athena
  .from("orders")
  .select("id, total")
  .currentPage(2)
  .pageSize(25)
  .totalPages(8);

Payload mapping

Order of chaining

Pagination helpers live on the shared filter chain, so they work before or after .select():

await athena.from("users").currentPage(2).pageSize(50).select();
await athena.from("users").select().currentPage(2).pageSize(50);

Offset/limit and page-based fields are sent independently. You can combine them if your backend interprets both; typical apps choose one style.

Writes and deletes

The same limit/offset/page fields can propagate on update and delete chains when you need ordered, capped batches:

await athena
  .from("queued_jobs")
  .update({ status: "claimed" })
  .eq("status", "ready")
  .order("priority", { ascending: false })
  .limit(10)
  .select("id");

See Sorting for .order().

Clearing state

.reset() clears conditions, pagination, and order — see the API reference for details.

Related

• Sorting
• Queries and results
• Overview