Hybrid Search

This guide covers hybrid search patterns in MongoDB Atlas: combining vector and lexical search using $rankFusion and $scoreFusion, and using lexical prefilters with the vectorSearch operator inside $search.

Scope: This guide covers hybrid pipelines. For pure vector search indexes and $vectorSearch query construction, see vector-search.md. For lexical index definitions and query patterns, see lexical-search-indexing.md and lexical-search-querying.md.

Table of Contents

• Overview
• Choosing the Right Approach
• Indexing for Hybrid Search
• $rankFusion
• $scoreFusion
• Lexical Prefilters (vectorSearch Operator)
• Best Practices and Limitations

---

Overview

Hybrid search combines multiple search methods on the same collection and merges the results into a single ranked or scored list.

Three patterns covered in this guide:

$rankFusion vs $scoreFusion:

• $rankFusion ranks by position in each input pipeline using the Reciprocal Rank Fusion (RRF) algorithm. A document ranked #1 in multiple pipelines scores much higher than one ranked #1 in only one. Weights influence how much each pipeline's rank contributes.
• $scoreFusion ranks by the actual score values from each pipeline. Supports normalization (sigmoid, minMaxScaler) and custom combination expressions. Use when score magnitude, not just ordering, matters.

---

Choosing the Right Approach

Version requirements: $rankFusion requires MongoDB 8.0+. $scoreFusion requires MongoDB 8.2+. Only proceed with this guide if the use case is lexical prefilters, or if the cluster meets the version requirement for the fusion stage of interest. Otherwise do not proceed.

---

Indexing for Hybrid Search

For $rankFusion and $scoreFusion

You need two separate indexes on the collection:

1. A vectorSearch-type index for the $vectorSearch input pipeline:

db.collection.createSearchIndex(
  "<vector-index-name>",
  "vectorSearch",
  {
    "fields": [
      {
        "type": "vector",
        "path": "<embedding-field>",
        "numDimensions": <number>,
        "similarity": "dotProduct"
      }
    ]
  }
)

2. A search-type index for the $search input pipeline:

db.collection.createSearchIndex(
  "<search-index-name>",
  {
    "mappings": { "dynamic": true }
  }
)

---

For Lexical Prefilters (vectorSearch Operator)

The vectorSearch operator runs inside $search, so you need a single search-type index that includes a vector field type. This is different from a vectorSearch-type index — you cannot use the $vectorSearch stage to query fields indexed this way.

db.collection.createSearchIndex(
  "<search-index-name>",
  {
    "mappings": {
      "dynamic": true,
      "fields": {
        "<embedding-field>": {
          "type": "vector",
          "numDimensions": <number>,
          "similarity": "dotProduct",
          "quantization": "scalar"  // Optional
        }
      }
    }
  }
)

Note: storedSource: true is not supported on indexes that contain a vector field type. Use include or exclude to specify stored fields explicitly.

---

Common Rules for Fusion Stages

The following rules apply to both $rankFusion and $scoreFusion.

Pipeline naming restrictions: Pipeline names must not be empty, start with $, contain the null character \\0, or contain .

Not allowed inside input pipelines: $project or storedSource fields. Apply modifications ($project, $addFields, $set) in stages after the fusion stage.

---

$rankFusion

$rankFusion executes all input pipelines independently, de-duplicates results, and ranks them using the Reciprocal Rank Fusion (RRF) algorithm. Documents appearing highly ranked in multiple pipelines score highest.

Syntax

{
  $rankFusion: {
    input: {
      pipelines: {
        <pipelineName1>: [ <stages> ],
        <pipelineName2>: [ <stages> ],
        ...
      }
    },
    combination: {
      weights: {
        <pipelineName1>: <number>,
        <pipelineName2>: <number>
      }
    },
    scoreDetails: <boolean>  // Default: false
  }
}

Fields

RRF Formula

For each document, the RRF score is:

RRFscore(d) = sum over all pipelines of: weight * (1 / (60 + rank_of_d_in_pipeline))

The constant 60 is a sensitivity parameter set by MongoDB and cannot be changed. Documents not present in a pipeline do not contribute a term for that pipeline.

Input Pipeline Restrictions

See Common Rules for naming and modification restrictions. Allowed stages: $search, $vectorSearch, $match, $geoNear, $sample, $sort, $skip, $limit.

The ordering requirement is satisfied if the pipeline begins with $search, $vectorSearch, or $geoNear, or contains an explicit $sort.

---

Example 1: Basic Hybrid (Vector + Lexical, Equal Weights)

db.embedded_movies.aggregate([
  {
    $rankFusion: {
      input: {
        pipelines: {
          vectorPipeline: [
            {
              $vectorSearch: {
                index: "<vector-index-name>",
                path: "plot_embedding",
                queryVector: [<query-vector-2048-dimensions>],
                numCandidates: 100,
                limit: 20
              }
            }
          ],
          textPipeline: [
            {
              $search: {
                index: "<search-index-name>",
                text: {
                  query: "<query-term>",
                  path: "title"
                }
              }
            },
            { $limit: 20 }
          ]
        }
      }
    }
  },
  { $limit: 10 }
])

Note: $search does not auto-limit results — always add $limit inside the $search input pipeline.

---

Example 2: Weighted Hybrid (Boosting One Pipeline)

Assign higher weight to the pipeline whose ranking should contribute more to the final score:

