Docs Menu
Docs Home
/
MongoDB Atlas
/
Atlas Search
/
Create and Run Queries
/
Create a Query
/
5. Define Additional Search Options

Highlight Search Terms in Results

On this page

  • Syntax
  • Options
  • Output
  • Prerequisites
  • Limitations
  • Examples
  • Sample collection
  • Sample Index
  • Sample Queries

The Atlas Search highlight option adds fields to the result set that display search terms in their original context. You can use it in conjunction with all $search operators to display search terms as they appear in the returned documents, along with the adjacent text content (if any). highlight results are returned as part of the $meta field.

Syntax

highlight has the following syntax:

{
  $search: {
    "index": "<index name>", // optional, defaults to "default"
    "<operator>": { // such as "text", "compound", or "phrase"
      <operator-specification>
    },
    "highlight": {
      "path": "<field-to-search>",
      "maxCharsToExamine": "<number-of-chars-to-examine>", // optional, defaults to 500,000
      "maxNumPassages": "<number-of-passages>" // optional, defaults to 5
    }
  }
},
{
  $project: {
    "highlights": { "$meta": "searchHighlights" }
  }
}

Options

Field
Type
Description
Required?

path

string

Document field to search. The path field may contain:

  • A string

  • An array of strings

  • A multi analyzer specification

  • An array containing a combination of strings and multi analyzer specifications

  • A wildcard character *

See Construct a Query Path for more information.

yes

maxCharsToExamine

int

Maximum number of characters to examine on a document when performing highlighting for a field. If omitted, defaults to 500,000, which means that Atlas Search only examines the first 500,000 characters in the search field in each document for highlighting.

no

maxNumPassages

int

Number of high-scoring passages to return per document in the highlights results for each field. A passage is roughly the length of a sentence. If omitted, defaults to 5, which means that for each document, Atlas Search returns the top 5 highest-scoring passages that match the search text.

no

The "$meta": "searchHighlights" field contains the highlighted results. That field isn't part of the original document, so it is necessary to use a $project pipeline stage to add it to the query output.

Output

The highlights field is an array containing the following output fields:

Field
Type
Description

path

string

Document field which returned a match.

texts

array of documents

Each search match returns one or more objects, containing the matching text and the surrounding text (if any).

texts.value

string

Text from the field which returned a match.

texts.type

string

Type of result. Value can be one of the following:

  • hit - The results contain the term that matched the query.

  • text - The results contain the text content adjacent to the matching term.

score

float

Score assigned to the matching result. The highlights score is a measure of the relevance of the highlights object to the query. If multiple highlights objects are returned, the most relevant highlights object has the highest score.

Prerequisites

You must index the field that you want to highlight as an Atlas Search string type with indexOptions set to offsets (default).

Limitations

You can't use the Atlas Search highlight option in conjunction with the embeddedDocument operator.

Examples

You can try the following examples in the Atlas Search Playground or your Atlas cluster.

Sample collection

The examples on this page use a collection called fruit that contains the following documents:

{
  "_id" : 1,
  "type" : "fruit",
  "summary" : "Apple varieties",
  "description" : "Apples come in several varieties, including Fuji, Granny Smith, and Honeycrisp. The most popular varieties are McIntosh, Gala, and Granny Smith.",
  "category": "organic"
},
{
  "_id" : 2,
  "type" : "fruit",
  "summary" : "Banana",
  "description" : "Bananas are usually sold in bunches of five or six.",
  "category": "nonorganic"
},
{
  "_id" : 3,
  "type" : "fruit",
  "summary" : "Pear varieties",
  "description" : "Bosc and Bartlett are the most common varieties of pears.",
  "category": "nonorganic"
}

Sample Index

The fruit collection also has an index definition that uses the english analyzer and dynamic field mappings.

{
  "analyzer": "lucene.english",
  "searchAnalyzer": "lucene.english",
  "mappings": {
    "dynamic": true
  }
}

Note

