How to Index Fields for Vector Search

Create a .json file and define the index in the file.

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
}

Replace the following placeholder values and save the file.

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
}

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
}

Run the following command to create the index.

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.

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.

In Atlas, go to the Clusters page for your project.

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.

Go to the Atlas Search page for your cluster.

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

Create an Atlas Vector Search index.

To create, click Create Search Index.

Select JSON Editor under Atlas Vector Search and click Next.

click to enlarge

Enter the Index Name, and set the Database and Collection.

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.

Specify an index definition.

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.

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

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
}

Click Next to review the index.

Click Create Search Index.

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

Close the You're All Set! Modal Window by clicking the Close button.

Check the status.

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.

Connect to the Atlas cluster using mongosh.

To learn more, see Connect via mongosh.

Switch to the database that contains the collection for which you want to create the index.

use sample_mflix

switched to db sample_mflix

Run the db.collection.createSearchIndex() method.

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

1
db.<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
);

1
db.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
);

1
db.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
);

Create a .js file and define the index in the file.

1
const { MongoClient } = require("mongodb");
2
3
// connect to your Atlas deployment
4
const uri =  "<connectionString>";
5
6
const client = new MongoClient(uri);
7
8
async 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
}
41
run().catch(console.dir);

Replace the following values and save the file.

1
const { MongoClient } = require("mongodb");
2
3
// connect to your Atlas deployment
4
const uri =  "<connectionString>";
5
6
const client = new MongoClient(uri);
7
8
async 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
}
36
run().catch(console.dir);

1
const { MongoClient } = require("mongodb");
2
3
// connect to your Atlas deployment
4
const uri =  "<connectionString>";
5
6
const client = new MongoClient(uri);
7
8
async 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
}
44
run().catch(console.dir);

Run the following command to create the index.

node <file-name>.js

node vector_index.js

Create a .py file and define the index in the file.

1
import pymongo
2
from pymongo.mongo_client import MongoClient
3
from pymongo.operations import SearchIndexModel
4
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 model, then create the search index
14
search_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
34
result = collection.create_search_index(model=search_index_model)
35
print(result)

1
from pymongo.mongo_client import MongoClient
2
from pymongo.operations import SearchIndexModel
3
4
def 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)

Replace the following values and save the file.

1
from pymongo.mongo_client import MongoClient
2
from pymongo.operations import SearchIndexModel
3
4
# Connect to your Atlas deployment
5
uri = "<connectionString>"
6
client = MongoClient(uri)
7
8
# Access your database and collection
9
database = client["sample_mflix"]
10
collection = database["embedded_movies"]
11
12
# Create your index model, then create the search index
13
search_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
28
result = collection.create_search_index(model=search_index_model)
29
print(result)

1
from pymongo.mongo_client import MongoClient
2
from pymongo.operations import SearchIndexModel
3
4
# Connect to your Atlas deployment
5
uri = "<connectionString>"
6
client = MongoClient(uri)
7
8
# Access your database and collection
9
database = client["sample_mflix"]
10
collection = database["embedded_movies"]
11
12
# Create your index model, then create the search index
13
search_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
36
result = collection.create_search_index(model=search_index_model)
37
print(result)

Run the following command to create the index.

python <file-name>.py

python vector-index.py

Gather the following information.

Run the following command to retrieve the indexes for the collection.

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.

In Atlas, go to the Clusters page for your project.

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.

Go to the Atlas Search page for your cluster.

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

Connect to the Atlas cluster using mongosh.

To learn more, see Connect via mongosh.

Switch to the database that contains the collection.

Run the db.collection.getSearchIndexes() method.

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

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

Create the .js file and use the listSearchIndexes() method to retrieve the index.

1
const { MongoClient } = require("mongodb");
2
3
// connect to your Atlas deployment
4
const uri =  "<connectionString>";
5
6
const client = new MongoClient(uri);
7
8
async 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
}
20
run().catch(console.dir);

Replace the following values and save the file.

Run the following command to retrieve the index.

node <file-name>.js

Create a .py file and use the list_search_indexes() method to retrieve the indexes for the collection.

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

To learn more, see the list_search_indexes() method.

Replace the following values and save the file.

Run the following command to retrieve the indexes.

python <file-name>.py

Create a .json file and define the changes to the index in the file.

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
}

Replace the following placeholder values and save the file.

Run the following command to update the index.

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.

In Atlas, go to the Clusters page for your project.

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.

Go to the Atlas Search page for your cluster.

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

Edit the index.

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.

Connect to the Atlas cluster using mongosh.

To learn more, see Connect via mongosh.

Switch to the database that contains the collection for which you want to update the index.

Run the db.collection.updateSearchIndex() method.

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

1
db.<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
);

Create the .js file and define the index changes in the file.

1
const { MongoClient } = require("mongodb");
2
3
// connect to your Atlas deployment
4
const uri =  "<connection-string>";
5
6
const client = new MongoClient(uri);
7
8
async 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
}
41
run().catch(console.dir);

Replace the following values and save the file.

Run the following command to update the index.

node <file-name>.js

Create the .py file and define the index changes in the file.

1
from pymongo.mongo_client import MongoClient
2
3
# Connect to your Atlas deployment
4
uri = "<connectionString>"
5
client = MongoClient(uri)
6
7
# Access your database and collection
8
database = client["<databaseName>"]
9
collection = database["<collectionName>"]
10
11
definition = {
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
28
collection.update_search_index("<indexName>", definition)

To learn more, see the update_search_index() method.

Replace the following values and save the file.

Run the following command to update the index.

python <file-name>.py

Gather the following information.

Run the command to delete the index.

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.

In Atlas, go to the Clusters page for your project.

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.

Go to the Atlas Search page for your cluster.

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

Delete the index.

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.

Connect to the Atlas cluster using mongosh.

To learn more, see Connect via mongosh.

Switch to the database that contains the collection.

Run the db.collection.dropSearchIndex() method.

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

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

Create the .js file and use the dropSearchIndex() method to delete the index.

1
const { MongoClient } = require("mongodb");
2
3
// connect to your Atlas deployment
4
const uri = "<connectionString>";
5
6
const client = new MongoClient(uri);
7
8
async 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
}
20
run().catch(console.dir);

Replace the following values and save the file.

Run the following command to delete the index.

node <file-name>.js

Create the .py file and use the drop_search_index() method to delete the index.

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

To learn more, see the drop_search_index() method.

Replace the following values and save the file.

Run the following command to delete the index.

python <file-name>.py