Writing $search Queries: Text, Phrase, and Wildcard
Learners will query with text, phrase, and wildcard operators inside the $search aggregation stage and project the search score.
Writing $search Queries: Text, Phrase, and Wildcard is a free MongoDB Academy lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the MongoDB Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
The $search Aggregation Stage
Atlas Search queries are written using the $search aggregation stage—a special pipeline stage that routes the query to the Lucene engine rather than the MongoDB query planner. The $search stage must be the first stage in an aggregation pipeline. Inside it, you specify an operator (like text, phrase, or wildcard) that determines how the query string is matched against indexed documents.
The text Operator: Keyword Search
The text operator is the standard keyword search operator. It tokenizes the query string using the same analyzer used to build the index, then looks for documents containing those tokens. It supports multi-word queries where any word can match (OR semantics by default) and the path field specifies which indexed fields to search in—either a specific field name or all fields via { wildcard: '*' }.
db.articles.aggregate([
{
$search: {
index: 'default',
text: {
query: 'mongodb aggregation pipeline',
path: 'content' // search in the 'content' field only
}
}
},
{
$project: {
title: 1,
author: 1,
score: { $meta: 'searchScore' }
}
},
{ $limit: 10 }
])Searching Multiple Fields
The path field in a text operator can be a single field name, an array of field names, or the wildcard { wildcard: '*' } to search all indexed fields. When searching multiple fields, MongoDB combines results using the best score across fields. Searching fewer, more relevant fields typically produces better precision than searching all fields.
db.products.aggregate([
{
$search: {
text: {
query: 'noise cancelling headphones',
path: ['name', 'description', 'tags'] // search in these three fields
}
}
},
{ $limit: 20 }
])
// Or search all indexed fields:
db.products.aggregate([
{
$search: {
text: {
query: 'wireless bluetooth',
path: { wildcard: '*' }
}
}
}
])The phrase Operator: Exact Phrase Matching
The phrase operator requires the query terms to appear in order and adjacent to each other in the document (like quoting a phrase in a search engine). This is more restrictive than text but much more precise—searching for 'machine learning' as a phrase will not match documents that only contain 'learning' and 'machine' in different sentences. Use slop to allow some words between terms.
db.articles.aggregate([
{
$search: {
phrase: {
query: 'machine learning model',
path: 'content' // all three words must appear in order
}
}
},
{ $project: { title: 1, score: { $meta: 'searchScore' } } }
])
// With slop: allows up to 1 word between the terms
db.articles.aggregate([
{
$search: {
phrase: {
query: 'neural network',
path: 'content',
slop: 1 // allows 'neural deep network' to match
}
}
}
])The wildcard Operator: Pattern Matching
The wildcard operator matches documents where the field value matches a glob-style pattern using * (matches any sequence of characters) and ? (matches any single character). It searches against the indexed token values, so the behavior depends on the analyzer. For keyword-analyzed fields, it matches the entire stored string. Set allowAnalyzedField: true to use wildcard on analyzed fields (use with care—expensive for leading wildcards).
// Match SKUs starting with 'PROD-'
db.products.aggregate([
{
$search: {
wildcard: {
query: 'PROD-*',
path: 'sku', // keyword-analyzed field
allowAnalyzedField: false
}
}
}
])
// Match domains ending in '.org'
db.users.aggregate([
{
$search: {
wildcard: {
query: '*.org',
path: 'email',
allowAnalyzedField: true
}
}
}
])Projecting the Search Score
Atlas Search computes a relevance score for each result document indicating how well it matches the query. Access this score in a $project stage using { $meta: 'searchScore' }. By default, $search returns results in descending score order (most relevant first). Projecting the score also lets you filter on it—for example, discarding low-relevance results below a threshold.
db.articles.aggregate([
{
$search: {
text: { query: 'cloud computing', path: 'body' }
}
},
{
$project: {
title: 1,
author: 1,
publishedAt: 1,
relevanceScore: { $meta: 'searchScore' } // include the score
}
},
// Only show results with score above 0.5
{ $match: { relevanceScore: { $gt: 0.5 } } },
{ $limit: 10 }
])Combining $search With $match for Post-Filtering
You can follow $search with a $match stage to apply additional structured filters—for example, text search for 'headphones' and then filter to products with price under $100. However, use $searchMeta or the filter clause inside $search for pre-filtering on indexed fields, as post-match $match runs after all results are fetched and may be slower than filtering within the search stage.
db.products.aggregate([
{
$search: {
compound: {
must: [
{ text: { query: 'wireless headphones', path: 'name' } }
],
filter: [
// Pre-filter inside $search: much more efficient
{ range: { path: 'price', lte: 100 } },
{ equals: { path: 'inStock', value: true } }
]
}
}
},
{ $project: { name: 1, price: 1, score: { $meta: 'searchScore' } } }
])The range Operator for Numeric and Date Filtering
The range operator allows numeric or date range filtering inside the $search stage. This is more efficient than a post-search $match because Lucene applies the filter before fetching documents. Use gte, gt, lte, and lt bounds. The range operator works on fields indexed with type 'number' or 'date' in the Atlas Search index mapping.
db.jobs.aggregate([
{
$search: {
compound: {
must: [
{ text: { query: 'backend developer', path: 'title' } }
],
filter: [
{
range: {
path: 'postedAt',
gte: new Date('2024-01-01'),
lte: new Date('2024-12-31')
}
},
{
range: {
path: 'salaryMin',
gte: 80000
}
}
]
}
}
}
])The equals Operator for Exact Field Matching
The equals operator performs an exact equality match on a field—similar to MongoDB's standard equality filter but executed inside the Lucene engine. It works on boolean, number, date, objectId, and string fields. Using equals inside $search (rather than a post-search $match) allows Lucene to combine it with the text query efficiently using its bitset and skip-list optimizations.
db.listings.aggregate([
{
$search: {
compound: {
must: [
{ text: { query: 'beachfront villa', path: 'description' } }
],
filter: [
{ equals: { path: 'available', value: true } },
{ equals: { path: 'bedrooms', value: 3 } }
]
}
}
}
])Performance: $search vs Native Text Index
Atlas Search generally outperforms MongoDB's native text indexes for complex queries because Lucene's inverted index is more sophisticated. However, for simple keyword lookups on small collections, the native $text operator may be sufficient. Key advantages of Atlas Search: better relevance scoring, per-field boosting, fuzzy matching, autocomplete, facets, and no one-text-index-per-collection limitation. Choose Atlas Search when you need any of these features.
Index Name Specification
When you have multiple Atlas Search indexes on a collection, specify the index field inside $search to select which index to use. If you omit it, Atlas Search uses the index named 'default'. Using named indexes allows different query types to use different index configurations—for example, a 'standard' index for keyword search and an 'autocomplete' index for type-ahead suggestions.
// Use the 'products_fulltext' search index
db.products.aggregate([
{
$search: {
index: 'products_fulltext', // named index
text: {
query: 'standing desk ergonomic',
path: ['title', 'description']
}
}
}
]);
// Falls back to 'default' if index is not specified:
db.products.aggregate([
{
$search: {
text: { query: 'monitor 4K', path: 'title' }
}
}
]);Quick Check
Test your understanding of MongoDB & NoSQL Databases concepts from this lesson.
Lesson Recap
In this lesson you learned: $search must be the first pipeline stage and takes an operator like text, phrase, or wildcard, the text operator matches any token from the query while phrase requires tokens to appear in order, and use the compound operator with filter clauses to combine text search with structured filters efficiently inside the Lucene engine. Next up we explore autocomplete and fuzzy matching for typo-tolerant search.
Frequently asked questions
Is the “Writing $search Queries: Text, Phrase, and Wildcard” lesson free?
Yes — the full text of “Writing $search Queries: Text, Phrase, and Wildcard” is free to read here on the web, and the MongoDB Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the MongoDB Academy course, upgrade to CoddyKit PRO.
What will I learn in “Writing $search Queries: Text, Phrase, and Wildcard”?
Learners will query with text, phrase, and wildcard operators inside the $search aggregation stage and project the search score. You practise MongoDB Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start MongoDB Academy?
No prior experience is required. MongoDB Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Writing $search Queries: Text, Phrase, and Wildcard” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this MongoDB Academy lesson?
Yes. Every MongoDB Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Creating an Atlas Search Index
- Writing $search Queries: Text, Phrase, and Wildcard
- Autocomplete and Fuzzy Matching
- Facets and Compound Queries