Definition
Query Locator is a technical component of the Salesforce development ecosystem. Developers leverage it to write custom business logic, build integrations, or extend the platform beyond its declarative capabilities.
Real-World Example
When a senior developer at TerraForm Tech needs to streamline operations, they turn to Query Locator to solve a complex business requirement that cannot be addressed with declarative tools alone. They implement Query Locator with proper error handling, write 98% test coverage, and document the solution for future maintainers. The code passes security review on the first attempt.
Why Query Locator Matters
Query Locator is a mechanism in Apex that enables batch processing of large data volumes by maintaining a server-side cursor across SOQL query result sets. When a standard SOQL query hits governor limits at 50,000 records, Query Locator extends this to 50 million records by returning a reference to the full result set rather than loading all records into memory at once. This is the backbone of the Database.BatchableContext interface, where the start method returns a Database.QueryLocator object that Salesforce uses to chunk records into manageable batches of up to 2,000 records each for processing in the execute method.
As orgs accumulate millions of records through years of operation, routine maintenance tasks like data cleansing, mass updates, and archival become impossible without Query Locator-backed batch Apex. Developers who attempt to process large datasets with standard queries or lists will hit heap size and query row governor limits almost immediately. The consequences of not using Query Locator properly include failed batch jobs that leave data in inconsistent states, incomplete processing that misses records, and excessive resource consumption that affects other users. Best practice requires implementing robust error handling within each execute batch, maintaining state tracking across batches, and designing queryable criteria that produce a stable result set even as records are modified during processing.
How Organizations Use Query Locator
- DataForge Analytics — DataForge's Salesforce org contains 12 million contact records that need annual email verification. Their batch Apex class uses Query Locator to retrieve all contacts with an Email field, processing 2,000 contacts per batch through a verification API callout. The job runs nightly over 5 days, verifying all records without hitting governor limits.
- LegalEdge Compliance — LegalEdge runs a quarterly compliance job that updates data retention flags on 8 million case records based on their age and category. Query Locator retrieves the full record set, and the execute method applies the appropriate retention policy to each batch of 1,000 records, logging any failures to a custom error object for review.
- MergePoint CRM Services — MergePoint built a duplicate detection and merge batch job for a client with 4 million accounts. The start method's Query Locator selects accounts ordered by name, and each execute batch runs fuzzy matching logic against a reference set. The finish method emails a summary report showing 23,000 potential duplicates identified across 2,000 batch iterations.