One useful aspect of highlighting is that it reveals the original text returned by the search query, which may not be exactly the same as the search term. For example, if you use a language-specific analyzer, your text searches return all the stemmed variations of your search terms.

Another useful aspect of highlighting is that it can be used to highlight any field, inside or outside of the query path. For example, when you search for a term, you can perform highlighting for the query term on the query field and any other fields that you specify using the highlight option. To learn more, see Multi-Field Example.

Sample Queries

The following queries demonstrate the $search highlight option in Atlas Search queries.

Basic Example

The following query searches for variety and bunch in the description field of the fruit collection, with the highlight option enabled.

The $project pipeline stage restricts the output to the description field and adds a new field called highlights, which contains highlighting information.

1db.fruit.aggregate([
2  {
3    $search: {
4      "text": {
5        "path": "description",
6        "query": ["variety", "bunch"]
7      },
8      "highlight": {
9        "path": "description"
10      }
11    }
12  },
13  {
14    $project: {
15      "description": 1,
16      "_id": 0,
17      "highlights": { "$meta": "searchHighlights" }
18    }
19  }
20])
1{
2  "description" : "Bananas are usually sold in bunches of five or six. ",
3  "highlights" : [
4    {
5      "path" : "description",
6      "texts" : [
7        {
8          "value" : "Bananas are usually sold in ",
9          "type" : "text"
10        },
11        {
12          "value" : "bunches",
13          "type" : "hit"
14        },
15        {
16          "value" : " of five or six. ",
17          "type" : "text"
18        }
19      ],
20      "score" : 1.2841906547546387
21    }
22  ]
23}
24{
25  "description" : "Bosc and Bartlett are the most common varieties of pears.",
26  "highlights" : [
27    {
28      "path" : "description",
29      "texts" : [
30        {
31          "value" : "Bosc and Bartlett are the most common ",
32          "type" : "text"
33        },
34        {
35          "value" : "varieties",
36          "type" : "hit"
37        },
38        {
39          "value" : " of pears.",
40          "type" : "text"
41        }
42      ],
43      "score" : 1.2691514492034912
44    }
45  ]
46}
47{
48  "description" : "Apples come in several varieties, including Fuji, Granny Smith, and Honeycrisp. The most popular varieties are McIntosh, Gala, and Granny Smith. ",
49  "highlights" : [
50    {
51      "path" : "description",
52      "texts" : [
53        {
54          "value" : "Apples come in several ",
55          "type" : "text"
56        },
57        {
58          "value" : "varieties",
59          "type" : "hit"
60        },
61        {
62          "value" : ", including Fuji, Granny Smith, and Honeycrisp. ",
63          "type" : "text"
64        }
65      ],
66      "score" : 1.0330637693405151
67    },
68    {
69      "path" : "description",
70      "texts" : [
71        {
72          "value" : "The most popular ",
73          "type" : "text"
74        },
75        {
76          "value" : "varieties",
77          "type" : "hit"
78        },
79        {
80          "value" : " are McIntosh, Gala, and Granny Smith. ",
81          "type" : "text"
82        }
83      ],
84      "score" : 1.0940992832183838
85    }
86  ]
87}

The search term bunch returns a match on the document with _id: 2, because the description field contains the word bunches. The search term variety returns a match on the documents with _id: 3 and _id: 1, because the description field contains the word varieties.

➤ Try this in the Atlas Search Playground.

Advanced Example

The following query searches for variety and bunch in the description field of the fruit collection, with the highlight option enabled, maximum number of characters to examine set to 40, and only 1 high-scoring passage to return per document.

The $project pipeline stage restricts the output to the description field and adds a new field called highlights, which contains highlighting information.

