SOSL - Salesforce Object Search Language in Apex

What is Salesforce Object Search Language (SOSL) in Apex ? 

Salesforce Object Search Language (SOSL) is a Salesforce search language that is used to perform text searches in records. Use SOSL to search fields across multiple standard and custom object records in Salesforce. SOSL is similar to Apache Lucene.

SOSL statements evaluate to a list of lists of sObjects, where each list contains the search results for a particular sObject type. The result lists are always returned in the same order as they were specified in the SOSL query. If a SOSL query doesn’t return any records for a specified sObject type, the search results include an empty list for that sObject.

Use the Query Editor:
The Developer Console provides the Query Editor console, which enables you to run SOSL queries and view results. The Query Editor provides a quick way to inspect the database. It is a good way to test your SOSL queries before adding them to your Apex code. When you use the Query Editor, you need to supply only the SOSL statement without the Apex code that surrounds it.

Basic SOSL Syntax : 

• SOSL allows you to specify the following search criteria:
• Text expression (single word or a phrase) to search for
• Scope of fields to search
• List of objects and fields to retrieve
• Conditions for selecting rows in the source objects

How to Run / Execute SOSL Query:

• Go to Salesforce org
• Click on Gear Icon (Dropdown menu)
• Click on Developer Console
• In the Developer Console, click the Query Editor  tab.
• Copy and paste the following any SOSL Code line into the first box under Query Editor, and then click Execute.

Basic SOSL Syntax:

This is the syntax of a basic SOSL query:

FIND 'SearchQuery' [IN SearchGroup] [RETURNING ObjectsAndFields]

SearchQuery is the text to search for (a single word or a phrase).
Search terms can be grouped with logical operators (AND, OR) and parentheses. Also, search terms can include wildcard characters (*, ?). The * wildcard matches zero or more characters at the middle or end of the search term. The ? wildcard matches only one character at the middle or end of the search term.

Text searches are case-insensitive. For example, searching for Customer, customer, or CUSTOMER all return the same results.

SearchGroup is optional. It is the scope of the fields to search. If not specified, the default search scope is all fields.
SearchGroup can take one of the following values :

• ALL FIELDS
• NAME FIELDS
• EMAIL FIELDS
• PHONE FIELDS
• SIDEBAR FIELDS

ObjectsAndFields is optional. It is the information to return in the search result—a list of one or more sObjects and, within each sObject, list of one or more fields, with optional values to filter against. If not specified, the search results contain the IDs of all objects found.

Single Words and Phrases
A SearchQuery contains two types of text:
Single Word :
single word, such as test or hello. Words in the SearchQuery are delimited by spaces, punctuation, and changes from letters to digits (and vice-versa). Words are always case insensitive.

Phrase :
collection of words and spaces surrounded by double quotes such as "john smith". Multiple words can be combined together with logic and grouping operators to form a more complex query.

# After the required FIND clause, you can add one or more optional clauses in the following order.

FIND {SearchQuery} 
[ IN SearchGroup ]
[ RETURNING FieldSpec [[ toLabel(fields)] [convertCurrency(Amount)] [FORMAT()]] ]
[ WITH DivisionFilter ]
[ WITH DATA CATEGORY DataCategorySpec ]
[ WITH SNIPPET[(target_length=n)] ]
[ WITH NETWORK NetworkIdSpec ]
[ WITH PricebookId ]
[ WITH METADATA ]
[ LIMIT n ]

[ UPDATE [TRACKING], [VIEWSTAT] ]

When to Use SOSL :

• Use SOSL when you don’t know which object or field the data resides in, and you want to:
• Retrieve data for a specific term that you know exists within a field. Because SOSL can tokenize multiple terms within a field and build a search index from this, SOSL searches are faster and can return more relevant results.
• Retrieve multiple objects and fields efficiently where the objects might or might not be related to one another.
• Retrieve data for a particular division in an organization using the divisions feature.
• Retrieve data that’s in Chinese, Japanese, Korean, or Thai. Morphological tokenization for CJKT terms helps ensure accurate results.

Use SOQL when you know which objects the data resides in, and you want to:

• Retrieve data from a single object or from multiple objects that are related to one another.
• Count the number of records that meet specified criteria.
• Sort results as part of the query.
• Retrieve data from number, date, or checkbox fields.

Use SOSL when you don’t know which object or field the data resides in, and you want to:

• Retrieve data for a specific term that you know exists within a field. Because SOSL can tokenize multiple terms within a field and build a search index from this, SOSL searches are faster and can return more relevant results.
• Retrieve multiple objects and fields efficiently where the objects might or might not be related to one another.
• Retrieve data for a particular division in an organization using the divisions feature.
• Retrieve data that’s in Chinese, Japanese, Korean, or Thai. Morphological tokenization for CJKT terms helps ensure accurate results.

Performance Considerations :
If your searches are too general, they are slow and return too many results. Use the following clauses to define efficient text searches.

• IN: Limits the types of fields to search, including email, name, or phone.
• LIMIT: Specifies the maximum number of rows to return.
• OFFSET: Displays the search results on multiple pages.
• RETURNING: Limits the objects and fields to return.
• WITH DATA CATEGORY: Specifies the data categories to return.
• WITH DivisionFilter: Specifies the division field to return.
• WITH NETWORK: Specifies the Experience Cloud site ID to return.
• WITH PricebookId: Specifies the price book ID to return

Keywords in SOSL : 
FIND : 

FIND {John}

IN : 
To specify the field to look at

FIND {John} IN Name FIELDS

RETURNING : 
To specify the Object to be fetched

FIND {John} Returning Lead, Contact

FIND {John} Returning Lead(Id,Name), Contact(Id,Name)

FIND {John} IN Name Fields Returning Lead(Id,Name), Contact(Id,Name)

LIMIT : 
To specify the limit

ORDER BY : 
To specify the Sorting

WHERE : 
To specify the criteria

# Some Examples : 

1. To get all records that has “John” in any field of any object

FIND {John}

2. To get all records that has "John" in NAME Field of any object

FIND {John} IN Name Fields

3. To get all records that has "John" In any Field of Contact object

FIND {John} Returning Contact

4. To get all records that has either "John" or "Ravi" in name Field of Contact object

FIND {John OR Ravi} Returning Contact

FIND {John OR Ravi} Returning Contact(Name)

5. To get all records by showing the Name and Phone details that has either "John" or "Ravi" in name Field of Contact object

FIND {John OR Ravi} Returning Contact(Name, Phone)

Difference between SOQL and SOSL : 

SOQL	SOSL
Salesforce Object Ouery Language	Salesforce Object Search Language
Used to retrive data from single object or multiple objects that are related with each other	Fetches data from multiple un-related objects
It returns records.	It returns fields.
Not more than 50,000 records can be fetched	Not more than 2000 records can be fetched.
SELECT Id, Name FROM Account	FIND {John}
Total number of SOQL queries issued Synchronous Limit : 100 Asynchronous Limit : 200	Total number of SOSL queries issued : 20
We can query on all fields of any data type.	We can query on fields whose data type is Name, Phone, Email.
Return Type: List	Return Type: List Of Lists.

Reference : 
# SOSL Trailhead Module 

# SOSL Syntax 

# Apex Governor Limits 

# SOQL in Apex