Docs Menu
Docs Home
/
MongoDB Atlas
/

How to Index Fields for Vector Search

On this page

  • Considerations
  • Syntax
  • About the vector Type
  • About the filter Type
  • Atlas Vector Search Index Fields
  • Create an Atlas Vector Search Index
  • Prerequisites
  • Required Access
  • Procedure
  • View an Atlas Vector Search Index
  • Required Access
  • Procedure
  • Edit an Atlas Vector Search Index
  • Required Access
  • Procedure
  • Delete an Atlas Vector Search Index
  • Required Access
  • Procedure
  • Index Status

You can use the vectorSearch type to index fields for running $vectorSearch queries. You can define the index for the vector embeddings that you want to query and the boolean, date, objectId, numeric, or string values that you want to use to pre-filter your data. Filtering your data is useful to narrow the scope of your semantic search and ensure that certain vector embeddings are not considered for comparison, such as in a multi-tenant environment.

You can use the Atlas UI, Atlas Administration API, Atlas CLI, mongosh, or a supported MongoDB Driver to create your Atlas Vector Search index.

Note

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

In a vectorSearch type index definition, you can index arrays with only a single element. You can't index fields inside arrays of documents or fields inside arrays of objects. You can index fields inside documents using the dot notation.

The following syntax defines the vectorSearch index type:

1{
2 "fields":[
3 {
4 "type": "vector",
5 "path": "<field-to-index>",
6 "numDimensions": <number-of-dimensions>,
7 "similarity": "euclidean | cosine | dotProduct"
8 },
9 {
10 "type": "filter",
11 "path": "<field-to-index>"
12 },
13 ...
14 ]
15}

The vector field must contain an array of numbers of the BSON double data type for querying using the $vectorSearch pipeline stage. You must index the vector field as the vector type inside the fields array.

The following syntax defines the vector field type:

1{
2 "fields":[
3 {
4 "type": "vector",
5 "path": <field-to-index>,
6 "numDimensions": <number-of-dimensions>,
7 "similarity": "euclidean | cosine | dotProduct"
8 },
9 ...
10 ]
11}

You can optionally index boolean, objectId, numeric, date, and string values to pre-filter your data. Filtering your data is useful to narrow the scope of your semantic search and ensure that not all vectors are considered for comparison. You must index your boolean, objectId, numeric, date, and string fields using the filter type inside the fields array.

The following syntax defines the filter field type:

1{
2 "fields":[
3 {
4 "type": "vector",
5 ...
6 },
7 {
8 "type": "filter",
9 "path": "<field-to-index>"
10 },
11 ...
12 ]
13}

Note

Pre-filtering your data doesn't affect the score that Atlas Vector Search returns using $vectorSearchScore for $vectorSearch queries.

The Atlas Vector Search index definition takes the following fields:

Option
Type
Necessity
Purpose
fields
array of documents
Required
Vector and filter fields to index, one per document. At least one document must contain the field definition for the vector field. You can optionally also index date, number, objectId, boolean, and string fields, one per document, for pre-filtering the data.
fields.type
string
Required

Field type to use to index fields for $vectorSearch. You can specify one of the following values:

  • vector - for fields that contain vector embeddings.

  • filter - for fields that contain boolean, date, objectId, numeric, or string values.

fields.path
string
Required

Name of the field to index. For nested fields, use dot notation to specify path to embedded fields. You can't index field names with two consecutive dots (.) and field names ending with dots (.). For example, Atlas Vector Search doesn't support indexing the following field names:

foo..bar
Field name has two consecutive dots.
foo_bar.
Field name ends with a dot.
fields.numDimensions
int
Required
Number of vector dimensions that Atlas Vector Search enforces at index-time and query-time. You must specify a value less than or equal to 4096. You can set this field only for vector type fields.
fields.similarity
string
Required

Vector similarity function to use to search for top K-nearest neighbors. You can set this field only for vector type fields. Value include:

  • euclidean - measures the distance between ends of vectors. This value allows you to measure similarity based on varying dimensions. To learn more, see Euclidean.

  • cosine - measures similarity based on the angle between vectors. This value allows you to measure similarity that isn't scaled by magnitude. You can't use zero magnitude vectors with cosine. To measure cosine similarity, we recommend that you normalize your vectors and use dotProduct instead. To learn more, see Cosine.

  • dotProduct - measures similar to cosine, but takes into account the magnitude of the vector. This value allows you to efficiently measure similarity based on both angle and magnitude. To use dotProduct, you must normalize the vector to unit length at index-time and query-time. To learn more, see Dot Product.

Note

If you normalize the magnitude, cosine and dotProduct are almost identical in measuring similarity.

An Atlas Search index is a data structure that categorizes data in an easily searchable format. It is a mapping between terms and the documents that contain those terms. Atlas Search indexes enable faster retrieval of documents using certain identifiers. You must configure an Atlas Search index to query data in your Atlas cluster using Atlas Search.

You can create an Atlas Search index on a single field or on multiple fields. We recommend that you index the fields that you regularly use to sort or filter your data in order to quickly retrieve the documents that contain the relevant data at query-time.

You can create an Atlas Vector Search index for all collections that contain vector embeddings less than or equal to 4096 dimensions in length for any kind of data along with other data on your Atlas cluster through the Atlas UI, Atlas Administration API, Atlas CLI, mongosh, or a supported MongoDB Driver.

To create an Atlas Vector Search index, you must have an Atlas cluster with the following prerequisites:

  • MongoDB version 6.0.11, 7.0.2, or higher

  • A collection for which to create the Atlas Vector Search index

Note