1db.fruit.aggregate([
2  {
3    $search: {
4      "text": {
5        "path": "description",
6        "query": ["variety", "bunch"]
7      },
8      "highlight": {
9        "path": "description",
10        "maxNumPassages": 1,
11        "maxCharsToExamine": 40
12      }
13    }
14  },
15  {
16    $project: {
17      "description": 1,
18      "_id": 0,
19      "highlights": { "$meta": "searchHighlights" }
20    }
21  }
22])
1{
2  "description" : "Bananas are usually sold in bunches of five or six. ",
3  "highlights" : [
4    {
5      "path" : "description",
6      "texts" : [
7        {
8          "value" : "Bananas are usually sold in ",
9          "type" : "text"
10        },
11        {
12          "value" : "bunches",
13          "type" : "hit"
14        },
15        {
16          "value" : " of f",
17          "type" : "text"
18        }
19      ],
20      "score" : 1.313065767288208
21    }
22  ]
23}
24{
25  "description" : "Bosc and Bartlett are the most common varieties of pears.",
26  "highlights" : [ ]
27}
28{
29  "description" : "Apples come in several varieties, including Fuji, Granny Smith, and Honeycrisp. The most popular varieties are McIntosh, Gala, and Granny Smith.",
30  "highlights" : [
31    {
32      "path" : "description",
33      "texts" : [
34        {
35          "value" : "Apples come in several ",
36          "type" : "text"
37        },
38        {
39          "value" : "varieties",
40          "type" : "hit"
41        },
42        {
43          "value" : ", includ",
44          "type" : "text"
45        }
46      ],
47      "score" : 0.9093900918960571
48    }
49  ]
50}

The second document in the above results contains an empty highlights array even though the search field contains the search term varieties, because Atlas Search only examined 40 characters for highlighting. Similarly, the word includ is truncated because Atlas Search only examined 40 characters in the search field for highlighting. In the third document, although multiple passages contain the search term, Atlas Search returns only one passage in the highlights results because the query required only 1 passage per document in the highlights results.

➤ Try this in the Atlas Search Playground.

Multi-Field Example

The following query searches for varieties in the description field of the fruit collection, with the highlight option enabled for both the description and summary fields.

The $project pipeline stage adds a new field called highlights, which contains highlighting information for the query term across all fields in the highlight option.

1db.fruit.aggregate([
2  {
3    $search: {
4      "text": {
5        "path": "description",
6        "query": "varieties"
7      },
8      "highlight": {
9        "path": ["description", "summary" ]
10      }
11    }
12  },
13  {
14    $project: {
15      "description": 1,
16      "summary": 1,
17      "_id": 0,
18      "highlights": { "$meta": "searchHighlights" }
19    }
20  }
21])
1{
2  "summary" : "Pear varieties",
3  "description" : "Bosc and Bartlett are the most common varieties of pears.",
4  "highlights" : [
5    {
6      "path" : "summary",
7      "texts" : [
8        {
9          "value" : "Pear ",
10          "type" : "text"
11        },
12        {
13          "value" : "varieties",
14          "type" : "hit"
15        }
16      ],
17      "score" : 1.3891443014144897 },
18    {
19      "path" : "description",
20      "texts" : [
21        {
22          "value" : "Bosc and Bartlett are the most common ",
23          "type" : "text"
24        },
25        {
26          "value" : "varieties",
27          "type" : "hit"
28        },
29        {
30          "value" : " of pears.",
31          "type" : "text"
32        }
33      ],
34      "score" : 1.2691514492034912
35    }
36  ]
37}
38{
39  "summary" : "Apple varieties",
40  "description" : "Apples come in several varieties, including Fuji, Granny Smith, and Honeycrisp. The most popular varieties are McIntosh, Gala, and Granny Smith.",
41  "highlights" : [
42    {
43      "path" : "summary",
44      "texts" : [
45        {
46          "value" : "Apple ",
47          "type" : "text"
48        },
49        {
50          "value" : "varieties",
51          "type" : "hit"
52        }
53      ],
54      "score" : 1.3859853744506836
55    },
56    {
57      "path" : "description",
58      "texts" : [
59        {
60          "value" : "Apples come in several ",
61          "type" : "text"
62        },
63        {
64          "value" : "varieties",
65          "type" : "hit"
66        },
67        {
68          "value" : ", including Fuji, Granny Smith, and Honeycrisp. ",
69          "type" : "text"
70        }
71      ],
72      "score" : 1.0330637693405151
73    },
74    {
75      "path" : "description",
76      "texts" : [
77        {
78          "value" : "The most popular ",
79          "type" : "text"
80        },
81        {
82          "value" : "varieties",
83          "type" : "hit"
84        },
85        {
86          "value" : " are McIntosh, Gala, and Granny Smith.",
87          "type" : "text"
88        }
89      ],
90      "score" : 1.0940992832183838
91    }
92  ]
93}

