The number of records that can be returned by SOQL (Salesforce Object Query Language) and SOSL (Salesforce Object Search Language) is governed by specific Salesforce limits, which vary depending on the query type, context (e.g., Apex, API), and overall transaction.
For SOQL, a single query can retrieve up to 50,000 records within an Apex transaction. When using SOSL, a single search can return a maximum of 2,000 records.
SOQL Record Limits
SOQL is used to query records from a single object or multiple related objects. The maximum number of records it can return depends heavily on the context of its execution.
- Apex Transaction Limit: When executing SOQL queries within an Apex transaction, the maximum number of rows that can be returned by all SOQL queries combined in that transaction is 50,000. This limit is crucial to prevent long-running transactions and ensure platform stability. This applies whether you make one query returning 50,000 rows or 100 queries each returning 500 rows.
- Query Count Limits in Apex: Related to the above, an Apex synchronous transaction can execute a maximum of 100 SOQL queries, while an asynchronous Apex transaction (e.g., Batch Apex, Queueable Apex) can execute up to 200 SOQL queries.
- API Queries (beyond Apex): When fetching records through the Salesforce API (e.g., using Data Loader, Workbench, or custom API integrations), a single SOQL query can initially return up to 2,000 records. However, for larger datasets, the API provides the
queryMore()call, which allows you to retrieve additional batches of up to 2,000 records until all records matching your query are returned. This mechanism enables the retrieval of millions of records, though it requires multiple API calls. - Batch Apex: For processing large volumes of records directly within Salesforce, Batch Apex is designed to handle up to 50 million records. It processes records in batches, adhering to the 50,000 row SOQL limit per batch execution, but allowing the overall operation to process many more.
SOSL Record Limits
SOSL is designed for text-based searches across multiple objects and fields, providing more relevant results based on a search query, similar to a search engine.
- Maximum Records: A single SOSL query can return a maximum of 2,000 records. Unlike SOQL, there isn't a direct equivalent to
queryMore()for SOSL to retrieve additional records beyond this limit for a single search query. - Search Scope: SOSL is powerful for finding records where you might not know the exact object, as it can search across multiple standard and custom objects in a single request. It's ideal for keyword searches.
Summary of SOQL vs. SOSL Record Limits
The table below summarizes the key record return limits for SOQL and SOSL:
| Query Type | Context / Limit Type | Maximum Records Returned | Notes |
|---|---|---|---|
| SOQL | Apex Transaction (overall) | 50,000 rows | Total rows returned by all SOQL queries in a single synchronous or asynchronous Apex transaction. |
| SOQL | API Query (single call) | 2,000 rows | Initial retrieve. Can use queryMore() for additional batches. |
| SOQL | Batch Apex (overall processing) | Up to 50 million records | Processes records in batches; each batch adheres to Apex transaction limits. |
| SOSL | Single Search Query | 2,000 records | For keyword searches across multiple objects/fields. No queryMore() equivalent for SOSL. |
Practical Considerations and Best Practices
Understanding these limits is crucial for developing efficient and scalable Salesforce applications.
- Filter Queries Effectively: Always filter your SOQL and SOSL queries to return only the necessary records. Use
WHEREclauses (for SOQL) and search scope (for SOSL) to narrow down results. - Use
LIMITClause: When you only need a specific number of records (e.g., top 10), always use theLIMITclause in SOQL to prevent retrieving unnecessary data. - Handle Large Datasets: For operations involving more than 50,000 records in Apex, consider using asynchronous Apex options like Batch Apex, Queueable Apex, or the Salesforce API with
queryMore(). - Indexed Fields: Ensure that fields used in your SOQL
WHEREclauses or SOSL search terms are indexed to optimize performance, especially for large datasets.