You can't use the mongosh command or driver helper methods to create Atlas Search indexes on M0, M2, or M5 Atlas clusters. To create and manage Atlas Search indexes using mongosh or the driver, upgrade to a dedicated cluster tier.

You need the Project Data Access Admin or higher role to create and manage Atlas Vector Search indexes.


Use the Select your language drop-down menu to select the client you want to use to create your index.


Note

The procedure includes index definition examples for the embedded_movies collection in the sample_mflix database. If you load the sample data on your cluster and create the example Atlas Search indexes for this collection, you can run the sample $vectorSearch queries against this collection. To learn more about the sample queries that you can run, see $vectorSearch Examples.

To create an Atlas Vector Search index for a collection using the Atlas Administration API, send a POST request to the Atlas Search indexes endpoint with the required parameters.

1curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
2--header "Accept: application/json" \
3--header "Content-Type: application/json" \
4--include \
5--request POST "https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/clusters/{clusterName}/search/indexes" \
6--data '
7 {
8 "database": "<name-of-database>",
9 "collectionName": "<name-of-collection>",
10 "type": "vectorSearch",
11 "name": "<index-name>",
12 "definition": {
13 "fields":[
14 {
15 "type": "vector",
16 "path": <field-to-index>,
17 "numDimensions": <number-of-dimensions>,
18 "similarity": "euclidean | cosine | dotProduct"
19 },
20 {
21 "type": "filter",
22 "path": "<field-to-index>"
23 },
24 ...
25 }
26 ]
27 }'

To learn more about the syntax and parameters for the endpoint, see Create One Atlas Search Index.

Example

The following index definition indexes the plot_embedding field as the vector type and the genres and year fields as the filter type in an Atlas Vector Search index. The plot_embedding field contains embeddings created using OpenAI's text-embedding-ada-002 embeddings model. The index definition specifies 1536 vector dimensions and measures similarity using euclidean distance.

The following index definition indexes only the vector embeddings field for performing vector search.

1curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
2--header "Accept: application/json" \
3--header "Content-Type: application/json" \
4--include \
5--request POST "https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/clusters/{clusterName}/search/indexes" \
6--data '
7 {
8 "database": "sample_mflix",
9 "collectionName": "embedded_movies",
10 "type": "vectorSearch",
11 "name": "vector_index",
12 "definition: {
13 "fields":[
14 {
15 "type": "vector",
16 "path": "plot_embedding",
17 "numDimensions": 1536,
18 "similarity": "euclidean"
19 }
20 ]
21 }
22 }'

This index definition indexes the following fields:

  • A string field (genres) and a numeric field (year) for pre-filtering the data.

  • The vector embeddings field (plot_embedding) for performing vector search against pre-filtered data.

1curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
2--header "Accept: application/json" \
3--header "Content-Type: application/json" \
4--include \
5--request POST "https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/clusters/{clusterName}/search/indexes" \
6--data '
7 {
8 "database": "sample_mflix",
9 "collectionName": "embedded_movies",
10 "type": "vectorSearch",
11 "name": "vector_index",
12 "definition: {
13 "fields":[
14 {
15 "type": "vector",
16 "path": "plot_embedding",
17 "numDimensions": 1536,
18 "similarity": "euclidean"
19 },
20 {
21 "type": "filter",
22 "path": "genres"
23 },
24 {
25 "type": "filter",
26 "path": "year"
27 }
28 ]
29 }
30 }'

To create an Atlas Vector Search index for a collection using the Atlas CLI v1.14.3 or later, perform the following steps:

1

Your index definition should resemble the following format:

1{
2 "database": "<name-of-database>",
3 "collectionName": "<name-of-collection>",
4 "type": "vectorSearch",
5 "name": "<index-name>",
6 "fields":[
7 {
8 "type": "vector",
9 "path": "<field-to-index>",
10 "numDimensions": <number-of-dimensions>,
11 "similarity": "euclidean | cosine | dotProduct"
12 },
13 {
14 "type": "filter",
15 "path": "<field-to-index>"
16 },
17 ...
18 ]
19}

Example

Create a file named vector-index.json.

2
<name-of-database>
Database that contains the collection for which you want to create the index.
<name-of-collection>
Collection for which you want to create the index.
<index-name>
Name of your index. If you omit the index name, Atlas Vector Search names the index vector_index.
<number-of-dimensions>
Number of vector dimensions that Atlas Vector Search enforces at index-time and query-time.
<field-to-index>
Vector and filter fields to index.

Example

Copy and paste the following index definition into the vector-index.json file. The following index definition indexes the plot_embedding field as the vector type and the genres and year fields as the filter type in an Atlas Vector Search index. The plot_embedding field contains embeddings created using OpenAI's text-embedding-ada-002 embeddings model. The index definition specifies 1536 vector dimensions and measures similarity using euclidean distance.

The following index definition indexes only the vector embeddings field for performing vector search.

1{
2 "database": "sample_mflix",
3 "collectionName": "embedded_movies",
4 "type": "vectorSearch",
5 "name": "vector_index",
6 "fields": [
7 {
8 "type": "vector",
9 "path": "plot_embedding",
10 "numDimensions": 1536,
11 "similarity": "euclidean"
12 }
13 ]
14}

This index definition indexes the following fields:

  • A string field (genres) and a numeric field (year) for pre-filtering the data.

  • The vector embeddings field (plot_embedding) for performing vector search against pre-filtered data.

1{
2 "database": "sample_mflix",
3 "collectionName": "embedded_movies",
4 "type": "vectorSearch",
5 "name": "vector_index",
6 "fields":[
7 {
8 "type": "vector",
9 "path": "plot_embedding",
10 "numDimensions": 1536,
11 "similarity": "euclidean"
12 },
13 {
14 "type": "filter",
15 "path": "genres"
16 },
17 {
18 "type": "filter",
19 "path": "year"
20 }
21 ]
22}
3
atlas clusters search indexes create --clusterName [cluster_name] --file [vector_index].json

