SOSL: Salesforce Object Search Language – In Absolute Detail

Estimated reading time: 7 minutes

SOSL (Salesforce Object Search Language) is a powerful language used to perform text-based searches across multiple Salesforce objects. Unlike SOQL (Salesforce Object Query Language), which is used to query records from a single object, SOSL allows you to search for specific terms within various fields of multiple standard and custom objects simultaneously. Think of it as a global search for your Salesforce data accessible programmatically.

Key Characteristics of SOSL

• Text-Based Search: SOSL is optimized for finding records that contain specific words or phrases in their text, phone, or email fields.
• Cross-Object Search: A single SOSL query can search across multiple Salesforce objects, eliminating the need for separate queries for each object.
• Indexing: Salesforce indexes text fields automatically, making SOSL searches efficient.
• Relevance Scoring: SOSL results are returned based on relevance, with the most relevant records appearing first.
• Limited Query Structure: Compared to SOQL, SOSL has a more constrained structure focused on search terms and object scoping.
• Governor Limits: Like Apex and SOQL, SOSL queries are subject to Salesforce governor limits to ensure fair resource usage in the multi-tenant environment.

SOSL Query Structure

A basic SOSL query follows this general structure:

FIND 'search term(s)' IN search_group RETURNING object_list

Let’s break down each part:

1. FIND 'search term(s)'

This clause specifies the text you want to search for. You can include:

• Single words: FIND 'Acme'
• Phrases (enclosed in single quotes): FIND 'Salesforce support'
• Wildcards:
  • *: Matches zero or more characters (e.g., FIND 'App*' will match ‘App’, ‘Apple’, ‘Application’).
  • ?: Matches exactly one character (e.g., FIND 'Lead?' will match ‘Leads’, but not ‘Lead’).
• Logical Operators (AND, OR, NOT): You can combine search terms using these operators, but their usage and precedence can be nuanced. It’s often clearer to use multiple keywords which implicitly act as AND.

  FIND 'marketing AND manager' IN ALL FIELDS RETURNING Lead (FirstName, LastName)

  FIND 'support OR help' IN ALL FIELDS RETURNING Case (CaseNumber, Subject)

  FIND 'developer NOT senior' IN ALL FIELDS RETURNING Contact (FirstName, LastName)

• Fuzzy Search (~): Use the tilde (~) to find terms that are similar in spelling.

  FIND 'account~' IN ALL FIELDS RETURNING Account (Name) // Might match 'account', 'accounts', 'acount'

2. IN search_group

This clause specifies the scope of the search. Common search_group options include:

• ALL FIELDS: Searches across all searchable text, phone, and email fields of all accessible objects.
• NAME FIELDS: Searches only in name fields (e.g., Account Name, Contact Name, Lead Name).
• EMAIL FIELDS: Searches only in email address fields.
• PHONE FIELDS: Searches only in phone number fields.
• TEXT FIELDS: Searches only in long text area, rich text area, and plain text fields.
• ALL object_type FIELDS: Searches across all searchable fields of a specific object type (e.g., ALL Account FIELDS).

3. RETURNING object_list

This clause specifies the objects and the fields you want to retrieve from the search results. The object_list is a comma-separated list of objects, and for each object, you can specify a list of fields in parentheses.

RETURNING Account (Id, Name, Industry), Contact (Id, FirstName, LastName, Email)

You can also use:

• Id only: To just retrieve the IDs of the matching records.
• No fields specified: To retrieve the default set of fields for the object.
• LIMIT: To restrict the number of records returned for each object type.

  RETURNING Account (Id, Name LIMIT 5), Contact (Id, Email LIMIT 10)

• ORDER BY: To sort the results within each object type. You can order by a searchable field and specify ASC (ascending) or DESC (descending).

  RETURNING Account (Id, Name ORDER BY Name ASC), Lead (Id, LastName ORDER BY LastName DESC)

• WITH DATA CATEGORY: To filter results based on Salesforce Knowledge data categories. This is specific to Knowledge objects.

  RETURNING KnowledgeArticleVersion (Title, KnowledgeArticleId WITH DataCategory__c = 'Products__c/Hardware__c')

Complete SOSL Query Examples

1. Searching for ‘Acme’ in all fields and returning Account ID and Name, and Contact ID and Email:

   FIND 'Acme' IN ALL FIELDS RETURNING Account (Id, Name), Contact (Id, Email)

2. Searching for the phrase ‘customer service’ in name fields and returning Case Number and Subject:

   FIND 'customer service' IN NAME FIELDS RETURNING Case (CaseNumber, Subject)

3. Searching for phone numbers starting with ‘415’ in phone fields and returning Lead ID and Phone:

   FIND '415*' IN PHONE FIELDS RETURNING Lead (Id, Phone)

4. Searching for ‘report’ in the text fields of all objects and returning the ID:

   FIND 'report' IN TEXT FIELDS RETURNING Id

5. Searching for ‘marketing’ in all Account fields and returning the Name, ordered by Name:

   FIND 'marketing' IN ALL Account FIELDS RETURNING Account (Id, Name ORDER BY Name ASC)

6. Searching for ‘error’ or ‘issue’ in all fields and returning the Subject of Cases, limited to 20 results:

   FIND 'error OR issue' IN ALL FIELDS RETURNING Case (Subject LIMIT 20)

Using SOSL in Apex

You can execute SOSL queries directly within your Apex code using square brackets [], similar to SOQL:

Remember that the order of the lists in the searchList corresponds to the order of the objects specified in the RETURNING clause of your SOSL query.

When to Use SOSL vs. SOQL

Use SOSL When:	Use SOQL When:
You need to search for specific words or phrases across multiple objects.	You know the specific object(s) you want to query.
You are unsure which object contains the data you are looking for.	You need to retrieve data based on specific field values and relationships between objects.
You need relevance-based search results.	You need to perform complex filtering and sorting based on specific fields.
You are performing a global search-like operation.	You need to traverse parent-child or child-parent relationships (using dot notation).

Limitations of SOSL

• Cannot traverse relationships between objects like SOQL.
• Less precise control over filtering compared to SOQL’s WHERE clause.
• Limited ability to perform aggregate functions.
• The structure of the query is more rigid than SOQL.

Conclusion

SOSL is an invaluable tool in the Salesforce developer’s arsenal for implementing powerful search functionality across the platform. By understanding its syntax, capabilities, and limitations, you can effectively leverage it to build user-friendly and efficient applications that allow users to quickly find the information they need, regardless of which Salesforce object it resides in.