Force.com SOQL and SOSL Reference

Salesforce Object Query Language (SOQL)
Salesforce Object Search Language (SOSL)
About SOSL
SOSL Typographical Conventions
SOSL Syntax
FIND {SearchQuery}
IN SearchGroup
RETURNING FieldSpec
WHERE conditionExpression
ORDER BY Clause
UPDATE TRACKING
UPDATE VIEWSTAT
WITH DivisionFilter
WITH DATA CATEGORY DataCategorySpec
WITH NETWORK NetworkIdSpec
WITH SNIPPET
LIMIT n
OFFSET n
toLabel(fields)
Querying Currency Fields in Multicurrency Organizations
Example Text Searches
SOSL Limits
PDF

Newer Version Available

This content describes an older version of this product. View Latest

SOSL Syntax

A SOSL query begins with the required FIND clause and then can have optional clauses to filter the query by object type, by fields, based on data categories, and more. You can also determine what is returned. For example, you can determine the order in which results are returned, how many rows are returned, and more.

The SOSL query syntax consists of a required FIND clause followed by one or more optional clauses in the following order:

1FIND {SearchQuery} 
2[ IN SearchGroup [ convertCurrency(Amount)] ]
3[ RETURNING FieldSpec [ toLabel(fields)] ]
4[ WITH DivisionFilter ]
5[ WITH DATA CATEGORY DataCategorySpec ]
6[ WITH SNIPPET[(target_length=n)] ]
7[ WITH NETWORK NetworkIdSpec ]
8[ LIMIT n ]
9[ OFFSET n ]
10[ UPDATE [TRACKING], [VIEWSTAT] ]

where:

Syntax Description
FIND {SearchQuery} Required. Specifies the text (words or phrases) to search for. The search query must be delimited with curly braces.

If the SearchQuery string is longer than 10,000 characters, no result rows are returned. If SearchQuery is longer than 4,000 characters, any logical operators are removed. For example, the AND operator in a statement with a SearchQuery that’s 4,001 characters will default to the OR operator, which could return more results than expected.
IN SearchGroup Optional. Scope of fields to search. One of the following values:
  • ALL FIELDS
  • NAME FIELDS
  • EMAIL FIELDS
  • PHONE FIELDS
  • SIDEBAR FIELDS
If unspecified, then the default is ALL FIELDS. You can specify the list of objects to search in the RETURNING FieldSpec clause.

This clause doesn't apply to articles, documents, feed comments, feed items, files, products, and solutions. If any of these objects are specified in the RETURNING clause, the search is not limited to specific fields; all fields are searched.

Note
convertCurrency(Amount) Optional. If an organization is multicurrency enabled, converts currency fields to the user's currency.
RETURNING FieldSpec Optional. Information to return in the search result. List of one or more objects and, within each object, list of one or more fields, with optional values to filter against. If unspecified, then the search results contain the IDs of all objects found.
toLabel(fields) Optional. Results from a query are returned translated into the user’s language.
WITH DivisionFilter Optional. If an organization uses divisions, filters all search results based on values for the Division field.
WITH DATA CATEGORY DataCategorySpec Optional. If an organization uses Salesforce Knowledge articles or answers, filters all search results based on one or more data categories.
WITH SNIPPET [(target_length=n)] Optional. If an organization uses Salesforce Knowledge articles, displays contextual snippets and highlights the search term for each article in the search results. By default, each snippet displays up to about 300 characters, which is usually about three lines of text in a standard browser window. Add the optional target_length parameter to specify an alternate target length, which can be from 100 and 500 characters.
WITH NETWORK NetworkIdSpec Optional. Filters search results by community ID.
LIMIT n Optional. Specifies the maximum number of rows returned in the text query, up to 2,000. If unspecified, the default is 2,000, the largest number of rows that can be returned. These limits apply to API version 28.0 and later. Previous versions support a maximum of 200 rows returned.
[ UPDATE [TRACKING | VIEWSTAT][,...] ] ] Optional. If an organization uses Salesforce Knowledge:
  • UPDATE TRACKING tracks keywords used in Salesforce Knowledge article search.
  • UPDATE VIEWSTAT updates an article’s view statistics.
  • UPDATE TRACKING, VIEWSTAT does both.

The SOSL statement character limit is tied to the SOQL statement character limit defined for your organization. By default, SOQL and SOSL queries cannot exceed 20,000 characters. For SOSL statements that exceed this maximum length, the API returns a MALFORMED_SEARCH exception code; no result rows are returned.

Note