The search term varieties returns a match on documents with _id: 1 and _id: 3 because the query field description in both documents contains the query term varieties. In addition, the highlights array includes the summary field because the field contains the query term varieties.

➤ Try this in the Atlas Search Playground.

Wildcard Example

The following query searches for the term varieties in fields that begin with des in the fruit collection, with the highlight option enabled for fields that begin with des.

The $project pipeline stage adds a new field called highlights, which contains highlighting information.

1db.fruit.aggregate([
2  {
3    "$search": {
4      "text": {
5        "path": {"wildcard": "des*"},
6        "query": ["variety"]
7      },
8      "highlight": {
9        "path": {"wildcard": "des*"}
10      }
11    }
12  },
13  {
14    "$project": {
15      "description": 1,
16      "_id": 0,
17      "highlights": { "$meta": "searchHighlights" }
18    }
19  }
20])
1{
2  "description" : "Bosc and Bartlett are the most common varieties of pears.",
3  "highlights" : [
4    {
5      "path" : "description",
6      "texts" : [
7        {
8          "value" : "Bosc and Bartlett are the most common ",
9          "type" : "text"
10        },
11        {
12          "value" : "varieties",
13          "type" : "hit"
14        },
15        {
16          "value" : " of pears.",
17          "type" : "text"
18        }
19      ],
20      "score" : 1.2691514492034912
21    }
22  ]
23},
24{
25  "description" : "Apples come in several varieties, including Fuji, Granny Smith, and Honeycrisp. The most popular varieties are McIntosh, Gala, and Granny Smith.",
26  "highlights" : [
27    {
28      "path" : "description",
29      "texts" : [
30        {
31          "value" : "Apples come in several ",
32          "type" : "text"
33        },
34        {
35          "value" : "varieties",
36          "type" : "hit"
37        },
38        {
39          "value" : ", including Fuji, Granny Smith, and Honeycrisp. ",
40          "type" : "text"
41        }
42      ],
43      "score" : 1.0330637693405151
44    },
45    {
46      "path" : "description",
47      "texts" : [
48        {
49          "value" : "The most popular ",
50          "type" : "text"
51        },
52        {
53          "value" : "varieties",
54          "type" : "hit"
55        },
56        {
57          "value" : " are McIntosh, Gala, and Granny Smith.",
58          "type" : "text"
59        }
60      ],
61      "score" : 1.0940992832183838
62    }
63  ]
64}

In the Atlas Search results, the fields that begin with des are highlighted.

➤ Try this in the Atlas Search Playground.

Compound Example

The following query searches for the term organic in the category field and variety in the description field. The highlight option in the $search compound query requests highlighting information only for the text query against the description field. Note that the highlight option inside the $search stage must be a child of the $search stage, and not of any operator inside the $search stage.

The $project pipeline stage adds a new field called highlights, which contains highlighting information.

