$text

Phrases

To match on a phrase, as opposed to individual terms, enclose the phrase in escaped double quotes (\"), as in:

"\"ssl certificate\""

If the $search string of a $text operation includes a phrase and individual terms, text search only matches the documents that include the phrase.

For example, passed a $search string:

"\"ssl certificate\" authority key"

The $text operator searches for the phrase "ssl certificate".

Negations

Prefixing a word with a hyphen-minus (-) negates a word:

• The negated word excludes documents that contain the negated word from the result set.

• When passed a search string that only contains negated words, text search will not match any documents.

• A hyphenated word, such as pre-market, is not a negation. If used in a hyphenated word, $text operator treats the hyphen-minus (-) as a delimiter. To negate the word market in this instance, include a space between pre and -market, i.e., pre -market.

The $text operator adds all negations to the query with the logical AND operator.

Stop Words

The $text operator ignores language-specific stop words, such as the and and in English.

Stemmed Words

For case insensitive and diacritic insensitive text searches, the $text operator matches on the complete stemmed word. So if a document field contains the word blueberry, a search on the term blue will not match. However, blueberry or blueberries will match.

$caseSensitive Option

To support case sensitive search where the text index is case insensitive, specify $caseSensitive: true.

Case Sensitive Search Process

When performing a case sensitive search ($caseSensitive: true) where the text index is case insensitive, the $text operator:

• First searches the text index for case insensitive and diacritic matches.

• Then, to return just the documents that match the case of the search terms, the $text query operation includes an additional stage to filter out the documents that do not match the specified case.

For case sensitive search (i.e. $caseSensitive: true), if the suffix stem contains uppercase letters, the $text operator matches on the exact word.

Specifying $caseSensitive: true may impact performance.

$diacriticSensitive Option

To support diacritic sensitive text search against the text index, specify $diacriticSensitive: true.

Text searches against earlier versions of the text index are inherently diacritic sensitive and cannot be diacritic insensitive. As such, the $diacriticSensitive option for the $text operator has no effect with earlier versions of the text index.

Diacritic Sensitive Search Process

To perform a diacritic sensitive text search ($diacriticSensitive: true) against a version 3 text index, the $text operator:

• First searches the text index, which is diacritic insensitive.

• Then, to return just the documents that match the diacritic marked characters of the search terms, the $text query operation includes an additional stage to filter out the documents that do not match.

Specifying $diacriticSensitive: true may impact performance.

To perform a diacritic sensitive search against an earlier version of the text index, the $text operator searches the text index, which is diacritic sensitive.

For diacritic sensitive search, if the suffix stem contains the diacritic mark or marks, the $text operator matches on the exact word.

Case Sensitive Search for a Term

The following query performs a case sensitive search for the term Coffee:

db.articles.find( { $text: { $search: "Coffee", $caseSensitive: true } } )

The search matches just the document:

{ "_id" : 2, "subject" : "Coffee Shopping", "author" : "efg", "views" : 5 }

Case Sensitive Search for a Phrase

The following query performs a case sensitive search for the phrase Café Con Leche:

db.articles.find( {
   $text: { $search: "\"Café Con Leche\"", $caseSensitive: true }
} )

The search matches just the document:

{ "_id" : 5, "subject" : "Café Con Leche", "author" : "abc", "views" : 200 }

Case Sensitivity with Negated Term

A negated term is a term that is prefixed by a minus sign -. If you negate a term, the $text operator will exclude the documents that contain those terms from the results. You can also specify case sensitivity for negated terms.

The following example performs a case sensitive search for documents that contain the word Coffee but do not contain the lower-case term shop, or more precisely the stemmed version of the words:

db.articles.find( { $text: { $search: "Coffee -shop", $caseSensitive: true } } )

The query matches the following document:

{ "_id" : 2, "subject" : "Coffee Shopping", "author" : "efg" }

Diacritic Sensitive Search for a Term

The following query performs a diacritic sensitive text search on the term CAFÉ, or more precisely the stemmed version of the word:

db.articles.find( { $text: { $search: "CAFÉ", $diacriticSensitive: true } } )

The query only matches the following document:

{ "_id" : 5, "subject" : "Café Con Leche", "author" : "abc" }

Diacritic Sensitivity with Negated Term

The $diacriticSensitive option applies also to negated terms. A negated term is a term that is prefixed by a minus sign -. If you negate a term, the $text operator will exclude the documents that contain those terms from the results.

The following query performs a diacritic sensitive text search for document that contains the term leches but not the term cafés, or more precisely the stemmed version of the words:

db.articles.find(
  { $text: { $search: "leches -cafés", $diacriticSensitive: true } }
)

The query matches the following document:

{ "_id" : 8, "subject" : "Cafe con Leche", "author" : "xyz" }

Return the Text Search Score

The following query performs a text search for the term cake and uses the $meta operator in the projection document to append the relevance score to each matching document:

db.articles.find(
   { $text: { $search: "cake" } },
   { score: { $meta: "textScore" } }
)

The returned document includes an additional field score that contains the document's relevance score:

{ "_id" : 3, "subject" : "Baking a cake", "author" : "abc", "views" : 90, "score" : 0.75 }

Sort by Text Search Score

• Starting in MongoDB 4.4, you can specify the { $meta: "textScore" } expression in the sort() without also specifying the expression in the projection. For example,

  db.articles.find(
     { $text: { $search: "cake" } }
  ).sort( { score: { $meta: "textScore" } } )

  As a result, you can sort the resulting documents by their search relevance without projecting the textScore.

  In earlier versions, to include { $meta: "textScore" } expression in the sort(), you must also include the same expression in the projection.

• Starting in MongoDB 4.4, if you include the { $meta: "textScore" } expression in both the projection and sort(), the projection and sort documents can have different field names for the expression.

  For example, in the following operation, the projection uses a field named score for the expression and the sort() uses the field named ignoredName.

  db.articles.find(
     { $text: { $search: "cake" } } ,
     { score: { $meta: "textScore" } }
  ).sort( { ignoredName: { $meta: "textScore" } } )

  In previous versions of MongoDB, if { $meta: "textScore" } is included in both the projection and sort, you must specify the same field name for the expression.

• In MongoDB 4.2, to sort by the text score, include the same $meta expression in both the projection document and the sort expression. The following query searches for the term coffee and sorts the results by the descending score:

  db.articles.find(
     { $text: { $search: "coffee" } },
     { score: { $meta: "textScore" } }
  ).sort( { score: { $meta: "textScore" } } )

  The query returns the matching documents sorted by descending score.

Return Top 2 Matching Documents

Use the limit() method in conjunction with a sort() to return the top n matching documents.

The following query searches for the term coffee and sorts the results by the descending score, limiting the results to the top two matching documents:

db.articles.find(
   { $text: { $search: "coffee" } },
   { score: { $meta: "textScore" } }
).sort( { score: { $meta: "textScore" } } ).limit(2)

Text Search with Additional Query and Sort Expressions

The following query searches for documents where the author equals "xyz" and the indexed field subject contains the terms coffee or bake. The operation also specifies a sort order of ascending date, then descending text search score:

db.articles.find(
   { author: "xyz", $text: { $search: "coffee bake" } },
   { score: { $meta: "textScore" } }
).sort( { date: 1, score: { $meta: "textScore" } } )