Running $text Queries With Phrases and Negation

Once a text index exists, you run keyword searches with the $text operator inside a find() filter. The value is an object with a $search string containing the words or phrases you are looking for. MongoDB tokenises your search string the same way it tokenised the indexed fields, then returns documents where at least one indexed field contains a matching token.

By default, a $text search with multiple words uses OR semantics: a document matches if it contains any of the words. So 'mongodb index' returns documents containing 'mongodb' or 'index' or both. The relevance score (textScore) is higher for documents that contain more of the search terms, but all matching documents are returned regardless.

To require an exact phrase, wrap it in escaped double quotes inside the $search string. A phrase search requires the words to appear together and in that order. Documents that only contain some of the phrase words but not the exact sequence will not match. Phrase searches are more precise but can miss relevant documents with slightly different wording.

Prefix a word with a minus sign (-) to exclude documents that contain that word. You cannot use negation alone—you must pair it with at least one positive search term. Negation is useful when a keyword is too broad and you want to filter out a specific unwanted meaning, like 'java -coffee' to find programming articles about Java, not the beverage.

You can freely mix phrases, keywords, and negation in a single $search string. MongoDB processes each term independently: quoted groups are phrase searches, minus-prefixed words are exclusions, and remaining bare words are optional keyword matches. This composability lets you express moderately complex search logic without a dedicated search engine.

$text searches are case-insensitive by default. MongoDB lowercases all tokens during indexing and during the search, so 'MongoDB', 'MONGODB', and 'mongodb' all match the same indexed tokens. You do not need to normalise search input before running a $text query.

By default, $text uses the language configured on the text index. You can override this per query with the $language option. This is useful for multilingual content collections where documents stored in different languages should be searched with the appropriate stop word list and stemming algorithm.

While case-insensitive search is the default, you can enable case-sensitive text search with $caseSensitive: true. This is rarely needed but useful when your content has case-significant identifiers like class names or command names. Note: case-sensitive text search is significantly slower because it cannot use the pre-lowercased index entries.

By default, MongoDB text search is diacritic-insensitive: 'café' and 'cafe' are treated as the same word. You can enable $diacriticSensitive: true to distinguish accented characters. This matters for languages like French, German, or Spanish where diacritics change meaning. Like case sensitivity, diacritic-sensitive search is slower because it bypasses pre-normalised index entries.

You can use $text in aggregation pipelines by placing a $match stage with the text filter as the very first stage. This lets MongoDB push the text search to the index before applying subsequent pipeline stages. You can then project the textScore, group results by category, or limit the number of matches—all server-side.

To count how many documents match a text query, use countDocuments() with the $text filter or add a $count stage at the end of an aggregation pipeline. Avoid using count() (deprecated) and be aware that estimatedDocumentCount() cannot take a filter—always use countDocuments() for filtered counts.

Test your understanding of $text query options from this lesson.

In this lesson you learned: bare words use OR semantics and match any of the search terms, double-quoted phrases require an exact word sequence, and minus-prefixed words exclude documents containing that term. Next up we sort results by text relevance score using $meta.