Docs Menu
Docs Home
/ /
Operators & Collectors
Docs Home
/ /
Query Reference
/
Operators & Collectors
Docs Home
/
Development
/
Search
/
Queries & Indexes
/
Query Reference
/
Operators & Collectors

vectorSearch (MongoDB Search Operator)

Definition

The vectorSearch operator performs an ANN or ENN search on vector embeddings in the specified field. Use this operator to add analyzed text capabilities such a fuzzy search, phrase matching, location filtering, wildcard pattern matching, and so on alongside semantic search.

Syntax

vectorSearch has the following syntax:

{
  "$search": {
    "index": "<index name>", // optional, defaults to "default"
    "vectorSearch": {
      "exact": true | false,
      "filter": {<operator-specification>},
      "limit": <number-of-results>,
      "numCandidates": <number-of-candidates>,
      "path": "<field-to-search>",
      "queryVector": [<array-of-numbers>],
      "score": {<options>}
    }
  }
}

Options

vectorSearch uses the following fields to construct a query:

Field
Type
Necessity
Description

exact

Boolean

Optional

This is required if numCandidates is omitted.

Flag that specifies whether to run ENN or ANN search. Value can be one of the following:

  • false - to run ANN search

  • true - to run ENN search

If omitted, defaults to false.

MongoDB Vector Search supports ANN search on clusters running MongoDB v6.0.11, v7.0.2, or later and ENN search on clusters running MongoDB v6.0.16, v7.0.10, v7.3.2, or later.

filter

Object

Optional

MongoDB Search operator to use to pre-filter documents based on metadata or specific search criteria.

To learn more, see Pre-Filter.

limit

Int

Required

Number (of type int only) of documents to return in the results. This value can't exceed the value of numCandidates if you specify numCandidates.

On sharded clusters, you must use $limit after the $search stage to limit the number of documents in the results.

numCandidates

Int

Optional

This field is required if exact is false or omitted.

Number of nearest neighbors to use during the search. Value must be less than or equal to (<=) 10000. You can't specify a number less than the number of documents to return (limit).

We recommend that you specify a number at least 20 times higher than the number of documents to return (limit) to increase accuracy.

This overrequest pattern is the recommended way to trade off latency and recall in your ANN searches, and we recommend tuning this parameter based on your specific dataset size and query requirements.

path

String

Required

Indexed vector type field to search.

queryVector

Array of Integers or Floats

Required

Array of numbers of float32, BSON BinData vectors with subtype float32, or BSON BinData vectors with subtype int1 or int8 type that represent the query vector.

To learn more about generating BSON binData vectors with subtype float32, int8, or int1, see How to Ingest Pre-Quantized Vectors.

The array size must match the number of vector dimensions (numDimensions) specified in the index definition for the field.

You must embed your query with the same model that you used to embed the data.

You can query your embeddings with full-fidelity vectors, as long as the vector subtype is the same. This is only possible with binData vectors with subtype float32. If you use any other subtype (int8 or int1), MongoDB Search doesn't return any results or errors.

score

Object

Optional

Score assigned to matching search term results. Use one of the following options to modify the score:

  • boost: multiply the result score by the given number.

  • constant: replace the result score with the given number.

  • function: replace the result score using the given expression.

For information on using score in your query, see Score the Documents in the Results.

Behavior

MongoDB Search Index

You must index the fields to search using the vectorSearch operator. You can index the following types of fields in the MongoDB Search index definition:

  • Field that contains vector embeddings. This is the field you specify in the query path option.

  • Fields to pre-filter the documents. These are the fields you specify in the query filter option.

Pre-Filter

You can pre-filter the documents to narrow the scope of your semantic search and ensure that not all vectors are considered for comparison. You can use any supported MongoDB Search operator in the filter field to query and filter the documents.

You must index the fields that you want to filter your data in the index definition for the vector type.

Score

You can include the score of each document in your search results. Specify the $meta expression with the searchScore value in the $project stage. You can also specify the searchScoreDetails value for the scoreDetails field $meta expression for a detailed breakdown of the score.

To learn more, see Score the Documents in the Results and Return the Score Details.

vectorSearch Operator Limitations

The vectorSearch operator must be the top-level operator in your queries. Therefore, you can't use the vectorSearch operator inside the following MongoDB Search operators:

You can't use the vectorSearch operator to query fields indexed using a vectorSearch type index.

You can't use the following $search options with the vectorSearch operator:

You can't run $search queries with the vectorSearch operator using the Search Tester.

Examples

The following examples use the sample_mflix.embedded_movies collection from the sample data. If you load the sample data and create the sample index on the collection, you can run the following ANN and ENN queries against the collection after replacing the <connection-string> and <index-name> placeholders in the queries.

Back

text

Next

wildcard

On this page