Queries

Pagination

Offset pages for numbered navigation, cursor pages for feeds and exports, and exact counts only when needed.

Pagination has two modes. Offset mode supports numbered pages. Cursor mode moves forward through a result without the cost of large offsets.

ModeRequestCounts by defaultGood for
offsetpageIndex (starts at 1), pageSize"exact"numbered pages, "page 4 of 12"
cursorcursor from the previous page"none"feeds, "load more", infinite scroll, exports

Offset

import type { 
QueryRequest
} from "drizzle-resource";
const
pagination
:
QueryRequest
["pagination"] = {
mode
: "offset",
pageIndex
: 1,
pageSize
: 25,
count
: "exact",
};

Page 1 is offset 0; page 500 with 25 rows per page is offset 12,475. The response repeats the mode:

import type { 
QueryOffsetPageInfo
} from "drizzle-resource";
const
pageInfo
:
QueryOffsetPageInfo
= {
mode
: "offset",
pageIndex
: 1,
pageSize
: 25,
hasNextPage
: true,
count
: "exact",
rowCount
: 12_483,
};

Change pageIndex in the example below to move through the sample data.

Page 3, five rows per page real engine · 10,000 sample orders in your browser
requestplayground →
{
  "pagination": {
    "mode": "offset",
    "pageIndex": 3,
    "pageSize": 5,
    "count": "exact"
  },
  "sorting": [
    {
      "key": "createdAt",
      "dir": "desc"
    }
  ]
}
Runs when scrolled into view.

Cursor

Allow cursor mode on the resource, and make it the default if you like:

const 
query
= {
pagination
: {
modes
: ["cursor", "offset"] },
defaults
: {
pagination
: {
mode
: "cursor",
pageSize
: 25 },
},
sort
: {
defaults
: [{
key
: "createdAt",
dir
: "desc" }],
}, } satisfies
ExampleQueryConfig
;

The first request has no cursor. Each next request sends the nextCursor of the previous response:

import type { 
QueryRequestInput
} from "drizzle-resource";
const
firstPage
:
QueryRequestInput
["pagination"] = {
mode
: "cursor",
pageSize
: 25,
}; const
nextPage
:
QueryRequestInput
["pagination"] = {
mode
: "cursor",
cursor
: "opaque-cursor-from-the-previous-response",
pageSize
: 25,
};

Cursor mode needs a visible, sortable root id:

  • The engine appends it to the sort when missing, so createdAt desc becomes createdAt desc, id desc and equal timestamps keep a stable order.
  • It fetches one extra id to know whether there's a next page. That row isn't returned.
import type { 
QueryCursorPageInfo
} from "drizzle-resource";
const
pageInfo
:
QueryCursorPageInfo
= {
mode
: "cursor",
pageSize
: 25,
nextCursor
: "opaque-next-cursor",
count
: "none",
rowCount
: null,
};

A cursor is a position in one ordered result. Reset it to null when the sorting, filters, search or scope change.

Exact counts

An exact count reads every matching row. Cursor mode skips it by default; ask for it when the interface shows a total:

import type { 
QueryRequestInput
} from "drizzle-resource";
const
pagination
:
QueryRequestInput
["pagination"] = {
mode
: "cursor",
cursor
: null,
pageSize
: 25,
count
: "exact",
};

pageInfo.count tells TypeScript whether rowCount is a number:

import type { 
QueryPageInfo
} from "drizzle-resource";
declare const
pageInfo
:
QueryPageInfo
;
if (
pageInfo
.
count
=== "exact") {
pageInfo
.
rowCount
;
} else {
pageInfo
.
rowCount
;
}

Either mode accepts either count policy: an offset "load more" endpoint can skip the count too.

Limits

const 
validation
= {
maxPageSize
: 100,
maxCursorLength
: 1024,
} satisfies
ResourceQueryValidationConfig
;

maxPageSize applies to both modes. maxCursorLength defaults to 2,048 characters and is enforced by direct calls and by the Zod and Valibot request schemas.

Cursor pages can't jump to page 500 or show a page count without an exact total. Keep offset mode for numbered navigation.

Copyright © 2026