Scalable list navigation
Large datasets where traversing skipped rows would become expensive.
Prisma · Pipe
cursor
Prisma cursor pagination uses a unique, sequential field to bookmark a position and fetch records before or after it. Combine cursor with take, orderBy, and usually skip: 1 for forward pages.
How it works
Cursor pagination resumes a Prisma Client query from a known record. Pass a unique, sequential field in cursor, keep orderBy aligned with it, use take for page size, and skip the cursor record when fetching the next page.
Syntax
prisma.model.findMany({ cursor: { field: value }, take: number, skip: 1, orderBy: { field: "asc" } })Parameters
| Name | Type | Description |
|---|---|---|
cursor | object | Unique, sequential field value identifying the position from which to continue. |
take | number | Number of records to return; use a negative value for backward pagination. |
skip | number | Number of records to omit from the cursor position, commonly 1 for forward continuation. |
orderBy | object | Ordering that must use the cursor field. |
Returns
A limited set of model records before or after the supplied cursor.
Key points
- Use cursor with take to request a bounded result set relative to a known position.
- The cursor represents the current position, allowing a subsequent query to continue from there.
- Typical cursor fields are IDs or timestamps, provided they satisfy the required ordering properties.
- Pass the final record's cursor value into the next query to retrieve the following batch.
Common mistakes
- Set skip: 1 when continuing forward; otherwise the record used as the cursor appears again.
- The cursor field must be unique and sequential, and the query must sort by that same field.
- Cursor pagination cannot directly navigate to an arbitrary numbered page.
Example: Cursor-based pagination
const firstPage = await prisma.post.findMany({
take: 10,
orderBy: { id: "asc" },
});
const lastPost = firstPage[firstPage.length - 1];
const nextPage = lastPost
? await prisma.post.findMany({
take: 10,
skip: 1,
cursor: { id: lastPost.id },
orderBy: { id: "asc" },
})
: [];Fetches an initial page, then resumes after its final post by using that post's unique ID as the cursor.
When to use it
Infinite scrolling
Feeds or timelines that load the next batch from the last displayed record.
Ordered result traversal
Sequentially reading records using IDs or timestamps as stable positions.
Interview questions
QHow does Prisma cursor pagination work?
Cursor pagination uses a unique, sequential value to bookmark a position in the result set. The next query supplies that value through cursor, sets take for the page size, and commonly uses skip: 1 to exclude the bookmark record.
Follow-up: When is offset pagination preferable? Use it when users need to jump directly to a numbered page.
QWhat constraints apply to the cursor field?
The cursor should identify a unique, sequential column such as an ID or timestamp. orderBy must sort by that cursor so Prisma can continue from a deterministic position.
Follow-up: What happens if the cursor value is guessed? Pagination can begin at an unknown location because the guessed value may not correspond to the intended position.
QHow do you paginate backwards?
Set take to a negative value to page backwards. The cursor still marks the known position, while the negative page size requests records in the reverse direction.
Follow-up: Can cursor pagination jump to page 400? No; the preceding pages must be requested to discover the appropriate cursor.
Related
offset paginationfindManyorderBytakeskip