Mastering SOSL in Apex: A Guide to Salesforce Object Search Language
When working with large Salesforce orgs, efficient data retrieval becomes essential. While SOQL allows searching within a single object, what if you need to query multiple objects at once? This is where Salesforce Object Search Language (SOSL) becomes a game-changer.
In this blog, we’ll dive deep into SOSL, covering its syntax, benefits, types, limitations, and real-world Apex examples.
What is SOSL?
SOSL (Salesforce Object Search Language) is a powerful tool provided by Salesforce to search text across multiple objects, fields, and records simultaneously.
Unlike SOQL, which searches one object at a time, SOSL can query up to 20 objects in a single statement, making it an ideal choice for global searches.
Why Use SOSL Instead of SOQL?
- SOQL Limitation: You can only query one object at a time.
- Multiple SOQL Queries: Increases the risk of hitting governor limits like “Too many SOQL queries: 101”.
- SOSL Solution: Query multiple objects at once, searching across all fields or specific field types (Name, Email, Phone).
Basic SOSL Syntax
FIND ‘searchText*’ IN ALL FIELDS RETURNING
Object1(Field1, Field2, …),
Object2(Field1, Field2, …),
…
ObjectN(Field1, Field2, …)
Example:
FIND ‘test*’ IN ALL FIELDS RETURNING
Account(Id, Name, Rating),
Lead(Id, FirstName, LastName),
Contact(Id, Email, Phone)
Search Group Options
SOSL allows narrowing the search field:
- IN ALL FIELDS: Searches across all fields.
- IN NAME FIELDS: Only name-related fields.
- IN EMAIL FIELDS: Only email-related fields.
- IN PHONE FIELDS: Only phone-related fields.
Governor Limits of SOSL
- Max 20 SOSL queries per transaction.
- Each query can search up to 20 objects.
- Each query returns up to 2,000 records.
- No DML operations on SOSL results directly.
Types of SOSL Queries
- Static SOSL
- Declared within square brackets [].
- Cannot change search text at runtime.
- Automatically executed by Salesforce.
Syntax:
List<List<SObject>> results = [FIND ‘test*’ IN ALL FIELDS RETURNING Account(Name), Contact(Email)];
- Dynamic SOSL
- Search text can be passed dynamically at runtime.
- Requires the Search.query() method to execute.
- Useful in search utilities or reusable methods.
Syntax:
String searchText = ‘test’;
String searchQuery = ‘FIND \” + searchText + ‘*\’ IN ALL FIELDS RETURNING Account(Name), Contact(Email)’;
List<List<SObject>> results = Search.query(searchQuery);
Invoking SOSL Queries
You can run SOSL:
- In Developer Console’s Query Editor.
- Inside Apex Classes or Triggers.
Hands-on Examples
Static SOSL in Apex
public class GlobalSearchUtility {
public static void SearchRecords() {
List<List<SObject>> results = [FIND ‘test*’ IN ALL FIELDS RETURNING
Account(Id, Name),
Contact(Id, Email),
Lead(Id, Company)
];
// Typecasting and processing results
}
}
Dynamic SOSL in Apex
public class GlobalSearchUtility {
public static void DynamicSearchByText(String searchText) {
String query = ‘FIND \” + searchText + ‘*\’ IN ALL FIELDS RETURNING ‘ +
‘Account(Id, Name), Lead(Id, FirstName), User(Id, Email)’;
List<List<SObject>> results = Search.query(query);
// Handle results with typecasting
}
}
Call this method with:
apex
CopyEdit
GlobalSearchUtility.DynamicSearchByText(‘apex’);
Important Notes
- Ensure “Allow Search” is enabled for custom objects in Salesforce Setup.
- SOSL results are returned as a list of lists (List<List<SObject>>)—you must typecast results for processing.
Conclusion
SOSL is a must-have tool in any Salesforce developer’s toolkit. Whether you’re building search functionality across custom and standard objects or avoiding SOQL limits, SOSL provides the performance and flexibility needed for enterprise-level applications.