salesforce-claude-code: Skill for Claude Code

Apex Cursor

The Cursor class (GA Spring '26) enables efficient pagination through up to 50 million SOQL rows without the 2,000-row OFFSET limit. Use it for large dataset processing that previously required chunked OFFSET patterns or raw Batch Apex.

Reference: @../_reference/APEX_CURSOR.md

---

When to Use

• When implementing paginated queries over large datasets using the Apex Cursor API
• When OFFSET-based pagination hits governor limits or performance issues on large result sets
• When building @AuraEnabled methods with server-side cursor pagination for LWC components
• When migrating legacy OFFSET queries to cursor-based iteration for scalability beyond 2,000 rows

---

Cursor vs. OFFSET vs. Batch Apex

Approach	Max Records	Heap Impact	Best For
SOQL OFFSET	2,000	Full result set in heap	Small UI pagination
Batch Apex	Unlimited	Per-execute governor reset	Background mass processing
Cursor class	50,000,000	Per-page only	Large paginated reports, async chaining, LWC infinite scroll

Performance Comparison

Record Count	Best Approach	Why
< 200	Standard SOQL with LIMIT	Simple, no overhead
200 - 2,000	OFFSET pagination	Adequate performance, simpler code
2,000 - 50,000	Cursor	OFFSET degrades above 2K; Cursor maintains constant performance
50,000+	Cursor + Queueable chaining	Single cursor handles up to 50M records
Batch processing	Database.QueryLocator	Full governor reset per execute chunk

Key insight: OFFSET forces the database to skip N rows on every request. At 10,000 OFFSET, the DB scans and discards 10K rows. Cursor maintains a server-side pointer with no scanning overhead regardless of position.

---

Cursor Class API

// Open a cursor — returns a server-side pointer, not the data
Database.Cursor cursor = Database.getCursor('SELECT Id, Name FROM Account ORDER BY Id');

// Fetch a page of records starting at offset
List<SObject> page = cursor.fetch(offset, pageSize);

// Total number of records the cursor can return
Integer total = cursor.getNumRecords();

// Serialize the cursor for use across transactions (Queueable chaining)
String cursorId = cursor.getId();

// Re-open a serialized cursor in a new transaction
Database.Cursor resumed = Database.getCursor(cursorId);

// Always close when done to release server-side resources
cursor.close();