db.embedded_movies.aggregate([
  {
    $rankFusion: {
      input: {
        pipelines: {
          vectorPipeline: [
            {
              $vectorSearch: {
                index: "<vector-index-name>",
                path: "plot_embedding",
                queryVector: [<query-vector-2048-dimensions>],
                numCandidates: 100,
                limit: 20
              }
            }
          ],
          textPipeline: [
            {
              $search: {
                index: "<search-index-name>",
                phrase: {
                  query: "<query-term>",
                  path: "title"
                }
              }
            },
            { $limit: 20 }
          ]
        }
      },
      combination: {
        weights: {
          vectorPipeline: 0.7,
          textPipeline: 0.3
        }
      }
    }
  },
  { $limit: 10 }
])

Recommendation: Set weights per-query based on which method is more appropriate for that query, rather than using static weights for all queries.

---

Example 3: Multiple $vectorSearch Pipelines

Use multiple vector pipelines to search different fields, different query vectors, or different embedding models:

db.embedded_movies.aggregate([
  {
    $rankFusion: {
      input: {
        pipelines: {
          plotPipeline: [
            {
              $vectorSearch: {
                index: "<vector-index-name>",
                path: "plot_embedding_voyage",
                queryVector: [<query-vector-2048-dimensions>],
                numCandidates: 200,
                limit: 50
              }
            }
          ],
          titlePipeline: [
            {
              $vectorSearch: {
                index: "<vector-index-name>",
                path: "title_embedding_voyage",
                queryVector: [<query-vector-2048-dimensions>],
                numCandidates: 200,
                limit: 50
              }
            }
          ]
        }
      },
      combination: {
        weights: {
          plotPipeline: 0.5,
          titlePipeline: 0.5
        }
      }
    }
  },
  { $limit: 20 }
])

---

Surfacing scoreDetails

Set scoreDetails: true on the stage, then project via $meta: "scoreDetails". The output includes a value (final RRF score), description, and a details array — one entry per input pipeline — containing inputPipelineName, rank, weight, and optionally value (raw pipeline score). See the $scoreFusion scoreDetails section below for a concrete structure example; $rankFusion follows the same pattern with rank instead of inputPipelineRawScore.

---

$scoreFusion

$scoreFusion executes all input pipelines independently, de-duplicates results, and combines them using the actual score values from each pipeline. Supports normalization and custom combination expressions for fine-grained control over how scores are merged.

Syntax

{
  $scoreFusion: {
    input: {
      pipelines: {
        <pipelineName1>: [ <stages> ],
        <pipelineName2>: [ <stages> ],
        ...
      },
      normalization: "none | sigmoid | minMaxScaler"
    },
    combination: {
      weights: {
        <pipelineName1>: <number>,
        <pipelineName2>: <number>
      },
      method: "avg | expression",
      expression: <arithmetic-expression>
    },
    scoreDetails: <boolean>
  }
}

Fields

Normalization Options

Input Pipeline Restrictions

See Common Rules for naming and modification restrictions. Allowed stages: $search, $vectorSearch, $match, $geoNear, $sort, $skip, $limit. Note: unlike $rankFusion, $sample is not permitted.

The scoring requirement is satisfied if the pipeline begins with $search, $vectorSearch, $match with legacy text search, or $geoNear. Otherwise, include an explicit $score stage.

---

Example 1: avg Method with Weights

db.embedded_movies.aggregate([
  {
    $scoreFusion: {
      input: {
        pipelines: {
          vectorPipeline: [
            {
              $vectorSearch: {
                index: "<vector-index-name>",
                path: "plot_embedding",
                queryVector: [<query-vector-2048-dimensions>],
                numCandidates: 100,
                limit: 20
              }
            }
          ],
          textPipeline: [
            {
              $search: {
                index: "<search-index-name>",
                text: {
                  query: "<query-term>",
                  path: "title"
                }
              }
            },
            { $limit: 20 }
          ]
        },
        normalization: "sigmoid"
      },
      combination: {
        method: "avg",
        weights: {
          vectorPipeline: 2,
          textPipeline: 1
        }
      }
    }
  },
  { $limit: 10 }
])

---

Example 2: expression Method with Custom Score Math

Use expression when you need full control over how pipeline scores are combined. Reference pipeline names as variables in the expression:

db.embedded_movies.aggregate([
  {
    $scoreFusion: {
      input: {
        pipelines: {
          searchOne: [
            {
              $vectorSearch: {
                index: "<vector-index-name>",
                path: "plot_embedding",
                queryVector: [<query-vector-2048-dimensions>],
                numCandidates: 100,
                limit: 20
              }
            }
          ],
          searchTwo: [
            {
              $search: {
                index: "<search-index-name>",
                text: {
                  query: "<query-term>",
                  path: "title"
                }
              }
            },
            { $limit: 20 }
          ]
        },
        normalization: "sigmoid"
      },
      combination: {
        method: "expression",
        expression: {
          $sum: [
            { $multiply: ["$searchOne", 10] },
            "$searchTwo"
          ]
        }
      },
      scoreDetails: true
    }
  },
  {
    $project: {
      _id: 1,
      title: 1,
      plot: 1,
      scoreDetails: { $meta: "scoreDetails" }
    }
  },
  { $limit: 10 }
])

Note: combination.expression and combination.weights are mutually exclusiv