struct PgORM::CursorPaginatedResult(T)

• PgORM::CursorPaginatedResult(T)
• Struct
• Value
• Object

Overview

Result wrapper for cursor-based pagination.

Cursor pagination is more efficient than offset pagination for large datasets because it doesn't require counting all records or skipping rows. Instead, it uses the primary key (or another column) as a cursor to fetch the next or previous page.

Advantages over Offset Pagination

• Performance: No OFFSET clause, which gets slower with large offsets
• Consistency: New records don't shift pages during pagination
• Scalability: Works well with millions of records

Limitations

• Can't jump to arbitrary pages (only next/previous)
• No total count or page numbers
• Requires a sortable cursor column (usually primary key)

Example

# First page
result = Article.order(:id).paginate_cursor(limit: 20)
result.records.each { |article| puts article.title }

# Next page (using cursor from previous result)
if result.has_next?
  next_result = Article.order(:id).paginate_cursor(
    after: result.next_cursor,
    limit: 20
  )
end

# Previous page
if result.has_prev?
  prev_result = Article.order(:id).paginate_cursor(
    before: result.prev_cursor,
    limit: 20
  )
end

Defined in:

pg-orm/pagination.cr

Constructors

• .new(records_array : Array(T), limit : Int32, next_cursor : String | Nil = nil, prev_cursor : String | Nil = nil)

Instance Method Summary

• #each(&block : T -> )

  Iterate over records

• #has_next? : Bool

  Whether there is a next page

• #has_prev? : Bool

  Whether there is a previous page

• #limit : Int32
• #next_cursor : String | Nil
• #prev_cursor : String | Nil
• #records : Array(T)

  Access records (already loaded for cursor determination)

• #to_json(json : JSON::Builder)

  Convert to JSON with cursor pagination metadata

Constructor Detail

Instance Method Detail