Force.com SOQL and SOSL Reference

Introduction to SOQL and SOSL
Salesforce Object Query Language (SOQL)
Salesforce Object Search Language (SOSL)
Typographical Conventions in This Document
SOSL Limits
SOSL Limits on External Objects
SOSL Syntax
Example Text Searches
convertCurrency()
FIND {SearchQuery}
FORMAT()
IN SearchGroup
LIMIT n
OFFSET n
ORDER BY Clause
RETURNING FieldSpec
toLabel(fields)
Update an Article’s Keyword Tracking with SOSL
Update an Article’s Viewstat with SOSL
WHERE conditionExpression
WITH DATA CATEGORY DataCategorySpec
WITH DivisionFilter
WITH HIGHLIGHT
WITH METADATA
WITH NETWORK NetworkIdSpec
WITH PricebookId
WITH SNIPPET
PDF

Newer Version Available

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

WITH SNIPPET

WITH SNIPPET is an optional clause that can be added to a SOSL query for article, case, feed, and idea searches. On the search results page, excerpts below article titles show terms matching the search query highlighted within the context of surrounding text. Snippets make it easier for users to identify the content they’re looking for.

To generate search results with highlighted matches but not snippets, use WITH HIGHLIGHT.

Note

Search snippets and highlights are generated from the following field types.
  • Email
  • Text
  • Text Area
  • Text Area (Long)
  • Text Area (Rich)

Search snippets and highlights are not generated from the following field types.

  • Checkbox
  • Currency
  • Date
  • Date/Time
  • File
  • Formula
  • Lookup Relationship
  • Number
  • Percent
  • Phone
  • Picklist
  • Picklist (Multi-Select)
  • URL

Example

The following SOSL statement returns snippets for articles that match the search term San Francisco.

The matching terms are highlighted with <mark> tags within the context of the snippet results. Stemmed forms of the term and any synonyms defined are also highlighted.

Example

In this example, “SF” (as a synonym defined for “San Francisco”) and “San Fran” (as a stemmed form of “San Francisco”) are also highlighted in the results as matching terms.

Note

Usage

For SOSL statements using the WITH SNIPPET clause, we recommend using a RETURNING ObjectTypeName clause, with a WHERE clause that filters on the PublishStatus field.

In the RETURNING clause, specify one of the following for ObjectTypeName:
  • To search a specific article type, use the article type name with the suffix __kav.
  • To search all article types, use KnowledgeArticleVersion.
  • To search case, case comment, feed, feed comment, idea, and idea comment types, use Case, CaseComment, FeedItem, FeedComment, Idea, and IdeaComment. For example:

Other objects that are included in searches that contain WITH SNIPPET don’t return snippets.

Snippets aren’t displayed for search terms that contain a wildcard, when the search doesn’t return any articles, or if the user doesn’t have access to the field that contains the snippet. Even if you add the WITH SNIPPET clause, searches that don’t return snippets don’t return snippets.

Snippets are only displayed when 20 or fewer results are returned on a page.

Use the LIMIT or OFFSET clause to return only 20 results at a time.

Tip

Escaped HTML Tags

When matching terms within HTML tags are returned in a snippet, the HTML tags are escaped and the matching terms are highlighted in the results.

Example

A search for salesforce returns an article with the text “For more information, visit <a href='http://salesforce.com'>salesforce.com</a>”. The original hyperlink tags from the article are escaped (encoded) and “salesforce” is highlighted in the snippet result.

Target Snippet Length

By default, each snippet displays up to approximately 300 characters, which is usually three lines of text in a standard browser window display. The number of characters displayed is the target length, within a statistically insignificant degree of variance.

Snippets consist of one or more fragments of text that contain the matching terms. If the returned snippet includes multiple text fragments (for example, for matches within multiple fields), the target length is the maximum total length of all the returned fragments.

To specify an alternate target length, add the optional target_length parameter to the WITH SNIPPET clause. You can specify a target length from 50 to 1,000 characters. When the target_length is set to an invalid number, such as 0 or a negative number, the length defaults to 300.

Example

A target_length parameter of 120 characters is useful for displaying a snippet of approximately three lines of text in a standard mobile interface.

Supported APIs

The WITH SNIPPET clause can be used in API version 32.0 or later. The WITH SNIPPET clause in SOSL is supported in SOAP API, REST API, and Apex.