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.

1FIND {San Francisco} IN ALL FIELDS RETURNING KnowledgeArticleVersion(id, title WHERE PublishStatus = 'Online' AND Language = 'en_US') WITH
2      SNIPPET (target_length=120)

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

1[ {
2  "attributes" : {
3    "type" : "KnowledgeArticleVersion",
4    "url" : "/services/data/v32.0/sobjects/KnowledgeArticleVersion/kaKD00000000001MAA"
5  },
6  "Id" : "kaKD00000000001MAA"
7  "Title" : "San Francisco"
8  "Summary" : "City and County of San Francisco"
9  "snippet.text" : "<mark>San</mark> <mark>Francisco</mark>, officially the City and County of <mark>San</mark> <mark>Francisco</mark> is the... City and County of <mark>San</mark> <mark>Fran</mark>" 
10  "highlight.Title" : "<mark>San</mark> <mark>Francisco</mark>"
11}, {
12   "attributes" : {   
13     "type" : "KnowledgeArticleVersion",
14     "url" : "/services/data/v32.0/sobjects/KnowledgeArticleVersion/kaBD0000000007DMAQ"
15   },
16   "Id" : "kaBD0000000007DMAQ",
17   "Title" : "San Francisco Bay Area",
18   "Summary" : "Nine county metropolitan area",
19   "snippet.text" : "The <mark>SF</mark> Bay Area, commonly known as the Bay Area, is a populated region that"
20   "highlight.Title" : "<mark>San</mark> <mark>Francisco</mark> Bay Area"
21}, {
22   "attributes" : {
23     "type" : "KnowledgeArticleVersion",
24     "url" : "/services/data/v32.0/sobjects/KnowledgeArticleVersion/ka3D0000000042OIAQ"
25   },
26   "Id" : "ka3D0000000042OIAQ",
27   "Title" : "California",
28   "Summary" : "State of California",
29   "snippet.text" : "(Greater Los Angeles area and <mark>San</mark> <mark>Francisco</mark> Bay Area, respectively), and eight of the nation’s 50 most"
30  } ]

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:
1FIND {San Francisco} IN ALL FIELDS RETURNING FeedItem, FeedComment WITH SNIPPET (target_length=120)

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.

1For more information, visit &lt;a href='http://salesforce.com'&gt;salesforce.com&lt;/a&gt;

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.

1FIND {San Francisco} IN ALL FIELDS RETURNING KnowledgeArticleVersion(id, title WHERE PublishStatus = 'Online' AND Language = 'en_US') WITH
2      SNIPPET(target_length=120)

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.

Salesforce Knowledge Developer Guide

WITH SNIPPET

Example

Example

Usage

Escaped HTML Tags

Example

Target Snippet Length

Example

Supported APIs