Salesforce Object Search Language (SOSL)

Use the Salesforce Object Search Language (SOSL) to construct text-based search queries against the search index.

When building efficient SOSL queries, create filters that are selective. Search analyzes all records in the index and by default, only the top 2,000 matched records are returned based on relevancy. This API supports pagination to fetch additional matches. Sharing is applied after the result set is returned from the search stack. If your filters aren’t selective and cause search term matches of more than 2000 records, there’s a possibility of running into search crowding.

You can search text, email, and phone fields for multiple objects, including custom objects, that you have access to in a single query in the following environments.

  • SOAP API search() calls. See search() in the SOAP API Developer Guide.
  • REST API Search calls. See Search in the REST API Developer Guide.
  • Apex statements. See SOQL and SOSL Queries in the Apex Developer Guide.
  • Visualforce controllers and getter methods. See Controller Methods in the Visualforce Developer Guide.
  • Schema Explorer of the Eclipse Toolkit. See Schema Explorer in the IDE Developer Guide.

If your org has relationship queries enabled, SOSL supports SOQL relationship queries.


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.

Performance Considerations

If your searches are too general, they’re 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.

Navigating This Document