November 5, 2025 ・ 5 min read
For modern data-rich applications, it is fundamental to deliver users highly relevant search results. However, relying on a single search mechanism often falls short of capturing the full complexity of user intent. This post will demonstrate how to overcome this by implementing a hybrid search system in MongoDB Atlas. The specific use case involves identifying appropriate categories from a list of dozens or potentially hundreds to feed a large language model (LLM) with the relevant context to answer a question. Some examples of applications for this use case are:
- Finding definitions of specific terms th…
November 5, 2025 ・ 5 min read
For modern data-rich applications, it is fundamental to deliver users highly relevant search results. However, relying on a single search mechanism often falls short of capturing the full complexity of user intent. This post will demonstrate how to overcome this by implementing a hybrid search system in MongoDB Atlas. The specific use case involves identifying appropriate categories from a list of dozens or potentially hundreds to feed a large language model (LLM) with the relevant context to answer a question. Some examples of applications for this use case are:
- Finding definitions of specific terms that are company-specific jargon.
- Finding job titles of different companies that may be mentioned or alluded to in a user’s query.
- Finding accurate values for categorical fields in a database.
For the purposes of demonstration, a smart agent is implemented to help customers find the right product from an online home improvement store. Customers could search for specific kinds of products. However, they may not be aware of all products that meet their requirements. Consider the following search queries a customer could try:
- “Smart thermostat” → MongoDB’s agent will recommend products in the Thermostats category, and related brands.
- “Led strips” → the agent will look for light fixtures, specifically LED-based strips.
- “Tools to hang a picture on the wall” → the agent will identify diverse yet appropriate tools like adhesive hooks, no-tool hooks, nails, studs, and power tools.
- “It’s too warm at home” → the agent will recommend air conditioner units, fans, and related equipment like thermostats.
A single search mechanism is insufficient
In the above and other scenarios, a single search mechanism does not always retrieve optimal results. This is due to each search mechanism specialising in specific use cases:
- Full text search** (FTS)**: typically refers to a literal search of the query in text documents, possibly with some fuzzy matching, including typo tolerance. This can help retrieve results even when the query has some errata. E.g., “themrostat” will still retrieve “thermostats” as a result. However, it cannot take semantics into account. Therefore, unless the user input is close to one of the available product categories, text search will be unable to ascertain a result.
- Vector search: With this type of search, text documents and user queries are mapped to a semantic space. This helps determine when similar terms are semantically nearer to one another and different ones are more distant. For example, a search for “cooling solutions” would find “Air Conditioning Units” even though the exact words do not match. However, vector search will struggle if the query is misspelled or contains acronyms with no clear meaning, context, or includes ambiguous words.
For the original example, queries number 1 and 2 (“smart thermostat”, “led strips”) can be addressed with text search if there are matching product categories in the database. Vector search would be ideal for queries 3 and 4 (“tools to hang a picture”, “it’s too warm”) since they have clear meanings however have no exact matches in terms of a product category.
This inherent limitation of individual search approaches highlights the need for a more comprehensive solution. This is where hybrid search comes into play.
Solution overview
Figure 1. A dependency graph connecting the different components of the solution. $rankFusion uses both search mechanisms: FTS and vector search. All components run solely on MongoDB Atlas.
Hybrid search is a technique that combines multiple search methods to utilize their individual strengths. This provides more accurate and comprehensive results. By integrating different search algorithms, a wider range of user queries can be addressed, from precise keyword matching to conceptual understanding.
The key to effective hybrid search lies in intelligently combining the results from different search mechanisms. Merging results without qualification can lead to redundancy or lower relevance. This is where advanced aggregation techniques like reciprocal rank fusion are critical.
Reciprocal Rank Fusion (RRF) is an algorithm that combines ranked lists from multiple search systems into a single, unified ranking. Instead of merging or averaging scores, RRF assigns each result a score based on its position (or rank) in each individual list. Results that appear near the top of any list are attributed a greater weighting.
In MongoDB Atlas, the $rankFusion aggregation stage implements RRF natively. This enables combining results from FTS and vector search pipelines in a single query.
Implementation on MongoDB Atlas
MongoDB Atlas offers a single platform to implement native hybrid search by combining:
- Atlas Search for fuzzy matching.
- Atlas vector search for semantic understanding.
- The $rankFusion aggregation stage to intelligently combine all results.
The solution will be comprised of three straightforward steps:
- Compute the term embeddings for the documents in the database.
- Create the search indexes for both text and vector search.
- Define the aggregation pipeline that performs hybrid search and combines results with $rankFusion.
The full script is available here, and the relevant snippets are highlighted below.
Compute term embeddings
The main prerequisite to perform vector search is to compute vector embeddings for the terms that will be stored in the database. Assuming all product categories in a categories list have been collected, those embeddings can be created and saved to a collection:
Python
Code Snippet
The previous snippet uses the Voyage AI client to generate embeddings using the “voyage-3” model. For efficiency, multiple texts can be batched at once, and Voyage AI will return a list of embeddings.
Create search indexes
MongoDB Atlas requires specific indexes for both FTS and vector search. This is how they can be created:
Python
Code Snippet
The vector search index is configured to handle 1024-dimensional embeddings from the Voyage-3 model using cosine similarity. The FTS index enables fuzzy text matching on the field_value field.
Aggregate search results
The core of hybrid search is the aggregation pipeline that combines results from both search methods using MongoDB’s native $rankFusion operator:
Python
Code Snippet
The $rankFusion operator intelligently combines and re-ranks results from both pipelines:
- Vector Pipeline: Performs semantic search using $vectorSearch to find conceptually similar terms.
- FTS Pipeline: Uses $search with fuzzy matching to handle exact matches and typos.
To adjust the behavior of the RRF algorithm, each search pipeline can be weighted to balance which one contributes more to the final score. Additionally, if the scoreDetails parameter is set to True, the final score can be extracted as well as the score breakdown for each result.
In the example above two search stages have been included in the pipelines field. However, $rankFusion is not limited to combining the results of two pipelines. Additional search stages or $match, $sample and $geoNear stages can be added. These can also be combined by the same algorithm. Note: each stage must have a distinct name and target the same collection.
Results and benefits
This is how the hybrid approach performs with the example queries cited above:
Query: “smart thermostat”
- Text search: Finds exact match for “Thermostats” category.
- Vector search: Identifies semantically related HVAC categories.
- Combined: Returns thermostats as the top result with high confidence.
Query: “led strips”
- Text search: Finds a match for “LED fixtures” category.
- Vector search: Matches several categories, assigns most relevance to “Power tools.”
- Combined: Returns LED fixtures with high confidence, as it was retrieved by both pipelines.
Query: “it’s too warm at home”
- Text search: No exact category match, retrieved results are not relevant.
- Vector search: Identifies “Air Conditioning Units”, “Thermostats” as conceptually relevant.
- Combined: Returns climate control products despite no exact text match.
Unformatted
Code Snippet
Query: “tools to hang a picture on the wall”
- Text search: Finds partial matches for “tools” and “wall.”
- Vector search: Identifies “Adhesive Hooks” and “Wall Anchors” categories.
- Combined: Returns a comprehensive list of picture-hanging solutions.
Conclusion
Hybrid search with MongoDB Atlas delivers a powerful solution for applications that require both precision and semantic understanding. By combining text search, vector search, and intelligent rank fusion, highly relevant results are delivered that match user intent. Concurrently, tolerance for variations in how queries are expressed is maintained. Five key advantages of this approach are:
- Semantic understanding: Vector search captures intent even when exact keywords do not match.
- Typo tolerance: Text search with fuzzy matching handles misspellings.
- Balanced results: Rank fusion prevents either search method from dominating results.
- Native implementation: MongoDB’s built-in operators provide optimal performance.
- Flexible scoring: Can adjust weights between different search methods.
The native implementation using $rankFusion ensures this approach is both performant and maintainable. This eliminates the need for complex client-side result merging logic. Whether building product recommendation systems, knowledge bases, or content discovery platforms, hybrid search significantly improves search relevance and user satisfaction.
To get started with this implementation, you will need:
- A MongoDB Atlas cluster with Atlas Search enabled and running MongoDB 8.0 or later.
- An embedding service (like Voyage AI).
- Indexed documents with both text fields and vector embeddings.
The complete code example is available and demonstrates how to implement this system end-to-end for a home improvement store use case.
Next Steps
MongoDB Resources
For modern data-rich applications, it is fundamental to deliver users highly relevant search results. However, relying on a single search mechanism often falls short of capturing the full complexity of user intent. This post will demonstrate how to overcome this by implementing a hybrid search system in MongoDB Atlas. The specific use case involves identifying appropriate categories from a list of dozens or potentially hundreds to feed a large language model (LLM) with the relevant context to answer a question. Some examples of applications for this use case are:
- Finding definitions of specific terms that are company-specific jargon.
- Finding job titles of different companies that may be mentioned or alluded to in a user’s query.
- Finding accurate values for categorical fields in a database.
For the purposes of demonstration, a smart agent is implemented to help customers find the right product from an online home improvement store. Customers could search for specific kinds of products. However, they may not be aware of all products that meet their requirements. Consider the following search queries a customer could try:
- “Smart thermostat” → MongoDB’s agent will recommend products in the Thermostats category, and related brands.
- “Led strips” → the agent will look for light fixtures, specifically LED-based strips.
- “Tools to hang a picture on the wall” → the agent will identify diverse yet appropriate tools like adhesive hooks, no-tool hooks, nails, studs, and power tools.
- “It’s too warm at home” → the agent will recommend air conditioner units, fans, and related equipment like thermostats.
A single search mechanism is insufficient
In the above and other scenarios, a single search mechanism does not always retrieve optimal results. This is due to each search mechanism specialising in specific use cases:
- Full text search** (FTS)**: typically refers to a literal search of the query in text documents, possibly with some fuzzy matching, including typo tolerance. This can help retrieve results even when the query has some errata. E.g., “themrostat” will still retrieve “thermostats” as a result. However, it cannot take semantics into account. Therefore, unless the user input is close to one of the available product categories, text search will be unable to ascertain a result.
- Vector search: With this type of search, text documents and user queries are mapped to a semantic space. This helps determine when similar terms are semantically nearer to one another and different ones are more distant. For example, a search for “cooling solutions” would find “Air Conditioning Units” even though the exact words do not match. However, vector search will struggle if the query is misspelled or contains acronyms with no clear meaning, context, or includes ambiguous words.
For the original example, queries number 1 and 2 (“smart thermostat”, “led strips”) can be addressed with text search if there are matching product categories in the database. Vector search would be ideal for queries 3 and 4 (“tools to hang a picture”, “it’s too warm”) since they have clear meanings however have no exact matches in terms of a product category.
This inherent limitation of individual search approaches highlights the need for a more comprehensive solution. This is where hybrid search comes into play.
Solution overview
Figure 1. A dependency graph connecting the different components of the solution. $rankFusion uses both search mechanisms: FTS and vector search. All components run solely on MongoDB Atlas.
Hybrid search is a technique that combines multiple search methods to utilize their individual strengths. This provides more accurate and comprehensive results. By integrating different search algorithms, a wider range of user queries can be addressed, from precise keyword matching to conceptual understanding.
The key to effective hybrid search lies in intelligently combining the results from different search mechanisms. Merging results without qualification can lead to redundancy or lower relevance. This is where advanced aggregation techniques like reciprocal rank fusion are critical.
Reciprocal Rank Fusion (RRF) is an algorithm that combines ranked lists from multiple search systems into a single, unified ranking. Instead of merging or averaging scores, RRF assigns each result a score based on its position (or rank) in each individual list. Results that appear near the top of any list are attributed a greater weighting.
In MongoDB Atlas, the $rankFusion aggregation stage implements RRF natively. This enables combining results from FTS and vector search pipelines in a single query.
Implementation on MongoDB Atlas
MongoDB Atlas offers a single platform to implement native hybrid search by combining:
- Atlas Search for fuzzy matching.
- Atlas vector search for semantic understanding.
- The $rankFusion aggregation stage to intelligently combine all results.
The solution will be comprised of three straightforward steps:
- Compute the term embeddings for the documents in the database.
- Create the search indexes for both text and vector search.
- Define the aggregation pipeline that performs hybrid search and combines results with $rankFusion.
The full script is available here, and the relevant snippets are highlighted below.
Compute term embeddings
The main prerequisite to perform vector search is to compute vector embeddings for the terms that will be stored in the database. Assuming all product categories in a categories list have been collected, those embeddings can be created and saved to a collection:
Python
Code Snippet
The previous snippet uses the Voyage AI client to generate embeddings using the “voyage-3” model. For efficiency, multiple texts can be batched at once, and Voyage AI will return a list of embeddings.
Create search indexes
MongoDB Atlas requires specific indexes for both FTS and vector search. This is how they can be created:
Python
Code Snippet
The vector search index is configured to handle 1024-dimensional embeddings from the Voyage-3 model using cosine similarity. The FTS index enables fuzzy text matching on the field_value field.
Aggregate search results
The core of hybrid search is the aggregation pipeline that combines results from both search methods using MongoDB’s native $rankFusion operator:
Python
Code Snippet
The $rankFusion operator intelligently combines and re-ranks results from both pipelines:
- Vector Pipeline: Performs semantic search using $vectorSearch to find conceptually similar terms.
- FTS Pipeline: Uses $search with fuzzy matching to handle exact matches and typos.
To adjust the behavior of the RRF algorithm, each search pipeline can be weighted to balance which one contributes more to the final score. Additionally, if the scoreDetails parameter is set to True, the final score can be extracted as well as the score breakdown for each result.
In the example above two search stages have been included in the pipelines field. However, $rankFusion is not limited to combining the results of two pipelines. Additional search stages or $match, $sample and $geoNear stages can be added. These can also be combined by the same algorithm. Note: each stage must have a distinct name and target the same collection.
Results and benefits
This is how the hybrid approach performs with the example queries cited above:
Query: “smart thermostat”
- Text search: Finds exact match for “Thermostats” category.
- Vector search: Identifies semantically related HVAC categories.
- Combined: Returns thermostats as the top result with high confidence.
Query: “led strips”
- Text search: Finds a match for “LED fixtures” category.
- Vector search: Matches several categories, assigns most relevance to “Power tools.”
- Combined: Returns LED fixtures with high confidence, as it was retrieved by both pipelines.
Query: “it’s too warm at home”
- Text search: No exact category match, retrieved results are not relevant.
- Vector search: Identifies “Air Conditioning Units”, “Thermostats” as conceptually relevant.
- Combined: Returns climate control products despite no exact text match.
Unformatted
Code Snippet
Query: “tools to hang a picture on the wall”
- Text search: Finds partial matches for “tools” and “wall.”
- Vector search: Identifies “Adhesive Hooks” and “Wall Anchors” categories.
- Combined: Returns a comprehensive list of picture-hanging solutions.
Conclusion
Hybrid search with MongoDB Atlas delivers a powerful solution for applications that require both precision and semantic understanding. By combining text search, vector search, and intelligent rank fusion, highly relevant results are delivered that match user intent. Concurrently, tolerance for variations in how queries are expressed is maintained. Five key advantages of this approach are:
- Semantic understanding: Vector search captures intent even when exact keywords do not match.
- Typo tolerance: Text search with fuzzy matching handles misspellings.
- Balanced results: Rank fusion prevents either search method from dominating results.
- Native implementation: MongoDB’s built-in operators provide optimal performance.
- Flexible scoring: Can adjust weights between different search methods.
The native implementation using $rankFusion ensures this approach is both performant and maintainable. This eliminates the need for complex client-side result merging logic. Whether building product recommendation systems, knowledge bases, or content discovery platforms, hybrid search significantly improves search relevance and user satisfaction.
To get started with this implementation, you will need:
- A MongoDB Atlas cluster with Atlas Search enabled and running MongoDB 8.0 or later.
- An embedding service (like Voyage AI).
- Indexed documents with both text fields and vector embeddings.
The complete code example is available and demonstrates how to implement this system end-to-end for a home improvement store use case.