SOSL (Salesforce Object Search Language)
SOSL (Salesforce Object Search Language) is the full-text search language for Salesforce records.
Definition
SOSL (Salesforce Object Search Language) is the full-text search language for Salesforce records. Where SOQL queries one object and returns typed records, SOSL searches across multiple objects at once using a single text expression, returning matching records from each object as a separate list. It is the same engine that powers the global search bar at the top of the Salesforce UI, and it is the right tool whenever a user or integration needs to find records based on free-text matching rather than exact field filters.
A SOSL statement looks like: FIND {Acme} IN ALL FIELDS RETURNING Account(Id, Name), Contact(Id, FirstName, LastName), Opportunity(Id, Name). The search expression goes inside curly braces and supports wildcards, phrase matching with quotes, boolean operators (AND, OR, NOT), and proximity operators. The RETURNING clause lists the objects to search and the fields to return for each. SOSL queries hit a precomputed text index, which makes them much faster than equivalent LIKE-based SOQL on text fields, but the index has its own freshness lag (typically a few seconds after a record is saved).
How SOSL searches across Salesforce records
When SOSL beats SOQL
SOSL fits when the search is text-based, the user does not know which object holds the match, and the platform needs to find candidate records across many objects in one call. Global search, dropdown lookups, type-ahead pickers, and "search across everything" features all use SOSL under the hood. SOQL fits when the query is field-precise, scoped to one object, and the filters are exact. The dividing line is "find records that contain the word Acme somewhere" (SOSL) versus "find records where Name equals Acme Corporation" (SOQL).
The search index and freshness lag
SOSL hits a precomputed text index, not the live record tables. The index is updated asynchronously after each record save, with a typical lag of a few seconds to a few minutes depending on org load. This is invisible most of the time but matters for integrations that save a record and immediately try to search for it. The pattern is: save the record, do not assume SOSL will find it for at least 30 seconds. For immediate lookup, use SOQL on the indexed field directly.
IN ALL FIELDS versus IN NAME FIELDS versus IN PHONE FIELDS
The IN clause narrows which fields the search expression matches against. IN ALL FIELDS searches every text field on the listed objects (slowest, broadest). IN NAME FIELDS searches Name and similar identifier fields (fastest, most common for global-search). IN PHONE FIELDS searches phone fields with formatting normalization. IN EMAIL FIELDS searches email fields. IN SIDEBAR FIELDS searches fields configured for legacy sidebar search. Picking the right IN clause is the single biggest performance lever in SOSL.
Wildcards, phrase matching, and operators
The search expression supports * for multi-character wildcards (Acme* matches Acme, Acmel, Acmeify), ? for single-character wildcards, double-quotes for exact phrase matching ("Acme Corporation" matches the phrase only), and the operators AND, OR, NOT for boolean combinations. Operators must be uppercase to distinguish from search terms. Wildcards at the start of a term (*Acme) are not allowed because the search index cannot use them efficiently.
Returning fields and per-object filters
The RETURNING clause specifies which objects to search and which fields to return for each. Each object can also have its own WHERE clause: RETURNING Account(Id, Name WHERE Industry = ''Tech'') filters Account results by Industry while still searching the text expression against Name. ORDER BY and LIMIT also apply per object inside the RETURNING clause. This per-object scoping is what makes SOSL useful for typeahead pickers that need both a text match and a relevance filter.
Apex syntax and result handling
Apex embeds SOSL with square-bracket syntax: List<List<SObject>> results = [FIND {Acme} IN ALL FIELDS RETURNING Account(Id, Name), Contact(Id, FirstName)]. The result is a list of lists, with one nested list per object in the RETURNING clause, in the same order. Access Account results as (List<Account>) results[0] and Contact results as (List<Contact>) results[1]. Apex SOSL counts against the 20 SOSL queries per transaction governor limit, separate from the 100 SOQL queries.
Limits and when SOSL falls short
SOSL caps at 2,000 records per object in the RETURNING list and 20,000 records across all objects per query. Each Apex transaction supports 20 SOSL calls and 20,000 returned records total. The search index does not include every field type; encrypted fields, formula fields that compute at read time, and some long-text fields may not be searchable. SOSL also struggles with very short search terms (under three characters) because the index is tokenized and short tokens do not produce useful matches.
How to write effective SOSL queries
SOSL has a small surface area but real subtlety in performance tuning. Pick the right IN clause, scope the RETURNING list to the objects you actually need, add per-object filters to narrow results, and remember the index freshness lag when integrating with save-then-search patterns. Build queries in the Developer Console first to validate output before embedding in Apex or REST calls.
- Confirm SOSL is the right tool
Use SOSL when the search is text-based, spans multiple objects, or matches free-text content. Use SOQL when the query is field-precise on one object. A single-object exact-match search runs faster as SOQL on an indexed field.
- Open the Developer Console Query Editor
Setup > Developer Console > Query Editor > switch to SOSL mode. The editor provides syntax checking and instant execution. Use it to draft and refine the search expression and RETURNING clause.
- Write the FIND clause with the right search expression
Use curly braces for the search text: FIND {Acme}. Wildcards (*, ?) and phrase quotes work inside the braces. Use uppercase AND, OR, NOT to distinguish boolean operators from search terms.
- Pick the right IN clause
IN NAME FIELDS is fastest and right for global-search patterns. IN ALL FIELDS is broad and slow, use sparingly. IN PHONE FIELDS, IN EMAIL FIELDS narrow to those types when the search is type-specific.
- List the RETURNING objects with field lists
RETURNING Account(Id, Name), Contact(Id, FirstName, LastName). Each object gets its own field list. Add per-object WHERE clauses to filter results: Account(Id, Name WHERE Industry = ''Tech'').
- Test the query in the Developer Console
Run with Execute. Verify the result count per object, check that the search terms match expected records, and confirm performance is acceptable. Refine the search expression and IN clause as needed.
- Embed in Apex with proper result handling
List<List<SObject>> results = [FIND :searchTerm IN ALL FIELDS RETURNING Account(Id, Name)]. Bind variables prevent injection. Cast each nested list to the typed sObject array: (List<Account>) results[0].
- Handle empty results gracefully
Empty SOSL results return empty lists, not nulls. Check list size before iterating. Also handle the freshness-lag case if the search is downstream of a recent record save.
Determines which fields the search expression matches against. IN NAME FIELDS for global search, IN ALL FIELDS for broad search, narrower IN clauses for specific field types.
Lists the objects to search and fields to return. Scope to needed objects; broad lists slow the query down.
Optional filters inside RETURNING that narrow results per object. Useful for typeahead pickers that need both text match and relevance filtering.
- The search index updates asynchronously after each record save. Integrations that save a record and immediately search for it may not find the new record for several seconds.
- Wildcards at the start of a term (*Acme) are not allowed because the index cannot use them efficiently. Use trailing wildcards (Acme*) or exact-match search instead.
- SOSL queries cap at 2,000 records per object and 20,000 total across objects. Larger result sets are silently truncated. Tune the search to be more selective or paginate via the SOAP/REST search APIs.
- Short search terms (under three characters) often return no results because the index tokenizes content and short tokens do not produce useful matches.
- Apex SOSL counts against a separate 20-queries-per-transaction limit. Triggers that fire SOSL on every record save hit this fast on bulk operations.
Trust & references
Cross-checked against the following references.
- SOSL ReferenceSalesforce Developer
- Introduction to SOSLSalesforce Developer
- SOQL and SOSL LimitsSalesforce Developer
Straight from the source - Salesforce's reference material on SOSL (Salesforce Object Search Language).
- SOSL ReferenceSalesforce Developer
- About SOSL SearchesSalesforce Developer
- Salesforce Search OverviewSalesforce Help
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is SOSL?
Q2. How does SOSL differ from SOQL?
Q3. When use SOSL?
Discussion
Loading discussion…