---
title: Smart Snippets implementation overview
slug: l9le0392
canonical_url: https://docs.coveo.com/en/l9le0392/
collection: leverage-machine-learning
source_format: adoc
---
# Smart Snippets implementation overview

To provide relevant [snippets](https://docs.coveo.com/en/laeb0292/) of content in a search results list, [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) [Smart Snippets](https://docs.coveo.com/en/laea5490/) [models](https://docs.coveo.com/en/1012/) require the content they use to be formatted in a certain way.
This article provides best practices for properly scoping, formatting, and testing the content you want the model to use.

## Step 1: Scope the content

To optimize the output of a Coveo ML Smart Snippet model, we strongly recommend that you first identify the content that the model must use.
This will help you better understand how to configure the model.

### Item language value

Coveo Smart Snippet models return snippets of content only for items whose `language` [field](https://docs.coveo.com/en/200/) value is `English`.

> **Note**
>
> Other languages are supported as a beta.
> For a list of beta-supported languages, see [Supported languages for machine learning models](https://docs.coveo.com/en/1956#supported-languages-for-machine-learning-models).

### HTML content

Coveo Smart Snippet models only return snippets of content for [items](https://docs.coveo.com/en/210/) that contain content in HTML format.
Therefore, you should ensure that the content that you want to use for creating the model contains HTML elements.

> **Leading practice**
>
> You can use the [**Content Browser**](https://platform.cloud.coveo.com/admin/#/orgid/content/browser/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/content/browser/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/content/browser/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/content/browser/)) page of the [Coveo Administration Console](https://docs.coveo.com/en/183/) to verify the items that are available for the model.
> 
> For example, you select the **My Source** [source](https://docs.coveo.com/en/246/) and **HTML File** file type to find the items from the **My Source** source that can be used as input by the model.
> 
> ![Content Browser with field selections to target html items in a given source](:https://docs.coveo.com/en/assets/images/leverage-machine-learning/html-items-ss.png)

> **Important**
>
> When checking the items that could be usable by the model in the [**Content Browser**](https://platform.cloud.coveo.com/admin/#/orgid/content/browser/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/content/browser/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/content/browser/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/content/browser/)), the number of items that match your requirements may differ from the number of items you'll see when inspecting the item count of your model's [build statistics](https://docs.coveo.com/en/1894#smart-snippets).
> 
> During the build process, the model can ignore some items because they either contain invalid HTML, or no snippets could be extracted from the parsed HTML.

### permanentid field

The items from which you want the model to extract snippets must use the value of the [`permanentid`](https://docs.coveo.com/en/1913/) field as their unique identifier.

> **Leading practice**
>
> You can use the [**Content Browser**](https://platform.cloud.coveo.com/admin/#/orgid/content/browser/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/content/browser/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/content/browser/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/content/browser/)) page of the Coveo Administration Console and [check an item's proprieties](https://docs.coveo.com/en/1712/) to verify whether an item uses the `permanentid` as its unique identifier.

### Document types

When you inspect the items that the model can use (that is, items containing the required HTML tags in a given source), you may notice that many of these items are available, but not all of them are relevant for the model.

When [configuring a Coveo ML Smart Snippet model](https://docs.coveo.com/en/l6he0424#create-a-smart-snippet-model), you can optionally target certain document types that must be used by the model.
This allows you to further narrow the content that the model will use as an input.

**Example**

The content you want the model to extract resides in a Salesforce source. This content is available in items whose `documenttype` has the `Knowledge` value. Therefore, you select `Knowledge` in the **Document type** dropdown menu so that the model uses only items whose `documenttype` field value is `Knowledge`.

In the [**Content Browser**](https://platform.cloud.coveo.com/admin/#/orgid/content/browser/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/content/browser/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/content/browser/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/content/browser/)) page of the Coveo Administration Console, you can verify the items that would be available for the model by scoping the items that have the `Knowledge` value for the `documenttype` field. For example, you can use a [field query](https://docs.coveo.com/en/1552#field-queries) to scope the documents as follows:

![Content Browser with field selections to target knowledge items in a given source | Coveo](https://docs.coveo.com/en/assets/images/leverage-machine-learning/knowledge-items-ss.png)

### Content fields

When you inspect the items that the model can use (that is, items of a specific [document type](#document-types) containing the required HTML tags in a given source), you may notice that these items contain multiple [fields](https://docs.coveo.com/en/200/) that embed HTML content.
The content of some of these fields may not be relevant and you may not want the model to use it.

When [configuring a Coveo ML Smart Snippet model](https://docs.coveo.com/en/l6he0424#create-a-smart-snippet-model), you can optionally target certain fields to be used by the model.
This allows you to further narrow the content that the model will use as an input.
If you don't mention specific fields, the model will use the value of the item `body` field by default.

**Example**

The content you want the model to extract resides in a Salesforce source. The relevant information, formatted in HTML, is located in a custom field named `sf_case_details_c`.
Therefore, you select the `sf_case_details_c` field in the **Field(s) containing HTML content** dropdown menu so that the model uses only the content that appears in the `sf_case_details_c` field when extracting the document.

In the [**Content Browser**](https://platform.cloud.coveo.com/admin/#/orgid/content/browser/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/content/browser/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/content/browser/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/content/browser/)) page of the Coveo Administration Console, you can verify the items that contain the `sf_case_details_c` field.
For example, you can use a [field query](https://docs.coveo.com/en/1552#field-queries) to scope items of the **My Salesforce Source** source whose `documenttype` value is `Knowledge` and that contains the `sf_case_details_c` field as follows:

![Content Browser with field selections to target specific items in a given source | Coveo](https://docs.coveo.com/en/assets/images/leverage-machine-learning/fields-ss.png)

## Step 2: Optimize the content

Now that you've targeted the content that must be used by the model, you must ensure that this content is properly configured.

Coveo ML Smart Snippets establish correlations between the headers appearing in result items and user queries.
Therefore, your content must be configured accordingly.

For optimal results, we recommend that you use [Google structured data](https://developers.google.com/search/docs/data-types/faqpage) in JSON-LD format in the `<head>` of the HTML items that must be used by the model to extract snippets.

The following code sample shows a simple HTML markup that contains JSON-LD formatted content within the `<head>`:

```html
<html>
  <head>
    <title>Example Site - Frequently Asked Questions(FAQ)</title>
    <script type="application/ld+json">
    {
      "@context": "https://schema.org",
      "@type": "FAQPage",
      "mainEntity":[{
        "@type": "Question",
        "name": "What is Smart Snippets?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "<p>Coveo Smart Snippet models provide users with answers to their queries directly on the results page by displaying a snippet of the most relevant result item. This allows users to quickly find answers without having to open links from the results page.</p>"]
    }
    </script>
  </head>
  <body>
  </body>
</html>
```

> **Important**
>
> If you're using a Web or Sitemap [source](https://docs.coveo.com/en/246/), don't exclude `<script>` elements from your content.
> 
> * If you're using the [default Coveo web scraping configuration](https://docs.coveo.com/en/malf0160#web-scraping-subtab) with either of these sources, remove the `CSS script` selector from the **Elements to exclude** list of selectors.
> 
> * If you're using a Web source and you've set a value for the [`ElementsToRemove`](https://docs.coveo.com/en/mc1f0219#elementstoremove-array-of-strings) parameter, make sure this array doesn't include the `script` string.
> If the `ElementsToRemove` parameter isn't defined in the JSON configuration, set it to an empty array as shown below:
>  
> ```json
"ElementsToRemove": {
  "sensitive": false,
  "value": "[]"
}
```

However, Coveo ML Smart Snippets will also work with raw HTML.
When using this approach, it must be noted that Coveo ML Smart Snippet models don't exclude navigation menus, featured content, or any other peripheral content in an item.
To help the algorithm identify this type of content, you should specify [CSS properties to exclude](https://docs.coveo.com/en/l6he0424#css-properties-to-exclude).

> **Notes**
>
> * If your web page doesn't contain Google structured data, and the questions contained on the web page aren't formatted using HTML headers (`<h>` tags), you can use the [pre-conversion IPE extension script](https://docs.coveo.com/en/lc6d0080/) to specify CSS selectors to identify questions and answers in an HTML item.
> 
> * If the content you want the model to use [resides in specific fields](https://docs.coveo.com/en/l6he0424#content-field), and that this content isn't properly configured to be optimally used by the model (for example, the item doesn't contain JSON-LD, or well-formatted HTML) you can use the [post-conversion IPE extension script](https://docs.coveo.com/en/m52a0468/) to specify fields whose content will be identified as questions and answers, and converted in JSON-LD format.

## HTML supported tags

In an item, a Smart Snippet model takes the content that appears within the following tags into consideration when they're attached to the last header (`<h>` tag) in a header stack:

* `<br>`

* `<ol>`

> **Note**
>
> Smart Snippet models support the `start` attribute in `<ol>` tags

* `<ul>`

* `<li>`

* `<p>`

* `<b>`


* `<i>`

* `<em>`

* `<span>`

* `<a>`

> **Notes**
>
> * For a snippet to correctly render the hyperlink, the URL value used in the `href` attribute must be absolute and use a secure scheme (that is, `https://`).
> 
> * When a user clicks an inline link displayed on a snippet, the [`openSmartSnippetInlineLink`](https://docs.coveo.com/en/m62a0057#click-event) click event is logged.
> This can be useful to report on the usage of links displayed in snippets.

**Example**

Considering a page that is configured as follows:

```html
<body>
<h1>FAQ</h1>
    <h2>Synchronizing Speedbit Watches</h2>
        <p>The procedure differs depending on the device with which you want to synchronize your watch.</p>
            <h3>Synchronizing a Speedbit Watch With a Smartphone</h3>
                <p>Procedure to synchronize your Speedbit watch with your smartphone.</p>
            <h3>Synchronizing a Speedbit Watch With a Computer</h3>
                <p>Procedure to synchronize your Speedbit watch with your computer.</p>
</body>
```

The model would process the page as follows:

```json
[
  {"headers":  ["FAQ", "Synchronizing Speedbit Watches", "Synchronizing a Speedbit Watch With a Smartphone"], "excerpt": "<p>Procedure to synchronize your Speedbit watch with your smartphone.</p>"},
  {"headers":  ["FAQ", "Synchronizing Speedbit Watches", "Synchronizing a Speedbit Watch With a Computer"], "excerpt": "<p>Procedure to synchronize your Speedbit watch with your computer.</p>"}
]
```

> **Important**
>
> * Coveo ML Smart Snippets ignores the content that appears within the following tags:
> 
> ** `<script>`
> 
> ** `<style>`
> 
> ** `<form>`
> 
> ** `<table>`
> 
> ** `<img>`
> 
> ** `<input>`


:leveloffset!:

## Step 3: Create the model

Now that you've [scoped the content that must be used by the model](#step-1-scope-the-content) and [your content is properly formatted](#step-2-optimize-the-content), you can create your Coveo ML Smart Snippet model and configure it as desired.

See [Create a Smart Snippet model](https://docs.coveo.com/en/l6he0424#create-a-smart-snippet-model) for instructions on how to create a Coveo ML Smart Snippet model.

### Review the model build information

Now that your model is created and is [**Active**](https://docs.coveo.com/en/l6he0424#status-column), you can verify whether the model is able to provide snippets of content.

The [Get detailed information about a specific model call](https://platform.cloud.coveo.com/docs?urls.primaryName=Machine%20Learning#/Machine%20Learning%20Models/rest_organizations_paramId_machinelearning_models_paramId_details_get) of the [Machine Learning Models API](https://docs.coveo.com/en/19/) allows you to obtain detailed information about your Coveo ML Smart Snippet model, such as:

* The number of items it can use to extract snippets of content.

* The number of HTML headers it can target to find related content.

* The average length of the snippets it extracted.

* The total number of snippets that the model can provide.

When performing this API call, you should receive a response that contains a `modelBuildingStats` object as follows:

```json
"modelBuildingStats": {
    "documentCount": 2688,
    "headerCount": 11239,
    "meanSnippetLength": 104.94903911094738,
    "snippetCount": 16287
}
```

## Step 4: Associate the model with the desired query pipeline

Now that your [model is created](#step-3-create-the-model), you must associate the model with the [query pipeline](https://docs.coveo.com/en/180/) to which the traffic of the desired [search interface](https://docs.coveo.com/en/2741/) is directed.

See [Associate a Smart Snippet model with a query pipeline](https://docs.coveo.com/en/l6he0309/) for instructions on how to associate your model with a query pipeline.

## Step 5: Configure the search interface

Now that your [model is configured](#step-3-create-the-model), and [associated with the query pipeline](#step-4-associate-the-model-with-the-desired-query-pipeline) to which the traffic of the desired search interface is directed, you must configure the search interface to include the components that will allow the model to render its output.

See [Configure a search interface for Smart Snippets](https://docs.coveo.com/en/l8ve0354/) for instructions.

## Step 6: Test the model

Now that your [model is configured](#step-3-create-the-model) and your [search interface is set up](#step-5-configure-the-search-interface) to display the model's output, you can test the model to ensure that everything works as expected.

You can test the model on a search interface that contains the required components, and for which the traffic is directed to the [query pipeline that you associated with your Coveo ML Smart Snippet model](https://docs.coveo.com/en/l9le0392#step-4-associate-the-model-with-the-desired-query-pipeline).

Perform a query that would likely trigger a snippet to appear in the search results.

**Example**

You scope an item for your model from which to extract snippets.
It contains a header that reads `When exactly is a model retrained?`.

When you perform the query `When is a model retrained`, you see the following:

![Example of a Smart Snippet model in action | Coveo](https://docs.coveo.com/en/assets/images/leverage-machine-learning/ss-example-gif.gif)

You can also inspect the request to the Search API to get detailed information about the model's output for a given query.

. Access a [search interface which contains the required components](https://docs.coveo.com/en/l8ve0354/), and in which the traffic is directed to the query pipeline that you [associated with your Coveo ML Smart Snippet model](https://docs.coveo.com/en/l6he0309/).

. [Access your browser's network monitoring tool](https://docs.coveo.com/en/mc2g0297#access-your-browsers-network-monitoring-tool).

. In the search box, perform a query that would likely trigger a snippet to appear in the search results.

. In the network monitoring tool, under the **Name** column, select the latest request to the Search API.
The request path should contain `/rest/search/v2`.

. Select the **Preview** tab.

. Find and expand the [`questionAnswer`](https://docs.coveo.com/en/l9le0392#search-api-response-reference) property.
It provides detailed information about the model's output for this specific query.
This property won't appear if the model can't provide snippets for the current query.

![Search API response for a smart snippet model | Coveo](https://docs.coveo.com/en/assets/images/leverage-machine-learning/ss-questionanswer.png)

### Access your browser's network monitoring tool

. Open your web browser's developer tools.

> **Note**
>
> The examples in this article use the **Google Chrome** developer tools.
> For browser-specific information, see:
> 
> * [Google Chrome](https://developers.google.com/web/tools/chrome-devtools/open)
> 
> * [Mozilla Firefox](https://developer.mozilla.org/en-US/docs/Tools)
> 
> * [Safari](https://support.apple.com/en-ca/guide/safari/sfri20948/mac)

. Select the **Network** tab.

### Search API response reference

This section provides reference information about the response provided by the [Search API](https://docs.coveo.com/en/13/) for the `questionAnswer` property.

The following snippet displays a Search API response when snippets are found.
As you can see, the response is divided into two sections.
One listing information about the [main snippet](#main-snippet), and another listing information about the [related questions](#related-questions):

```json
{
 "questionAnswer": {
   "answerFound": "boolean",
   "question": "string",
   "answerSnippet": "string",
   "documentId": {
     "contentIdKey": "string",
     "contentIdValue": "string"
   },
   "score": "int32",
   "relatedQuestions": [
     {
       "question": "string",
       "answerSnippet": "string",
       "documentId": {
         "contentIdKey": "string",
         "contentIdValue": "string"
       },
       "score": "int32"
     }
   ]
 }
}
```

#### `answerFound` (boolean)

Whether snippets were found for the query.

> **Note**
>
> This property evaluates to `true` even if only a main snippet, or only related questions, were found for the query.

#### Main snippet

##### `question` (string)

The text representing the header attached to the content of the main snippet.

##### `answerSnippet` (string)

The text corresponding to the main snippet.

##### `documentId` (object)

The [`contentIdKey`](#contentidkey-string) and [`contentIdValue`](#contentidvalue-string) of the item containing the main snippet.

##### `contentIdKey` (string)

The content identifier key.
Typically, `permanentid` or `urihash`.

See [About the permanentid field](https://docs.coveo.com/en/1913/).

##### `contentIdValue` (string)

The content identifier value.

##### `score` (integer [int32])

The relevance score computed for the main snippet based on the query.

#### Related questions

##### `relatedQuestions` (object)

An object representing the information available for each related question listed for the query.

##### `question` (string)

The header attached to the content of the related question.

##### `answerSnippet` (string)

The text corresponding to the answer of the corresponding related question.

##### `documentId` (object)

The [`contentIdKey`](#contentidkey-string-2) and [`contentIdValue`](#contentidvalue-string-2) of the item containing the related question.

##### `contentIdKey` (string)

The content identifier key.
Typically, `permanentid` or `urihash`.

See [About the permanentid field](https://docs.coveo.com/en/1913/).

##### `contentIdValue` (string)

The content identifier value.

##### `score` (integer [int32])

The relevance score computed for the related question based on the query.