1db.fruit.aggregate([
2  {
3    "$search": {
4      "compound": {
5        "should": [{
6          "text": {
7            "path": "category",
8            "query": "organic"
9          }
10        },
11        {
12          "text": {
13            "path": "description",
14            "query": "variety"
15          }
16        }]
17      },
18      "highlight": {
19        "path": "description"
20      }
21    }
22  },
23  {
24    "$project": {
25      "description": 1,
26      "category": 1,
27      "_id": 0,
28      "highlights": { "$meta": "searchHighlights" }
29    }
30  }
31])
1[
2  {
3    description: 'Apples come in several varieties, including Fuji, Granny Smith, and Honeycrisp. The most popular varieties are McIntosh, Gala, and Granny Smith.',
4    category: 'organic',
5    highlights: [
6      {
7        score: 1.0330637693405151,
8        path: 'description',
9        texts: [
10          { value: 'Apples come in several ', type: 'text' },
11          { value: 'varieties', type: 'hit' },
12          {
13            value: ', including Fuji, Granny Smith, and Honeycrisp. ',
14            type: 'text'
15          }
16        ]
17      },
18      {
19        score: 1.0940992832183838,
20        path: 'description',
21        texts: [
22          { value: 'The most popular ', type: 'text' },
23          { value: 'varieties', type: 'hit' },
24          {
25            value: ' are McIntosh, Gala, and Granny Smith.',
26            type: 'text'
27          }
28        ]
29      }
30    ]
31  },
32  {
33    description: 'Bosc and Bartlett are the most common varieties of pears.',
34    category: 'nonorganic',
35    highlights: [
36      {
37        score: 1.2691514492034912,
38        path: 'description',
39        texts: [
40          {
41            value: 'Bosc and Bartlett are the most common ',
42            type: 'text'
43          },
44          { value: 'varieties', type: 'hit' },
45          { value: ' of pears.', type: 'text' }
46        ]
47      }
48    ]
49  }
50]

➤ Try this in the Atlas Search Playground.

Autocomplete Example

For this example, the fruit collection also has the following index definition.

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "description": [
       {
        "type": "autocomplete",
        "tokenization": "edgeGram",
        "minGrams": 2,
        "maxGrams": 15,
        "foldDiacritics": true
       }
      ]
    }
  }
}

The following query searches for the characters var in the description field of the fruit collection, with the highlight option enabled for the description field.

The $project pipeline stage adds a new field called highlights, which contains highlighting information.

Important

To highlight the autocomplete indexed version of a path, the autocomplete operator must be the only operator that uses that path in the query.

1db.fruit.aggregate([
2  {
3    "$search": {
4      "autocomplete": {
5        "path": "description",
6        "query": ["var"]
7      },
8      "highlight": {
9        "path": "description"
10      }
11    }
12  },
13  {
14    "$project": {
15      "description": 1,
16      "_id": 0,
17      "highlights": { "$meta": "searchHighlights" }
18    }
19  }
20])
1{
2  "description": "Apples come in several varieties, including Fuji, Granny Smith, and Honeycrisp. The most popular varieties are McIntosh, Gala, and Granny Smith.",
3  "highlights": [
4    {
5      "score": 0.774385392665863,
6      "path": "description",
7      "texts": [
8        { "value": "Apples come in several ", "type": "text" },
9        { "value": "varieties, including Fuji", "type": "hit" },
10        { "value": ", Granny Smith, and Honeycrisp. ", "type": "text" }
11      ]
12    },
13    {
14      "score": 0.7879307270050049,
15      "path": "description",
16      "texts": [
17        { "value": "The most popular ", "type": "text" },
18        { "value": "varieties are McIntosh", "type": "hit" },
19        { "value": ", Gala, and Granny Smith.", "type": "text" }
20      ]
21    }
22  ]
23},
24{
25  "description": "Bosc and Bartlett are the most common varieties of pears.",
26  "highlights": [
27    {
28      "score": 0.9964432120323181,
29      "path": "description",
30      "texts": [
31        {
32          "value": "Bosc and Bartlett are the most common ",
33          "type": "text"
34        },
35        { "value": "varieties of pears", "type": "hit" },
36        { "value": ".", "type": "text" }
37      ]
38    }
39  ]
40}

Atlas Search returns a match on the documents with _id: 1 and id_: 2 for the query string var because the description field in the fruit collection contains the characters var at the beginning of a word. Atlas Search matches a highlight hit more coarsely to your query terms when a highlighted path is referenced only in the autocomplete operators of the highlighted query.

➤ Try this in the Atlas Search Playground.