Highlight Search Terms in Results
On this page
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
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:
|
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.
1 db.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 ])
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.
1 db.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 ])
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.
1 db.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 ])
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.
1 db.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 ])
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.
1 db.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 ])
➤ 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.
1 db.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 ])
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.