In the command, replace the following placeholder values:

  • cluster_name is the name of the Atlas cluster that contains the collection for which you want to create the index.

  • vector_index is the name of the JSON file that contains the index definition for the Atlas Vector Search index.

Example

atlas clusters search indexes create --clusterName [cluster_name] --file vector-index.json

To learn more about the command syntax and parameters, see the Atlas CLI documentation for the atlas clusters search indexes create command.

1
  1. If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it is not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. If the Clusters page is not already displayed, click Database in the sidebar.

2

You can go the Atlas Search page from the sidebar, the Data Explorer, or your cluster details page.

  1. In the sidebar, click Atlas Search under the Services heading.

  2. From the Select data source dropdown, select your cluster and click Go to Atlas Search.

  1. Click the Browse Collections button for your cluster.

  2. Expand the database and select the collection.

  3. Click the Search Indexes tab for the collection.

  1. Click the cluster's name.

  2. Click the Atlas Search tab.

3

To create, click Create Search Index.

4
Screenshot of create Atlas Vector Search index
click to enlarge
5
  1. In the Index Name field, enter a name for the index.

    Index name must be unique within the namespace, regardless of the index type.

    Example

    Enter vector_index as the name for the example index. If you already have an index named vector_index on this collection, enter a different name for the index.

  2. In the Database and Collection section, find the database, and select the collection.

    Tip

    If you navigated to this page from the Data Explorer, you can skip this step because Atlas preselects the database and collection that you selected in the Data Explorer.

    Example

    In the Database and Collection section, find the sample_mflix database, and select the embedded_movies collection.

6

An Atlas Vector Search index resembles the following example:

1{
2 "fields":[
3 {
4 "type": "vector",
5 "path": <field-to-index>,
6 "numDimensions": <number-of-dimensions>,
7 "similarity": "euclidean | cosine | dotProduct"
8 },
9 {
10 "type": "filter",
11 "path": "<field-to-index>"
12 },
13 ...
14 ]
15}

To learn more about the fields in the index, see How to Index Fields for Vector Search.

Example

The following index definition indexes the plot_embedding field as the vector type and the genres and year fields as the filter type in an Atlas Vector Search index. The plot_embedding field contains embeddings created using OpenAI's text-embedding-ada-002 embeddings model. The index definition specifies 1536 vector dimensions and measures similarity using euclidean distance.

The following index definition indexes only the vector embeddings field for performing vector search.

1{
2 "fields": [{
3 "type": "vector",
4 "path": "plot_embedding",
5 "numDimensions": 1536,
6 "similarity": "euclidean"
7 }]
8}

This index definition indexes the following fields:

  • A string field (genres) and a numeric field (year) for pre-filtering the data.

  • The vector embeddings field (plot_embedding) for performing vector search against pre-filtered data.

1{
2 "fields": [{
3 "type": "vector",
4 "path": "plot_embedding",
5 "numDimensions": 1536,
6 "similarity": "euclidean"
7 },
8 {
9 "type": "filter",
10 "path": "genres"
11 },
12 {
13 "type": "filter",
14 "path": "year"
15 }]
16}
7
8

Atlas displays a modal window to let you know your index is building.

9
10

The newly created index appears on the Atlas Search tab. While the index is building, the Status field reads Build in Progress. When the index is finished building, the Status field reads Active.

Note

Larger collections take longer to index. You will receive an email notification when your index is finished building.

To create an Atlas Vector Search index for a collection using mongosh v2.1.2 or later, perform the following steps:

1

To learn more, see Connect via mongosh.

2

Example

use sample_mflix
switched to db sample_mflix
3

The db.collection.createSearchIndex() method has the following syntax:

1db.<collectionName>.createSearchIndex(
2 "<index-name>",
3 "vectorSearch", //index type
4 {
5 fields: [
6 {
7 "type": "vector",
8 "numDimensions": <number-of-dimensions>,
9 "path": "<field-to-index>",
10 "similarity": "euclidean | cosine | dotProduct"
11 },
12 {
13 "type": "filter",
14 "path": "<field-to-index>"
15 },
16 ...
17 ]
18 }
19);

Example

The following index definition indexes the plot_embedding field as the vector type and the genres and year fields as the filter type in an Atlas Vector Search index. The plot_embedding field contains embeddings created using OpenAI's text-embedding-ada-002 embeddings model. The index definition specifies 1536 vector dimensions and measures similarity using euclidean distance.

The following index definition indexes only the vector embeddings field for performing vector search.

1db.embedded_movies.createSearchIndex(
2 "vector_index",
3 "vectorSearch",
4 {
5 "fields": [
6 {
7 "type": "vector",
8 "path": "plot_embedding",
9 "numDimensions": 1536,
10 "similarity": "euclidean"
11 }
12 ]
13 }
14);

This index definition indexes the following fields:

  • A string field (genres) and a numeric field (year) for pre-filtering the data.

  • The vector embeddings field (plot_embedding) for performing vector search against pre-filtered data.

1db.embedded_movies.createSearchIndex(
2 "vector_index",
3 "vectorSearch",
4 {
5 "fields": [
6 {
7 "type": "vector",
8 "path": "plot_embedding",
9 "numDimensions": 1536,
10 "similarity": "euclidean"
11 },
12 {
13 "type": "filter",
14 "path": "genres"
15 },
16 {
17 "type": "filter",
18 "path": "year"
19 }
20 ]
21 }
22);

To create an Atlas Vector Search index for a collection using the MongoDB Node driver v6.6.0 or later, perform the following steps:

