Run Vector Search Queries

Atlas Vector Search Index

You must index the fields to search using the $vectorSearch stage inside a vectorSearch type index definition. You can index the following types of fields in an Atlas Vector Search vectorSearch type index definition:

• Fields that contain vector embeddings as vector type.

• Fields that contain boolean, numeric, and string values as filter type to enable vector search on pre-filtered data.

To learn more about these Atlas Vector Search field types, see How to Index Fields for Vector Search.

Atlas Vector Search Score

Atlas Vector Search assigns a score, in a fixed range from 0 to 1 only, to every document that it returns. For cosine and dotProduct similarities, Atlas Vector Search normalizes the score using the following algorithm:

score = (1 + cosine/dot_product(v1,v2)) / 2

The score assigned to a returned document is part of the document's metadata. To include each returned document's score along with the result set, use a $project stage in your aggregation pipeline.

To retrieve the score of your Atlas Vector Search query results, use vectorSearchScore as the value in the $meta expression. That is, after the $vectorSearch stage, in the $project stage, the score field takes the $meta expression. The expression requires the vectorSearchScore value to return the score of documents for the vector search.

1
db.<collection>.aggregate([
2
  {
3
    "$vectorSearch": {
4
      <query-syntax>
5
    }
6
  },
7
  {
8
    "$project": {
9
      "<field-to-include>": 1,
10
      "<field-to-exclude>": 0,
11
      "score": { "$meta": "vectorSearchScore" }
12
    }
13
  }
14
])

Atlas Vector Search Pre-Filter

The $vectorSearch filter option matches only BSON boolean, string, and numeric values. You must index the fields that you want to filter your data by as the filter type in a vectorSearch type index definition. Filtering your data is useful to narrow the scope of your semantic search and ensure that not all vectors are considered for comparison.

The $vectorSearch filter option supports only the following comparison query operators:

• $gt

• $lt

• $gte

• $lte

• $eq

  Note

  Atlas Vector Search also supports the short form of $eq. In the short form, you don't need to specify $eq in the query. For example, consider the following $eq query:

  { "genres": { "$eq": "Comedy" } }

  You can run the preceding query using the short form of $eq the following way:

  { "genres": "Comedy"  }

• $ne

• $in

• $nin

Only matches a single value and doesn't support an array of values.

The $vectorSearch filter option supports only the following aggregation pipeline operators:

• $and

• $or

Limitations

$vectorSearch is supported only on Atlas clusters running the following MongoDB versions:

• v6.0.11

• v7.0.2 and later (including RCs).

$vectorSearch can't be used in view definition and the following pipeline stages:

• $lookup sub-pipeline

• $unionWith sub-pipeline

• $facet pipeline stage

You can pass the results of $vectorSearch to this stage.

Supported Clients

You can run $vectorSearch queries using the Atlas Data Explorer, mongosh, and the following drivers:

• C#

• Java

• Node

• Pymongo

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

Parallel Query Execution Across Segments

We recommend dedicated search nodes to isolate vector search query processing. You might see improved query performance on the dedicated search nodes. Note that the high-CPU systems might provide more performance improvement. When Atlas Vector Search runs on search nodes, Atlas Vector Search parallelizes query execution across segments of data.

Parallelization of query processing improves the response time in many cases, such as queries on large datasets. Using intra-query parallelism during Atlas Vector Search query processing utilizes more resources, but improves latency for each individual query.