Docs4dev
Docs
mongodb / v3.6 / reference / reference-operator-query-text.html

$text

On this page

Definition

$text

$text performs a text search on the content of the fields indexed with a text index. A $text expression has the following syntax:

Changed in version 3.2.

{
  $text:
    {
      $search: <string>,
      $language: <string>,
      $caseSensitive: <boolean>,
      $diacriticSensitive: <boolean>
    }
}

The $text operator accepts a text query document with the following fields:

Field Type Description
$search string A string of terms that MongoDB parses and uses to query the text index. MongoDB performs a logical OR search of the terms unless specified as a phrase. See Behavior for more information on the field.
$language string

Optional. The language that determines the list of stop words for the search and the rules for the stemmer and tokenizer. If not specified, the search uses the default language of the index. For supported languages, see Text Search Languages.

If you specify a language value of "none", then the text search uses simple tokenization with no list of stop words and no stemming.
$caseSensitive boolean

Optional. A boolean flag to enable or disable case sensitive search. Defaults to false; i.e. the search defers to the case insensitivity of the text index.

For more information, see Case Insensitivity.

New in version 3.2.
$diacriticSensitive boolean

Optional. A boolean flag to enable or disable diacritic sensitive search against version 3 text indexes. Defaults to false; i.e. the search defers to the diacritic insensitivity of the text index.

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

For more information, see Diacritic Insensitivity.

New in version 3.2.

The $text operator, by default, does not return results sorted in terms of the results’ scores. For more information on sorting by the text search scores, see the Text Score documentation.

Behavior

Restrictions

  • A query can specify, at most, one $text expression.
  • The $text query can not appear in $nor expressions.
  • The $text query can not appear in $elemMatch query expressions or $elemMatch projection expressions.
  • To use a $text query in an $or expression, all clauses in the $or array must be indexed.
  • You cannot use hint() if the query includes a $text query expression.
  • You cannot specify $natural sort order if the query includes a $text expression.
  • You cannot combine the $text expression, which requires a special text index, with a query operator that requires a different type of special index. For example you cannot combine $text expression with the $near operator.
  • Views do not support text search.

If using the $text operator in aggregation, the following restrictions also apply.

  • The $match stage that includes a $text must be the first stage in the pipeline.
  • A text operator can only occur once in the stage.
  • The text operator expression cannot appear in $or or $not expressions.
  • The text search, by default, does not return the matching documents in order of matching scores. Use the $meta aggregation expression in the $sort stage.

$search Field

In the $search field, specify a string of words that the text operator parses and uses to query the text index.

The text operator treats most punctuation in the string as delimiters, except a hyphen-minus (-) that negates term or an escaped double quotes \" that specifies a phrase.

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 includes a phrase and individual terms, text search will only match 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.

Match Operation

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.

Case Sensitive Search and Stemmed Words

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

Diacritic Sensitive Search and Stemmed Words

For diacritic sensitive search (i.e. $diacriticSensitive: true), if the suffix stem contains the diacritic mark or marks, the $text operator matches on the exact word.

Case Insensitivity

Changed in version 3.2.

The $text operator defaults to the case insensitivity of the text index:

  • The version 3 text index is case insensitive for Latin characters with or without diacritics and characters from non-Latin alphabets, such as the Cyrillic alphabet. See text index for details.
  • Earlier versions of the text index are case insensitive for Latin characters without diacritic marks; i.e. for [A-z].

$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.

See also

Stemmed Words

Diacritic Insensitivity

Changed in version 3.2.

The $text operator defaults to the diacritic insensitivity of the text index:

  • The version 3 text index is diacritic insensitive. That is, the index does not distinguish between characters that contain diacritical marks and their non-marked counterpart, such as é, ê, and e.
  • Earlier versions of the text index are diacritic sensitive.

$diacriticSensitive Option

To support diacritic sensitive text search against the version 3 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 imp