Query Locator
In Salesforce Apex SOQL, a cursor returned by Database.getQueryLocator() that enables processing of up to 50 million records in batch Apex jobs, compared to the standard 50,000-record SOQL limit.
Definition
In Salesforce Apex SOQL, a cursor returned by Database.getQueryLocator() that enables processing of up to 50 million records in batch Apex jobs, compared to the standard 50,000-record SOQL limit.
In plain English
“A Query Locator in Apex SOQL is a cursor returned by Database.getQueryLocator() that lets you process up to 50 million records in batch Apex jobs. Normal SOQL queries are limited to 50,000 records, so Query Locators are how you handle huge datasets.”
Worked example
A developer at Solwich Software writes a Batch Apex job to recalculate scoring for 8 million Lead records. Standard SOQL queries cap at 50,000 records - far too few. He uses Database.getQueryLocator() to return a Query Locator: Database.QueryLocator ql = Database.getQueryLocator('SELECT Id FROM Lead'). The Query Locator can iterate up to 50 million records, far beyond the standard limit. The Batch Apex framework processes 2,000 Leads per execution, walking the entire Query Locator over a 4-hour run. Without Query Locators, the same volume processing would require external scripts pulling via Bulk API rather than running natively in Apex.
Why Query Locator matters
In Salesforce Apex SOQL, a Query Locator is a cursor returned by Database.getQueryLocator() that enables processing of up to 50 million records in batch Apex jobs, compared to the standard 50,000-record SOQL limit. The query locator is used as the start() method return value in batch Apex, giving the platform a way to chunk through huge datasets across multiple transactions.
Query locators are essential for batch Apex patterns that process large data volumes. Without query locators, you'd be stuck with the 50,000-record limit that applies to standard SOQL queries in Apex. With them, batch jobs can iterate over the entire org. Mature Apex code uses query locators appropriately in batch contexts, understanding that they work with the batch framework rather than standalone queries.
How organizations use Query Locator
Built batch Apex jobs using query locators to process millions of records for data cleanup and migration.
Trains developers on query locators as foundational for any batch Apex work.
Uses query locators in their nightly data processing jobs that iterate over their full customer database.
Trust & references
Straight from the source - Salesforce's reference material on Query Locator.
- Database ClassSalesforce Developers
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is a Query Locator?
Q2. What's the record limit with query locators?
Q3. Where are query locators used?
Discussion
Loading discussion…