1
1const { MongoClient } = require("mongodb");
2
3// connect to your Atlas deployment
4const uri = "<connectionString>";
5
6const client = new MongoClient(uri);
7
8async function run() {
9 try {
10 const database = client.db("<databaseName>");
11 const collection = database.collection("<collectionName>");
12
13 // define your Atlas Vector Search index
14 const index = {
15 name: "<indexName>",
16 type: "vectorSearch",
17 definition: {
18 "fields": [
19 {
20 "type": "vector",
21 "numDimensions": <numberOfDimensions>,
22 "path": "<fieldToIndex>",
23 "similarity": "euclidean | cosine | dotProduct"
24 },
25 {
26 "type": "filter",
27 "path": "<fieldToIndex>"
28 },
29 ...
30 ]
31 }
32 }
33
34 // run the helper method
35 const result = await collection.createSearchIndex(index);
36 console.log(result);
37 } finally {
38 await client.close();
39 }
40}
41run().catch(console.dir);

Example

Create a file named vector-index.js.

2
<connectionString>
Atlas connection string. To learn more, see Connect via Drivers.
<databaseName>
Database that contains the collection for which you want to create the index.
<collectionName>
Collection for which you want to create the index.
<indexName>
Name of your index. If you omit the index name, Atlas Search names the index vector_index.
<numberOfDimensions>
Number of vector dimensions that Atlas Vector Search enforces at index-time and query-time.
<fieldToIndex>
Vector and filter fields to index.

Example

Copy and paste the following into the vector-index.js file and replace the <connectionString> placeholder value. The following index definition indexes the plot_embedding field as the vector type and the genres and year fields as the filter type in an Atlas Vector Search index. The plot_embedding field contains embeddings created using OpenAI's text-embedding-ada-002 embeddings model. The index definition specifies 1536 vector dimensions and measures similarity using euclidean distance.

The following index definition indexes only the vector embeddings field (plot_embedding) for performing vector search.

1const { MongoClient } = require("mongodb");
2
3// connect to your Atlas deployment
4const uri = "<connectionString>";
5
6const client = new MongoClient(uri);
7
8async function run() {
9 try {
10 const database = client.db("sample_mflix");
11 const collection = database.collection("embedded_movies");
12
13 // define your Atlas Vector Search index
14 const index = {
15 name: "vector_index",
16 type: "vectorSearch",
17 definition: {
18 "fields": [
19 {
20 "type": "vector",
21 "numDimensions": 1536,
22 "path": "plot_embedding",
23 "similarity": "euclidean"
24 }
25 ]
26 }
27 }
28
29 // run the helper method
30 const result = await collection.createSearchIndex(index);
31 console.log(result);
32 } finally {
33 await client.close();
34 }
35}
36run().catch(console.dir);

This index definition indexes the following fields:

  • A string field (genres) and a numeric field (year) for pre-filtering the data.

  • The vector embeddings field (plot_embedding) for performing vector search against pre-filtered data.

1const { MongoClient } = require("mongodb");
2
3// connect to your Atlas deployment
4const uri = "<connectionString>";
5
6const client = new MongoClient(uri);
7
8async function run() {
9 try {
10 const database = client.db("sample_mflix");
11 const collection = database.collection("embedded_movies");
12
13 // define your Atlas Vector Search index
14 const index = {
15 name: "vector_index",
16 type: "vectorSearch",
17 definition: {
18 "fields": [
19 {
20 "type": "vector",
21 "numDimensions": 1536,
22 "path": "plot_embedding",
23 "similarity": "euclidean"
24 },
25 {
26 "type": "filter",
27 "path": "genres"
28 },
29 {
30 "type": "filter",
31 "path": "year"
32 }
33 ]
34 }
35 }
36
37 // run the helper method
38 const result = await collection.createSearchIndex(index);
39 console.log(result);
40 } finally {
41 await client.close();
42 }
43}
44run().catch(console.dir);
3
node <file-name>.js

Example

node vector_index.js

To create an Atlas Vector Search index for a collection using the PyMongo driver v4.7 or later, perform the following steps:

1
1import pymongo
2from pymongo.mongo_client import MongoClient
3from pymongo.operations import SearchIndexModel
4
5# Connect to your Atlas deployment
6uri = "<connectionString>"
7client = MongoClient(uri)
8
9# Access your database and collection
10database = client["<databaseName>"]
11collection = database["<collectionName>"]
12
13# Create your index model, then create the search index
14search_index_model = SearchIndexModel(
15 definition={
16 "fields": [
17 {
18 "type": "vector",
19 "numDimensions": <numberofDimensions>,
20 "path": "<fieldToIndex>",
21 "similarity": "euclidean | cosine | dotProduct"
22 },
23 {
24 "type": "filter",
25 "path": "<fieldToIndex>"
26 },
27 ...
28 ]
29 },
30 name="<index name>",
31 type="vectorSearch",
32)
33
34result = collection.create_search_index(model=search_index_model)
35print(result)

To learn more, see the create_search_index() method.

