vector-search-stage

For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

<!-- Tab options on this page. Append to the .md URL to filter: ?tabs=<id,...> select specific tabs (e.g. ?tabs=nodejs,shell) ?allTabs=true include every tab (no param) default: one tab per tabset

Available tabs: other tabs: async, sync -->

Run Vector Search ANN and ENN Queries

A MongoDB Vector Search query takes the form of an [aggregation pipeline](https://www.mongodb.com/docs/manual/aggregation.md#std-label-aggregation that uses [$vectorSearch](https://www.mongodb.com/docs/vector-search/query/aggregation-stages/vector-search-stage.md#mongodb-pipeline-pipe.-vectorSearch as the first stage. This page explains the syntax, options, and behavior of the [$vectorSearch](https://www.mongodb.com/docs/vector-search/query/aggregation-stages/vector-search-stage.md#mongodb-pipeline-pipe.-vectorSearch stage.

The $vectorSearch stage performs a semantic search for a query vector on the specified field or fields. The field or fields must be indexed as the MongoDB Vector Search [vector](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-vector type inside a [vectorSearch](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-vector-search type index.

Note:

MongoDB Vector Search supports ANN (Approximate Nearest Neighbor) search on Atlas Clusters running MongoDB v6.0.11, v7.0.2, or later and ENN (Exact Nearest Neighbor) search on Clusters running MongoDB v6.0.16, v7.0.10, v7.3.2, or later. You can also use MongoDB Vector Search with [self-managed](https://www.mongodb.com/docs/manual/administration/install-community.md#std-label-install-mdb-community-edition or local Atlas deployments that you create with the Atlas CLI.

The $vectorSearch stage performs a semantic search for a query vector on the specified field or fields. The field or fields must be indexed as the MongoDB Vector Search [vector](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-vector type inside a [vectorSearch](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-vector-search type index.

The $vectorSearch stage is used to perform a semantic search for a natural language query on the specified field. When using automated embeddings, the field or fields must be indexed as the MongoDB Vector Search [autoEmbed](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-auto-embed type inside a [vectorSearch](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-vector-search type index.

Important:

Automated Embeddings is available as a Preview feature. The feature and the corresponding documentation might change at any time during the Preview period. Do not use this feature in your production environment. We do not use any customer data from this feature to train our models at this time. To learn more, see Preview Features.

The $vectorSearch stage is used to perform a semantic search for a natural language query on the specified field. When using automated embeddings, the field or fields must be indexed as the MongoDB Vector Search [autoEmbed](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-auto-embed type inside a [vectorSearch](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-vector-search type index.

Supported Clients

You can run [$vectorSearch](https://www.mongodb.com/docs/vector-search/query/aggregation-stages/vector-search-stage.md#mongodb-pipeline-pipe.-vectorSearch queries by using the Atlas UI, MongoDB Compass, [mongosh](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh, and any MongoDB driver.

You can also use MongoDB Vector Search with local Atlas deployments that you create with the Atlas CLI. To learn more, see Create a Local Atlas Deployment.

[$vectorSearch](https://www.mongodb.com/docs/vector-search/query/aggregation-stages/vector-search-stage.md#mongodb-pipeline-pipe.-vectorSearch is supported only on Atlas clusters running the following MongoDB versions:

• v6.0.11

• v7.0.2 and later (including RCs (Release Candidates)).

You can run [$vectorSearch](https://www.mongodb.com/docs/vector-search/query/aggregation-stages/vector-search-stage.md#mongodb-pipeline-pipe.-vectorSearch queries by using MongoDB Compass, [mongosh](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh, and any MongoDB driver.

You can run [$vectorSearch](https://www.mongodb.com/docs/vector-search/query/aggregation-stages/vector-search-stage.md#mongodb-pipeline-pipe.-vectorSearch queries by using MongoDB Compass, [mongosh](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh, and the following MongoDB drivers:

Syntax

The field that you want to search must be indexed as MongoDB Vector Search [vector](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-vector type inside a [vectorSearch](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-vector-search index type.

A $vectorSearch pipeline has the following prototype form:

{
  "$vectorSearch": {
    "exact": true | false,
    "index": "<index-name>",
    "limit": <number-of-results>,
    "numCandidates": <number-of-candidates>,
    "path": "<field-to-search>",
    "queryVector": [<array-of-numbers>],
    "filter": {<filter-specification>},
    "parentFilter": {<parent-filter-specification>},
    "nestedOptions": {
      "scoreMode": "max | avg"
    },
    "explainOptions": {
      "traceDocumentIds": [<array-of-documentIDs>]
    },
    "returnStoredSource": true | false,
    "searchNodePreference": {
      "key": <preference-string>
    }
  }
}

The field that you want to search must be indexed as MongoDB Vector Search [vector](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-vector type inside a [vectorSearch](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-vector-search index type.

A $vectorSearch pipeline has the following prototype form:

{
  "$vectorSearch": {
    "exact": true | false,
    "filter": {<filter-specification>},
    "index": "<index-name>",
    "limit": <number-of-results>,
    "numCandidates": <number-of-candidates>,
    "path": "<field-to-search>",
    "queryVector": [<array-of-numbers>],
    "explainOptions": {
      "traceDocumentIds": [<array-of-documentIDs>]
    },
    "parentFilter": {<parent-filter-specification>},
    "nestedOptions": {
      "scoreMode": "max | avg"
    },
    "returnStoredSource": true | false
  }
}

The field that you want to search must be indexed as MongoDB Vector Search [autoEmbed](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-auto-embed type inside a [vectorSearch](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-vector-search index type.

A $vectorSearch pipeline has the following prototype form:

{
  "$vectorSearch": {
    "exact": true | false,
    "filter": {<filter-specification>},
    "index": "<index-name>",
    "limit": <number-of-results>,
    "model": "<model-name>",
    "numCandidates": <number-of-candidates>,
    "path": "<field-to-search>",
    "query": {
      "text": "<query-text>"
    },
    "parentFilter": {<parent-filter-specification>},
    "nestedOptions": {
      "scoreMode": "max | avg"
    },
    "searchNodePreference": {
      "key": <preference-string>
    }
  }
}

The field that you want to search must be indexed as MongoDB Vector Search [autoEmbed](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-auto-embed type inside a [vectorSearch](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-vector-search index type.

A $vectorSearch pipeline has the following prototype form:

{
  "$vectorSearch": {
    "exact": true | false,
    "filter": {<filter-specification>},
    "index": "<index-name>",
    "limit": <number-of-results>,
    "model": "<model-name>",
    "numCandidates": <number-of-candidates>,
    "path": "<field-to-search>",
    "query": {
      "text": "<query-text>"
    }
  }
}

Fields

The $vectorSearch stage takes a document with the following fields:

Vector Search Types

When you define a [$vectorSearch](https://www.mongodb.com/docs/vector-search/query/aggregation-stages/vector-search-stage.md#mongodb-pipeline-pipe.-vectorSearch stage, you can use the exact field to specify whether to run an ANN (Approximate Nearest Neighbor) or ENN (Exact Nearest Neighbor) search.

ANN Search

Approximate Nearest Neighbors (ANN) search

For Approximate Nearest Neighbors (ANN) search, MongoDB Vector Search finds vector embeddings in your data that are closest to the vector embedding in your query based on their proximity in multi-dimensional space and based on the number of neighbors that it considers. It uses the Hierarchical Navigable Small Worlds algorithm and finds the vector embeddings most similar to the vector embedding in your query without scanning every vector. Therefore, ANN (Approximate Nearest Neighbor) search is ideal for querying large datasets without significant filtering.

Note:

Optimal [recall](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-recall for ANN (Approximate Nearest Neighbor) search is typically considered to be around 90-95% overlap in results with ENN (Exact Nearest Neighbor) search but with significantly lower latency. This provides a good balance between accuracy and performance. To achieve this with MongoDB Vector Search, [tune](https://www.mongodb.com/docs/vector-search/query/aggregation-stages/vector-search-stage.md#std-label-avs-num-candidates the numCandidates parameter at query time.

numCandidates Selection

You must specify the numCandidates field to run ANN (Approximate Nearest Neighbor) search. This field determines how many nearest neighbors MongoDB Vector Search considers during the search.

When you perform a vector search using the Hierarchical Navigable Small Worlds index structure, MongoDB Vector Search accumulates results by populating a priority queue. The numCandidates parameter controls the size of this queue, which determines how long to search before returning the top limit results. A larger queue (higher numCandidates) allows the search to explore more of the Hierarchical Navigable Small Worlds graph, potentially finding better matches at the cost of increased query latency.

We recommend that you specify a numCandidates number at least 20 times higher than the number of documents to return (limit) to increase accuracy and reduce discrepancies between your ENN (Exact Nearest Neighbor) and ANN (Approximate Nearest Neighbor) query results. For example, if you set limit to return 5 results, consider setting numCandidates to 100 as a starting point. To learn more, see [How to Measure the Accuracy of Your Query Results.](https://www.mongodb.com/docs/vector-search/query/improve-accuracy.md#std-label-avs-improve-results

This overrequest pattern is the recommended way to trade off latency and [recall](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-recall in your ANN (Approximate Nearest Neighbor) searches. However, we recommend tuning the numCandidates parameter based on your specific dataset size and query requirements. To ensure that you get accurate results, consider the following variables:

• Index Size: Larger collections typically require higher numCandidates values to maintain recall. A collection with millions of vectors might need significantly more candidates than one with thousands of vectors.

• Limit Value: Because numCandidates is highly correlated with the index size, low limit values require proportionally higher numCandidates values to maintain recall.

• Vector Quantization: [Quantized vectors](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-quantization reduce storage at the cost of accuracy. Using quantized vectors (int8 or int1 subtypes) might require higher numCandidates values compared to full precision float32 vectors to maintain similar recall.

• Index Size: Larger collections typically require higher numCandidates values to maintain recall. A collection with millions of vectors might need significantly more candidates than one with thousands of vectors.

• Limit Value: Because numCandidates is highly correlated with the index size, low limit values require proportionally higher numCandidates values to maintain recall.

ENN Search

Exact Nearest Neighbors (ENN) search

For an Exact Nearest Neighbors (ENN) search, MongoDB Vector Search exhaustively searches all the indexed vector embeddings by calculating the distance between all the embeddings and finds the exact nearest neighbor for the vector embedding in your query. This is computationally intensive and might negatively impact query latency. Therefore, we recommend ENN (Exact Nearest Neighbor) searches for the following use-cases:

• You want to determine the [recall](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-recall and accuracy of your ANN (Approximate Nearest Neighbor) query using the ideal, exact results for the ENN (Exact Nearest Neighbor) query.

• You want to query less than 10000 documents without having to tune the number of nearest neighbors to consider.

• Your want to include selective pre-filters in your query against collections where less than 5% of your data meets the given pre-filter.

If you enable automatic quantization, MongoDB Vector Search uses only the full-fidelity vectors for ENN (Exact Nearest Neighbor) queries.

• You want to determine the [recall](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-recall and accuracy of your ANN (Approximate Nearest Neighbor) query using the ideal, exact results for the ENN (Exact Nearest Neighbor) query.

• You want to query less than 10000 documents without having to tune the number of nearest neighbors to consider.

• Your want to include selective pre-filters in your query against collections where less than 5% of your data meets the given pre-filter.

Considerations

[$vectorSearch](https://www.mongodb.com/docs/vector-search/query/aggregation-stages/vector-search-stage.md#mongodb-pipeline-pipe.-vectorSearch must be the first stage of any pipeline where it appears.

Best Practices

Automated Embedding imposes rate limits on the number of requests you can make and the number of tokens you can use within a specific time frame. This is measured in tokens per minute (TPM) and requests per minute (RPM) to ensure fair usage, prevent abuse, and maintain the stability and performance of the endpoint service for all users. To learn more, see [Rate Limits](https://www.mongodb.com/docs/vector-search/crud-embeddings/automated-embedding/models.md#std-label-auto-embed-rate-limits. You can request for a rate limit increase by [contacting support.](https://www.mongodb.com/docs/atlas/support.md#std-label-request-support

You can use a different model in your query, which is compatible with the model used to create the index. This allows you to have different price and retrieval quality

（本文超出站点单文档体积上限，已截断）