Dynamic Term-Based Boosting in MongoDB Atlas Search
Search relevance is the bedrock of any modern user experience. While
MongoDB Atlas Search
offers a fantastic out-of-the-box relevance model with BM25, its standard approach treats all search terms with a uniform level of importance. For applications that demand precision, this isn't enough.
What if you need to boost content from an expert author? Or prioritize a trending topic for the next 48 hours? Or ensure a specific promotional product always appears at the top? Relying on query-time boosting alone can lead to complex, brittle queries that are a nightmare to maintain.
There's a more elegant solution. Enter the embedded scoring pattern—an advanced technique in Atlas Search that allows you to embed term-level boosting logic directly within your documents. It's a powerful way to make your relevance scoring data-driven, adaptable, and incredibly precise without ever changing your query structure.
Why you need embedded scoring: From uniform to granular
The standard approach to boosting is like using a single volume knob for an entire orchestra. The embedded scoring pattern, on the other hand, gives you a mixing board with a dedicated slider for every single instrument.
This enables application owners to seamlessly build business-focused use cases, such as:
Prioritizing authority:
Elevate content from verified experts or high-authority authors.
Boosting trends:
Dynamically increase the rank of time-sensitive or trending topics.
Elevating promotions:
Ensure seasonal or promotional products get the visibility they need.
By encoding scoring logic alongside your content, you solve the "one-size-fits-all" limitation and give yourself unparalleled control.
Under the hood: Building the embedded scoring pattern
Let's get practical. Implementing this pattern involves two key steps: designing the index and structuring your documents.
1. The index design: Defining your boosts
First, you need to tell Atlas Search how to understand your custom boosts. You do this by defining a field with the
embeddedDocuments
type in your search index. This creates a dedicated space for your term-boost pairs.
{
"mappings": {
"dynamic": true,
"fields": {
"indexed_terms": {
"type": "embeddedDocuments",
"dynamic": false,
"fields": {
"term": { "type": "string" },
"boost": { "type": "number" }
}
}
}
}
}
This index definition creates a special array,
indexed_terms
, ready to hold our custom scoring rules.
2. The document structure: Encoding relevance
With the index in place, you can now add the
indexed_terms
array to your documents. Each object in this array contains a term and a corresponding boost value.
Consider this sample document:
{
"id": "content_12345",
"title": "Advanced Machine Learning Techniques for Natural Language Processing",
"description": "Comprehensive guide covering transformer models and neural networks",
"tags": ["technology", "AI", "tutorial"],
"author": "Dr. Sarah Chen",
"indexed_terms": [
{ "term": "machine learning", "boost": 25.0 }, // High boost for the primary topic
{ "term": "dr. sarah chen", "boost": 20.0 }, // High boost for an expert author
{ "term": "tutorial", "boost": 8.0 } // Lower boost for the content format
]
}
As you can see, we've assigned a high score to the core topic ("machine learning") and the expert author, ensuring this document ranks highly for those queries.
The query: Putting embedded scores into action
Now for the magic. The query below uses the
compound
operator to combine our new embedded scoring with traditional field-based search.
[
{
"$search": {
"index": "default",
"compound": {
"should": [
{
// Clause 1: Use our embedded scores
"embeddedDocument": {
"path": "indexed_terms",
"operator": {
"text": {
"path": "indexed_terms.term",
"query": "machine learning",
"score": {
// Use the boost value from the document!
"function": {
"path": {
"value": "indexed_terms.boost",
"undefined": 0.0
}
}
}
}
}
}
},
{
// Clause 2: Standard search across other fields
"text": {
"path": ["title", "description"],
"query": "machine learning",
// Add a small constant score for matches in these fields
"score": { "constant": { "value": 5 } }
}
}
]
},
"scoreDetails": true
}
},
{
"$project": {
"_id": 0,
"id": 1,
"title": 1,
"author": 1,
"relevanceScore": { "$meta": "searchScore" },
"scoreDetails": { "$meta": "searchScoreDetails" }
}
}
]
In this query, a user searches for "machine learning". If our sample document is part of the index, the final score is a combination of our boosts:
25 points
from the
indexed_terms
match.
5 points
from the match in the title field.
Total Score:
30
This gives us precise, predictable, and highly tunable ranking behavior.
Aggregation strategies
You can even control how multiple matches within the
indexed_terms
array contribute to the score. The three main strategies are:
table,
th,
td {
border: 1px solid black;
border-collapse: collapse;
}
th,
td {
padding: 5px;
}
Strategy
Use Case
maximum
Highlights the single most relevant term that matched.
sum
Accumulates the score across all matching terms.
mean
Normalizes the score by averaging the boost of all matching terms.
Power comes with responsibility: Performance considerations
While powerful, this pattern requires foresight and planning. Embedding terms increases your index size. If 1 million documents each get five embedded terms, your index now has to manage 6 million entries.
To keep things snappy and scalable, follow these best practices:
Be selective:
Only embed high-impact terms. Don't use it for your entire vocabulary.
Quantize boosts:
Use discrete boost levels (e.g., 5, 10, 15, 20) instead of hyper-specific decimals. This improves caching and consistency.
Perform regular cleanup:
Create processes to remove obsolete or low-performing terms from the indexed_terms arrays.
Always monitor your index size, query latency, and memory usage in the Atlas UI to ensure your implementation remains performant.
Take control of your search destiny
The embedded scoring pattern in MongoDB Atlas Search is a game-changer for anyone serious about search relevance. It moves beyond static, one-size-fits-all ranking and gives you dynamic, context-aware control directly within your data.
You can use this pattern to implement business-driven ranking logic, enable real-time personalization, and achieve full transparency for tuning and debugging your search scores. While this article gives you a powerful head start, your journey into advanced relevance doesn't end here.
For more in-depth implementation examples, guidance on operational analytics, and best practices to ensure your embedded boost values stay aligned with business goals, we highly recommend diving into the official
MongoDB Atlas Search documentation
. It's the perfect resource for taking this pattern from concept to production.
Stop letting your search engine make all the decisions.
Try the embedded scoring pattern today
and unlock a new level of precision and power in Atlas Search.
June 24, 2025