1from pymongo.mongo_client import MongoClient
2from pymongo.operations import SearchIndexModel
3
4def create_indexes():
5 # Connect to your Atlas deployment
6 uri = "<connectionString>"
7 client = MongoClient(uri)
8
9 # Access your database and collection
10 database = client["<databaseName>"]
11 collection = database["<collectionName>"]
12
13 # Create your index models and add them to an array
14 first_model = SearchIndexModel(
15 definition={
16 "fields": [
17 {
18 "type": "vector",
19 "numDimensions": <numberOfDimensions>,
20 "path": "<fieldToIndex>",
21 "similarity": "euclidean | cosine | dotProduct"
22 },
23 {
24 "type": "filter",
25 "path": "<fieldToIndex>"
26 },
27 ...
28 ]
29 },
30 name="<indexName>",
31 type="vectorSearch",
32 )
33
34 second_model = SearchIndexModel(
35 definition={
36 "fields": [
37 {
38 "type": "vector",
39 "numDimensions": <numberOfDimensions>,
40 "path": "<fieldToIndex>",
41 "similarity": "euclidean | cosine | dotProduct"
42 },
43 {
44 "type": "filter",
45 "path": "<fieldToIndex>"
46 },
47 ...
48 ]
49 },
50 name="<index name>",
51 type="vectorSearch",
52 )
53
54 ...
55
56 idx_models = [first_model, second_model, ...]
57
58 # Create the search indexes
59 result = collection.create_search_indexes(models=idx_models)
60 print(result)

To learn more, see the create_search_indexes() method.

Example

Create a file named vector-index.py.

2
<connectionString>
Atlas connection string. To learn more, see Connect via Drivers.
<databaseName>
Database that contains the collection for which you want to create the index.
<collectionName>
Collection for which you want to create the index.
<indexName>
Name of your index. If you omit the index name, Atlas Search names the index vector_index.
<numberOfDimensions>
Number of vector dimensions that Atlas Vector Search enforces at index-time and query-time.
<fieldToIndex>
Vector and filter fields to index.

Example

Copy and paste the following into the vector-index.py and replace the <connectionString> placeholder value. The following index definition indexes the plot_embedding field as the vector type and the genres and year fields as the filter type in an Atlas Vector Search index. The plot_embedding field contains embeddings created using OpenAI's text-embedding-ada-002 embeddings model. The index definition specifies 1536 vector dimensions and measures similarity using euclidean distance.

The following index definition indexes only the vector embeddings field (plot_embedding) for performing vector search.

1from pymongo.mongo_client import MongoClient
2from pymongo.operations import SearchIndexModel
3
4# Connect to your Atlas deployment
5uri = "<connectionString>"
6client = MongoClient(uri)
7
8# Access your database and collection
9database = client["sample_mflix"]
10collection = database["embedded_movies"]
11
12# Create your index model, then create the search index
13search_index_model = SearchIndexModel(
14 definition={
15 "fields": [
16 {
17 "type": "vector",
18 "path": "plot_embedding",
19 "numDimensions": 1536,
20 "similarity": "euclidean"
21 }
22 ]
23 },
24 name="vector_index",
25 type="vectorSearch",
26)
27
28result = collection.create_search_index(model=search_index_model)
29print(result)

This index definition indexes the following fields:

  • A string field (genres) and a numeric field (year) for pre-filtering the data.

  • The vector embeddings field (plot_embedding) for performing vector search against pre-filtered data.

1from pymongo.mongo_client import MongoClient
2from pymongo.operations import SearchIndexModel
3
4# Connect to your Atlas deployment
5uri = "<connectionString>"
6client = MongoClient(uri)
7
8# Access your database and collection
9database = client["sample_mflix"]
10collection = database["embedded_movies"]
11
12# Create your index model, then create the search index
13search_index_model = SearchIndexModel(
14 definition={
15 "fields": [
16 {
17 "type": "vector",
18 "path": "plot_embedding",
19 "numDimensions": 1536,
20 "similarity": "euclidean"
21 },
22 {
23 "type": "filter",
24 "path": "genres"
25 },
26 {
27 "type": "filter",
28 "path": "year"
29 }
30 ]
31 },
32 name="vector_index",
33 type="vectorSearch",
34)
35
36result = collection.create_search_index(model=search_index_model)
37print(result)
3
python <file-name>.py

Example

python vector-index.py

You can view Atlas Vector Search indexes for all collections from the Atlas UI, Atlas Administration API, Atlas CLI, mongosh, or a supported MongoDB Driver.

You need the Project Search Index Editor or higher role to view Atlas Vector Search indexes.

Note

You can't use the mongosh command or driver helper methods to retrieve Atlas Search indexes on M0, M2, or M5 Atlas clusters. To create and manage Atlas Search indexes using mongosh or the driver, upgrade to a dedicated cluster tier.


Use the Select your language drop-down menu to set the language of the example in this section.


To retrieve all the Atlas Vector Search indexes for a collection using the Atlas Administration API, send a GET request to the Atlas Search indexes endpoint with the name of the database and collection.

1curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
2 --header "Accept: application/json" \
3 --include \
4 --request GET "https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/clusters/{clusterName}/search/indexes/{databaseName}/{collectionName}"

To learn more about the syntax and parameters for the endpoint, see Return All Atlas Search Indexes for One Collection.

To retrieve one Atlas Vector Search index for a collection using the Atlas Administration API, send a GET request to the Atlas Search indexes endpoint with either the unique ID or name of the index (line 4) to retrieve.

1curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
2 --header "Accept: application/json" \
3 --include \
4 --request GET "https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/clusters/{clusterName}/search/indexes/{indexId} | https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/clusters/{clusterName}/search/indexes/{databaseName}/{collectionName}/{indexName|indexId}"

To learn more about the syntax and parameters for the endpoint, Get One By Name and Get One By ID.

To return Atlas Vector Search indexes for a collection using Atlas CLI, perform the following steps:

1
clusterName
The name of the Atlas cluster.
db
The name of the database on the Atlas cluster that contains your indexed collection.
collection
The name of the indexed collection in the database.
projectId
The unique identifier of the project.
2
atlas clusters search indexes list --clusterName [cluster_name] --db <db-name> --collection <collection-name>

