--- schema_version: "1" id: c826964dd0c9b729e175f5d8bb6503b1c4cfa61e841acc9f4e4714d7f84c3fde title: WITH SNIPPET collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/platform/salesforce-soql-sosl/guides/soql-sosl/sforce-api-calls-sosl-with-snippet.md canonical_url: https://developer.salesforce.com/docs/platform/salesforce-soql-sosl/guide/sforce-api-calls-sosl-with-snippet.html source_site: developer.salesforce.com content_type: documentation content_hash: 15ca9bb593503493d7cf1fc3601c9cdf08e7398cbae410e8f0d6d643dfa88b3c products: - SOQL and SOSL Reference - Platform Developer Content --- # 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. Search snippets and highlights are generated from the following field types. **note:** To generate search results with highlighted matches but not snippets, use `WITH HIGHLIGHT`. - 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`. ```nolang FIND {San Francisco} IN ALL FIELDS RETURNING KnowledgeArticleVersion(id, title WHERE PublishStatus = 'Online' AND Language = 'en_US') WITH SNIPPET (target_length=120) ``` The matching terms are highlighted with `` tags within the context of the snippet results. Stemmed forms of the term and any synonyms defined are also highlighted. ## Example ```nolang [ { "attributes" : { "type" : "KnowledgeArticleVersion", "url" : "/services/data/v32.0/sobjects/KnowledgeArticleVersion/kaKD00000000001MAA" }, "Id" : "kaKD00000000001MAA" "Title" : "San Francisco" "Summary" : "City and County of San Francisco" "snippet.text" : "San Francisco, officially the City and County of San Francisco is the... City and County of San Fran" "highlight.Title" : "San Francisco" }, { "attributes" : { "type" : "KnowledgeArticleVersion", "url" : "/services/data/v32.0/sobjects/KnowledgeArticleVersion/kaBD0000000007DMAQ" }, "Id" : "kaBD0000000007DMAQ", "Title" : "San Francisco Bay Area", "Summary" : "Nine county metropolitan area", "snippet.text" : "The SF Bay Area, commonly known as the Bay Area, is a populated region that" "highlight.Title" : "San Francisco Bay Area" }, { "attributes" : { "type" : "KnowledgeArticleVersion", "url" : "/services/data/v32.0/sobjects/KnowledgeArticleVersion/ka3D0000000042OIAQ" }, "Id" : "ka3D0000000042OIAQ", "Title" : "California", "Summary" : "State of California", "snippet.text" : "(Greater Los Angeles area and San Francisco Bay Area, respectively), and eight of the nation’s 50 most" } ] ``` **note:** 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. ## 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](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_knowledgearticleversion.htm). - To search case, case comment, feed, feed comment, idea, and idea comment types, use `Case`, `CaseComment`, `FeedItem`, `FeedComment`, `Idea`, and `IdeaComment`. For example: ```nolang FIND {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. **tip:** Use the `LIMIT` clause to return only 20 results at a time. ## 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 `salesforce.com`. The original hyperlink tags from the article are escaped (encoded) and “salesforce” is highlighted in the snippet result. ```soql For 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 A `target_length` parameter of 120 characters is useful for displaying a snippet of approximately three lines of text in a standard mobile interface. ```soql FIND {San Francisco} IN ALL FIELDS RETURNING KnowledgeArticleVersion(id, title WHERE PublishStatus = 'Online' AND Language = 'en_US') WITH 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.