Salesforce Knowledge Developer Guide
jWITH SNIPPET
Search snippets and highlights are generated from some field types but not others.
| Supported Field Types | Not Supported Field Types |
|---|---|
| Checkbox | |
| Text | Currency |
| Text Area | Date |
| Text Area (Long) | Date/Time |
| Text Area (Rich) | File |
| Formula | |
| Lookup Relationship | |
| Number | |
| Percent | |
| Phone | |
| Picklist | |
| Picklist (Multi-Select) | |
| URL |
Example
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 } ]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:
- When search terms contain a wildcard.
- When the search doesn’t return any articles.
- If the user doesn’t have access to the field that contains the snippet.
- When the search term doesn’t appear in the first 6000 characters of the field, excluding HTML tags.
Even if you add the WITH SNIPPET clause, some searches don’t return snippets. If an object contains more than 50 fields, snippets are sometimes not generated.
Snippets are only displayed when 20 or fewer results are returned on a page.
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
1For more information, visit <a href='https://salesforce.com'>salesforce.com</a>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
1FIND {San Francisco} IN ALL FIELDS RETURNING KnowledgeArticleVersion(id, title WHERE PublishStatus = 'Online' AND Language = 'en_US') WITH
2 SNIPPET(target_length=120)