In the command, replace the following placeholder values:

  • cluster-name - the name of the Atlas cluster that contains the indexed collection.

  • db-name - the name of the database that contains the collection for which you want to retrieve the indexes.

  • collection-name - the name of the collection for which you want to retrieve the indexes.

To learn more about the command syntax and parameters, see the Atlas CLI documentation for the atlas clusters search indexes list command.

1
  1. If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it is not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. If the Clusters page is not already displayed, click Database in the sidebar.

2

You can go the Atlas Search page from the sidebar, the Data Explorer, or your cluster details page.

  1. In the sidebar, click Atlas Search under the Services heading.

  2. From the Select data source dropdown, select your cluster and click Go to Atlas Search.

  1. Click the Browse Collections button for your cluster.

  2. Expand the database and select the collection.

  3. Click the Search Indexes tab for the collection.

  1. Click the cluster's name.

  2. Click the Atlas Search tab.

The page displays the following details for the indexes on the page:

Name
Label that identifies the index.
Index Type

Label that indicates an Atlas Search or Atlas Vector Search index. Values include:

  • search for Atlas Search indexes.

  • vectorSearch for Atlas Vector Search indexes.

Index Fields
List that contains the fields that this index indexes.
Status
Current state of the index on the primary node of the cluster. For valid values, see Index Status.
Size
Size of the index on the primary node.
Documents
Number of indexed documents out of the total number of documents in the collection.
Actions

Actions that you can take on the index. You can:

Note

You can't run queries in the Search Tester UI against indexes of the vectorSearch type. If you click the Query button, Atlas Vector Search displays a sample $vectorSearch that you can copy, modify, and run in Data Explorer and using other supported clients.

To delete an Atlas Vector Search index for a collection using mongosh, perform the following steps:

1

To learn more, see Connect via mongosh.

2
3

The db.collection.getSearchIndexes() method has the following syntax:

1db.<collectionName>.getSearchIndexes( "<index-name>" );

To delete an Atlas Vector Search index for a collection using MongoDB Node driver v6.6.0 or later, perform the following steps:

1
1const { MongoClient } = require("mongodb");
2
3// connect to your Atlas deployment
4const uri = "<connectionString>";
5
6const client = new MongoClient(uri);
7
8async function run() {
9 try {
10 const database = client.db("<databaseName>");
11 const collection = database.collection("<collectionName>");
12
13 // run the helper method
14 const result = await collection.listSearchIndexes("<indexName>").toArray();
15 console.log(result);
16 } finally {
17 await client.close();
18 }
19}
20run().catch(console.dir);
2
<connectionString>
Your Atlas connection string. To learn more, see Connect via Drivers.
<databaseName>
The database that contains the collection.
<collectionName>
The collection for which you want to retrieve the indexes.
<indexName>
The name of your index if you want to retrieve a specific index. To return all indexes on the collection, omit this value.
3
node <file-name>.js

To view Atlas Vector Search indexes for a collection using PyMongo driver v4.7 or later, perform the following steps:

1
1from pymongo.mongo_client import MongoClient
2
3# Connect to your Atlas deployment
4uri = "<connectionString>"
5client = MongoClient(uri)
6
7# Access your database and collection
8database = client["<databaseName>"]
9collection = database["<collectionName>"]
10
11# Get a list of the collection's search indexes and print them
12cursor = collection.list_search_indexes()
13for index in cursor:
14 print(index)

To learn more, see the list_search_indexes() method.

2
<connectionString>
Your Atlas connection string. To learn more, see Connect via Drivers.
<databaseName>
The name of the database that contains the collection.
<collectionName>
The name of the collection.
3
python <file-name>.py

You can change the index definition of an existing Atlas Vector Search index from the Atlas UI, Atlas Administration API, Atlas CLI, mongosh, or a supported MongoDB Driver. You can't rename an index or change the index type. If you need to change an index name or type, you must create a new index and delete the old one.

Important

After you edit an index, Atlas Vector Search rebuilds it. While the index rebuilds, you can continue to run vector search queries by using the old index definition. When the index finishes rebuilding, the old index is automatically replaced. This process follows the same process as standard Atlas Search indexes.

To learn more, see Creating and Updating an Atlas Search Index.

You must have the Project Search Index Editor or higher role to edit an Atlas Vector Search index.

Note

You can't use the mongosh command or driver helper methods to edit Atlas Search indexes on M0, M2, or M5 Atlas clusters. To create and manage Atlas Search indexes using mongosh or the driver, upgrade to a dedicated cluster tier.


Use the Select your language drop-down menu to select the client you want to use to edit your index.


To edit an Atlas Vector Search index for a collection using the Atlas Administration API, send a PATCH request to the Atlas Search indexes endpoint with either the unique ID or name of the index (line 4) to edit.

1curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest --include \
2 --header "Accept: application/json" \
3 --header "Content-Type: application/json" \
4 --request PATCH "https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/clusters/{clusterName}/search/indexes/{indexId} | https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/clusters/{clusterName}/search/indexes/{databaseName}/{collectionName}/{indexName|indexId}" \
5 --data'
6 {
7 "database": "<name-of-database>",
8 "collectionName": "<name-of-collection>",
9 "type": "vectorSearch",
10 "name": "<index-name>",
11 "definition": {
12 "fields":[
13 {
14 "type": "vector",
15 "path": <field-to-index>,
16 "numDimensions": <number-of-dimensions>,
17 "similarity": "euclidean | cosine | dotProduct"
18 },
19 {
20 "type": "filter",
21 "path": "<field-to-index>"
22 },
23 ...
24 }
25 ]
26 }'

To learn more about the syntax and parameters for the endpoints, see Update One By Name and Update One By ID.

To edit an Atlas Vector Search index for a collection using Atlas CLI, perform the following steps:

1

