🎯Cursor

NEW

A position marker that enables efficient, consistent pagination through large, ordered datasets.

DESCRIPTION

Cursors represent opaque positions in an ordered result set, allowing clients to fetch adjacent pages without costly offsets. They improve consistency under concurrent writes and scale better than offset-based pagination. Database cursors iterate over query results, while API cursors enable token-based pagination. GraphQL’s Cursor Connections specification standardizes this pattern with edges and nodes. Cursors often encode ordering keys to maintain deterministic traversal.

ALTERNATIVE DEFINITIONS

PostgreSQL Documentation

Cursors allow a user to retrieve a small number of rows at a time.

Emphasizes incremental retrieval from a result set in databases.

Source

GraphQL Foundation

A cursor is an opaque string that identifies a specific position in a connection.

Defines cursors for API-level pagination in GraphQL connections.

Source

RELATED TERMS

Pagination GraphQL Connections Database Cursor Window Function Checkpointing Kafka Consumer Offset Token-based Pagination

COMPETING TERMS

Offset Pagination

KNOWLEDGE AREAS

Data Storage & Operations Data Integration & Interoperability Software Engineering

TARGET AUDIENCE

Software Developer Data Engineer Data Scientist

EXTERNAL SOURCES

• Wikipedia - Cursor (databases)
• PostgreSQL - Database cursors in PL/pgSQL
• Relay - Cursor Connections specification

TOP QUESTIONS

Why prefer cursor-based pagination over offset pagination?

Cursors scale better on large datasets and maintain consistency under concurrent inserts or deletes, avoiding skipped or duplicated rows.

Category: Relevancy

What makes a cursor opaque?

Clients shouldn’t infer meaning; the server encodes ordering keys or positions to preserve flexibility without exposing internal schema.

Category: Concepts

How do cursors handle sorting changes?

Cursors must be tied to a deterministic sort order; changing it invalidates cursors, requiring regeneration or versioning.

Category: Risks

Are database cursors the same as API cursors?

No. Database cursors iterate query results on the server, while API cursors are client tokens for stateless pagination.

Category: Comparison

How do I design a secure cursor token?

Use signed, time-bounded tokens with HMAC or encryption to prevent tampering and preserve confidentiality of ordering keys.

Category: Security

What happens if a record is deleted between pages?

Cursor-based pagination typically still works, as the cursor refers to position relative to remaining ordered records, minimizing duplication or gaps.

Category: Behavior

How do cursors integrate with GraphQL?

Use the Cursor Connections spec with edges, nodes, and pageInfo fields, providing cursor strings for next/previous navigation.

Category: Integration

Are cursors stateful on the server?

Generally no for APIs; the token encodes state. Database cursors are server-side and stateful during transactions.

Category: Design

What’s a common mistake with cursor pagination?

Using non-unique ordering fields can cause duplicates across pages. Include tie-breakers like primary keys in the sort and cursor.

Category: Mistakes