$text (Self-Managed Deployments)

Exact Strings

To match an exact multi-word string instead of individual terms, enclose the string in escaped double quotes (\"): as in:

"\"ssl certificate\""

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

For example, this $search string returns documents with the exact string "ssl certificate":

"\"ssl certificate\" authority key"

Negations

Prefix a word with a hyphen-minus (-) to negate it:

• Negated words exclude documents that contain the negated word from the result set.

• A string with only negated words matches no documents.

• Hyphenated words like pre-market are not negations. MongoDB treats the hyphen as a delimiter. To negate market, use pre -market.

MongoDB applies all negations to the operation with logical AND.

Stop Words

MongoDB ignores language-specific stop words such as the and and in English.

Stemmed Words

With case and diacritic insensitivity, $text matches the complete stemmed word. If a document field contains blueberry, a $search term of blue does not match. However, blueberry or blueberries do match.

Enabling Case Sensitivity

Specify $caseSensitive: true to enable case sensitivity when the text index is case insensitive.

Case Sensitivity Process

When $caseSensitive: true and the text index is case insensitive, $text:

• Queries the text index for case-insensitive and diacritic-insensitive matches.

• Filters results to return only documents matching the specified case.

When $caseSensitive: true and the suffix stem contains uppercase letters, $text matches the exact word.

Enabling $caseSensitive: true may reduce performance.

Enabling Diacritic Sensitivity

Specify $diacriticSensitive: true to enable diacritic sensitivity with version 3 text indexes.

Earlier text index versions are always diacritic sensitive, so $diacriticSensitive has no effect.

Diacritic Sensitivity Process

With version 3 text indexes and $diacriticSensitive: true, $text:

• Queries the diacritic-insensitive text index.

• Filters results to return only documents matching the diacritic marks in the specified terms.

Enabling $diacriticSensitive: true may reduce performance.

With earlier text index versions, $diacriticSensitive: true queries the already diacritic-sensitive text index.

When $diacriticSensitive: true and the suffix stem contains diacritic marks, $text matches the exact word.

Case-Sensitive Term Search

This example performs a case-sensitive query for Coffee:

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

This matches only:

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

Case-Sensitive Exact String Search

This example performs a case-sensitive query for an exact multi-word string:

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

This matches only:

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

Case-Sensitive Negated Term Search

You can use case sensitivity with negated terms (terms prefixed with -).

This example performs a case-sensitive query for documents containing Coffee but not shop (stemmed versions):

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

This matches:

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

Diacritic-Sensitive Term Search

This example performs a diacritic-sensitive query for CAFÉ (stemmed version):

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

This matches only:

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

Diacritic-Sensitive Negated Term Search

You can use diacritic sensitivity with negated terms (terms prefixed with -).

This example performs a diacritic-sensitive query for documents containing leches but not cafés (stemmed versions):

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

This matches:

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

Return the Relevance Score

This example queries for cake and uses $meta to append the relevance score to each matching document:

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

The returned document includes a score field with the relevance score:

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

Sort by Relevance Score

• 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 relevance without projecting the textScore.

• 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" } } )

Return Top 2 Matching Documents

Use limit() with sort() to return the top matching documents.

This example queries for coffee, sorts by descending score, and limits results to the top two documents:

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

Combine $text with Other Query and Sort Operations

This example matches documents where author is "xyz" and subject contains coffee or bake. It sorts by ascending date, then descending relevance score:

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