Your index definition should resemble the following format:

1{
2 "database": "<name-of-database>",
3 "collectionName": "<name-of-collection>",
4 "type": "vectorSearch",
5 "name": "<index-name>",
6 "fields":[
7 {
8 "type": "vector",
9 "path": "<field-to-index>",
10 "numDimensions": <number-of-dimensions>,
11 "similarity": "euclidean | cosine | dotProduct"
12 },
13 {
14 "type": "filter",
15 "path": "<field-to-index>"
16 },
17 ...
18 ]
19}
2
<name-of-database>
Database that contains the collection for which you want to create the index.
<name-of-collection>
Collection for which you want to create the index.
<index-name>
Name of your index. If you omit the index name, Atlas Vector Search names the index vector_index.
<number-of-dimensions>
Number of vector dimensions that Atlas Vector Search enforces at index-time and query-time.
<field-to-index>
Vector and filter fields to index.
3
atlas clusters search indexes update <indexId> --clusterName [cluster_name] --file [vector-_index].json

In the command, replace the following placeholder values:

  • cluster_name - the name of the Atlas cluster that contains the collection for which you want to update the index.

  • vector_index - the name of the JSON file that contains the modified index definition for the Atlas Vector Search index.

To learn more about the command syntax and parameters, see the Atlas CLI documentation for the atlas clusters search indexes update command.

1
  1. If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it is not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. If the Clusters page is not already displayed, click Database in the sidebar.

2

You can go the Atlas Search page from the sidebar, the Data Explorer, or your cluster details page.

  1. In the sidebar, click Atlas Search under the Services heading.

  2. From the Select data source dropdown, select your cluster and click Go to Atlas Search.

  1. Click the Browse Collections button for your cluster.

  2. Expand the database and select the collection.

  3. Click the Search Indexes tab for the collection.

  1. Click the cluster's name.

  2. Click the Atlas Search tab.

3
  1. Locate the vectorSearch type index to edit.

  2. Click Edit Index from the Actions dropdown for that index.

  3. Review the current configuration settings and edit them as needed.

    To learn more about the fields in an Atlas Vector Search index, see How to Index Fields for Vector Search.

  4. Click Save to apply the changes.

The index's status changes from Active to Building. In this state, you can continue to use the old index because Atlas Vector Search does not delete the old index until the updated index is ready for use. Once the status returns to Active, the modified index is ready to use.

To edit an Atlas Vector Search index for a collection using mongosh, perform the following steps:

1

To learn more, see Connect via mongosh.

2
3

The db.collection.updateSearchIndex() method has the following syntax:

1db.<collectionName>.updateSearchIndex(
2 "<index-name>",
3 {
4 fields: [
5 {
6 "type": "vector",
7 "numDimensions": <number-of-dimensions>,
8 "path": "<field-to-index>",
9 "similarity": "euclidean | cosine | dotProduct"
10 },
11 {
12 "type": "filter",
13 "path": "<field-to-index>"
14 },
15 ...
16 ]
17 }
18);

To create an Atlas Vector Search index for a collection using the MongoDB Node driver v6.6.0 or later, perform the following steps:

1
1const { MongoClient } = require("mongodb");
2
3// connect to your Atlas deployment
4const uri = "<connection-string>";
5
6const client = new MongoClient(uri);
7
8async function run() {
9 try {
10 const database = client.db("<databaseName>");
11 const collection = database.collection("<collectionName>");
12
13 // define your Atlas Search index
14 const index = {
15 name: "<indexName>",
16 type: "vectorSearch",
17 //updated search index definition
18 definition: {
19 "fields": [
20 {
21 "type": "vector",
22 "numDimensions": <numberOfDimensions>,
23 "path": "<field-to-index>",
24 "similarity": "euclidean | cosine | dotProduct"
25 },
26 {
27 "type": "filter",
28 "path": "<fieldToIndex>"
29 },
30 ...
31 ]
32 }
33 }
34
35 // run the helper method
36 await collection.updateSearchIndex("<index-name>", index);
37 } finally {
38 await client.close();
39 }
40}
41run().catch(console.dir);
2
<connectionString>
Atlas connection string. To learn more, see Connect via Drivers.
<databaseName>
Database that contains the collection for which you want to create the index.
<collectionName>
Collection for which you want to create the index.
<indexName>
Name of your index. If you omit the index name, Atlas Search names the index vector_index.
<numberOfDimensions>
Number of vector dimensions that Atlas Vector Search enforces at index-time and query-time.
<fieldToIndex>
Vector and filter fields to index.
3
node <file-name>.js

To update an Atlas Vector Search index for a collection using the PyMongo driver v4.7 or later, perform the following steps:

1
1from pymongo.mongo_client import MongoClient
2
3# Connect to your Atlas deployment
4uri = "<connectionString>"
5client = MongoClient(uri)
6
7# Access your database and collection
8database = client["<databaseName>"]
9collection = database["<collectionName>"]
10
11definition = {
12 "fields": [
13 {
14 "type": "vector",
15 "numDimensions": <numberofDimensions>,
16 "path": "<fieldToIndex>",
17 "similarity": "euclidean | cosine | dotProduct"
18 },
19 {
20 "type": "filter",
21 "path": "<fieldToIndex>"
22 },
23 ...
24 ]
25}
26
27# Update your search index
28collection.update_search_index("<indexName>", definition)

To learn more, see the update_search_index() method.

2
<connectionString>
Atlas connection string. To learn more, see Connect via Drivers.
<databaseName>
Database that contains the collection for which you want to create the index.
<collectionName>
Collection for which you want to create the index.
<indexName>
Bame of your index. If you omit the index name, Atlas Search names the index vector_index.
<numberOfDimensions>
Number of vector dimensions that Atlas Vector Search enforces at index-time and query-time.
<fieldToIndex>
Vector and filter fields to index.
3
python <file-name>.py

