MongoDB $text Operator

What You’ll Learn

The $text operator performs full-text search on string fields covered by a text index. Use it in find() queries and $match stages to search articles, products, comments, and other text-heavy data.

Definition and Usage

In MongoDB, the $text operator is a query operator that searches for words and phrases in text-indexed fields. Unlike math operators such as $abs or $tanh, $text does not transform field values — it filters documents that match your search terms.

Before you can search, create a text index on the fields you want to query. Then pass your search string to $search. MongoDB tokenizes the text, applies language-specific rules (stemming, stop words), and returns matching documents.

📝 Syntax

First create a text index, then use $text in your query filter:

Step 1 — Create a Text Index

db.articles.createIndex({
  title: "text",
  body: "text"
})

Step 2 — Query with $text

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

Minimal Example

db.articles.find({
  $text: { $search: "mongodb tutorial" }
})

// In an aggregation pipeline:
db.articles.aggregate([
  {
    $match: {
      $text: { $search: "mongodb tutorial" }
    }
  }
])

$search Modifiers

// Multiple terms (OR by default)
{ $search: "mongodb database" }

// Exact phrase (use quotes)
{ $search: "\"aggregation pipeline\"" }

// Exclude a term (prefix with minus)
{ $search: "mongodb -sql" }

// Require all terms (prefix with plus)
{ $search: "+mongodb +tutorial" }

Syntax Rules

• $search — required; the search string (terms, phrases, exclusions).
• $language — optional; language for stemming (default: "english").
• $caseSensitive — optional; case-sensitive matching (default: false).
• $diacriticSensitive — optional; accent-sensitive matching (default: false).
• Text index required — one text index per collection (can cover multiple fields).
• One $text per query — you cannot use two $text operators in the same query.

Examples Gallery

Set up a text index on an articles collection, run searches with find() and aggregation, and rank results by relevance.

db.articles.createIndex({
  title: "text",
  body: "text"
})

// Verify the index
db.articles.getIndexes()

[
  {
    "_id": 1,
    "title": "MongoDB Aggregation Tutorial",
    "body": "Learn pipelines, $match, and $project stages."
  },
  {
    "_id": 2,
    "title": "Introduction to Databases",
    "body": "A beginner guide covering SQL and NoSQL options."
  },
  {
    "_id": 3,
    "title": "Advanced MongoDB Tips",
    "body": "Indexing, aggregation, and performance tuning for MongoDB."
  },
  {
    "_id": 4,
    "title": "SQL vs NoSQL",
    "body": "Compare relational and document database models."
  }
]

db.articles.find({
  $text: { $search: "mongodb" }
})

// Matches documents 1 and 3 (title or body contains "mongodb")
{ "_id": 1, "title": "MongoDB Aggregation Tutorial", ... }
{ "_id": 3, "title": "Advanced MongoDB Tips", ... }

db.articles.aggregate([
  {
    $match: {
      $text: { $search: "mongodb aggregation" }
    }
  },
  {
    $project: {
      title: 1,
      body: 1,
      score: { $meta: "textScore" }
    }
  },
  {
    $sort: { score: -1 }
  }
])

// Document 1 ranks highest (title + body both match)
{ "_id": 1, "title": "MongoDB Aggregation Tutorial", "score": 2.5, ... }
{ "_id": 3, "title": "Advanced MongoDB Tips", "score": 1.2, ... }

db.articles.find({
  $text: { $search: "\"aggregation pipeline\"" }
})

// Matches documents where "aggregation" and "pipeline"
// appear together as a phrase

db.articles.find({
  $text: { $search: "mongodb -sql" }
})

// Returns MongoDB matches that do NOT contain "sql"

db.articles.find({
  $text: { $search: "database" },
  category: "tutorial",
  published: true
})

// Text search + exact match on category and published

db.articles.createIndex(
  {
    title: "text",
    body: "text"
  },
  {
    weights: {
      title: 10,
      body: 1
    },
    name: "article_text_index"
  }
)

🚀 Use Cases

• Site search — search blog posts, documentation, or product descriptions by keyword.
• Knowledge bases — find help articles and FAQs across title and body fields.
• E-commerce catalogs — search product names and descriptions with relevance ranking.
• Support tickets — locate customer messages containing specific terms or phrases.
• Content moderation — filter documents containing flagged words (combined with other query filters).

💡 Best Practices