You can delete an Atlas Vector Search index at any time from the Atlas UI, Atlas Administration API, Atlas CLI, mongosh, or a supported MongoDB Driver.

You must have the Project Search Index Editor or higher role to delete an Atlas Vector Search index.

Note

You can't use the mongosh command or driver helper methods to delete Atlas Search indexes on M0, M2, or M5 Atlas clusters. To create and manage Atlas Search indexes using mongosh or the driver, upgrade to a dedicated cluster tier.


Use the Select your language drop-down menu to select the client you want to use to delete your index.


To delete an Atlas Vector Search index for a collection using the Atlas Administration API, send a DELETE request to the Atlas Search indexes endpoint with either the unique ID or the name of the index to delete.

1curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
2 --header "Accept: application/json" \
3 --include \
4 --request DELETE "https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/clusters/{clusterName}/search/indexes/{indexId} | https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/clusters/{clusterName}/search/indexes/{databaseName}/{collectionName}/{indexName|indexId}"

To learn more about the syntax and parameters for the endpoint, see Remove One Search Index By Name and Remove One Search Index By ID.

To delete an Atlas Vector Search index for a collection using Atlas CLI, perform the following steps:

1
<indexId>
The unique identifier of the index to delete.
<clusterName>
The name of the Atlas cluster.
<projectId>
The unique identifier of the project.
2
atlas clusters search indexes delete <indexId> [options]

In the command, replace the indexId placeholder value with the unique identifier of the index to delete.

To learn more about the command syntax and parameters, see the Atlas CLI documentation for the atlas clusters search indexes delete command.

1
  1. If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it is not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. If the Clusters page is not already displayed, click Database in the sidebar.

2

You can go the Atlas Search page from the sidebar, the Data Explorer, or your cluster details page.

  1. In the sidebar, click Atlas Search under the Services heading.

  2. From the Select data source dropdown, select your cluster and click Go to Atlas Search.

  1. Click the Browse Collections button for your cluster.

  2. Expand the database and select the collection.

  3. Click the Search Indexes tab for the collection.

  1. Click the cluster's name.

  2. Click the Atlas Search tab.

3
  1. Locate the vectorSearch type index to delete.

  2. Click Delete Index from the Actions dropdown for that index.

  3. Click Drop Index in the confirmation window.

To delete an Atlas Vector Search index for a collection using mongosh, perform the following steps:

1

To learn more, see Connect via mongosh.

2
3

The db.collection.dropSearchIndex() method has the following syntax:

1db.<collectionName>.dropSearchIndex( "<index-name>" );

To delete an Atlas Vector Search index for a collection using MongoDB Node driver v6.6.0 or later, perform the following steps:

1
1const { MongoClient } = require("mongodb");
2
3// connect to your Atlas deployment
4const uri = "<connectionString>";
5
6const client = new MongoClient(uri);
7
8async function run() {
9 try {
10 const database = client.db("<databaseName>");
11 const collection = database.collection("<collectionName>");
12
13 // run the helper method
14 await collection.dropSearchIndex("<indexName>");
15
16 } finally {
17 await client.close();
18 }
19}
20run().catch(console.dir);
2
<connectionString>
Your Atlas connection string. To learn more, see Connect via Drivers.
<databaseName>
The database that contains the collection for which you want to create the index.
<collectionName>
The collection for which you want to create the index.
<indexName>
The name of your index. If you omit the index name, Atlas Search names the index vector_index.
3
node <file-name>.js

To delete an Atlas Vector Search index for a collection using PyMongo driver v4.7 or later, perform the following steps:

1
1from pymongo.mongo_client import MongoClient
2
3# Connect to your Atlas deployment
4uri = "<connectionString>"
5client = MongoClient(uri)
6
7# Access your database and collection
8database = client["<databaseName>"]
9collection = database["<collectionName>"]
10
11# Delete your search index
12collection.drop_search_index("<indexName>")

To learn more, see the drop_search_index() method.

2
<connectionString>
Your Atlas connection string. To learn more, see Connect via Drivers.
<databaseName>
The name of the database that contains the collection.
<collectionName>
The name of the collection.
<indexName>
The name of the index to delete.
3
python <file-name>.py

When you create the Atlas Vector Search index, the Status column shows the current state of the index on the primary node of the cluster. Click the View status details link below the status to view the state of the index on all the nodes of the cluster.

When the Status column reads Active, the index is ready to use. In other states, queries against the index may return incomplete results.

Status
Description
Not Started
Atlas has not yet started building the index.
Initial Sync

Atlas is building the index or re-building the index after an edit. When the index is in this state:

  • For a new index, Atlas Vector Search doesn't serve queries until the index build is complete.

  • For an existing index, you can continue to use the old index for existing and new queries until the index rebuild is complete.

Active
Index is ready to use.
Recovering
Replication encountered an error. This state commonly occurs when the current replication point is no longer available on the mongod oplog. You can still query the existing index until it updates and its status changes to Active. Use the error in the View status details modal window to troubleshoot the issue. To learn more, see Fix Atlas Search Issues.
Failed
Atlas could not build the index. Use the error in the View status details modal window to troubleshoot the issue. To learn more, see Fix Atlas Search Issues.
Delete in Progress
Atlas is deleting the index from the cluster nodes.

While Atlas builds the index and after the build completes, the Documents column shows the percentage and number of documents indexed. The column also shows the total number of documents in the collection.

The following sections describe how to create and manage Atlas Vector Search indexes from the

Back

How to Create Vector Embeddings

Next

Create and Run Queries