/ /

MongoDB Vector Search Indexes

Overview

MongoDB Vector Search enables you to perform semantic searches on vector embeddings stored in MongoDB Atlas. Before you can perform MongoDB Vector Search queries, you must create indexes that specify which fields to index and how they are indexed.

To learn more about MongoDB Vector Search, see the MongoDB Vector Search Overview in the MongoDB Vector Search documentation.

Sample Data

The examples in this guide use the movies collection in the sample_mflix database from the Atlas sample datasets. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the MongoDB Get Started guide.

To manage MongoDB Vector Search indexes on the sample_mflix collection from your C++ application, first instantiate a mongocxx::client that connects to an Atlas cluster and assign the following values to your db and collection variables:

auto db = client["sample_mflix"];
auto collection = db["movies"];

Then, call the search_indexes() method on your collection variable to instantiate a mongocxx::search_index_view on your collection:

auto siv = collection.search_indexes();

The mongocxx::search_index_view class contains the following member functions that allow you to interact with MongoDB Vector Search indexes:

create_one(): Creates a MongoDB Vector Search index with the specified configuration
list(): Returns a mongocxx::cursor object that points to a list of MongoDB Vector Search and Search indexes on the collection
update_one(): Updates the definition of the specified MongoDB Vector Search index
drop_one(): Removes the specified index from the collection

The following sections provide code examples that demonstrate how to use each MongoDB Vector Search index management method.

Note

MongoDB Vector Search Index Management is Asynchronous

The MongoDB C++ Driver manages MongoDB Vector Search indexes asynchronously. The library methods described in the following sections return the server response immediately, but the changes to your MongoDB Vector Search indexes take place in the background and might not complete until some time later.

Create a MongoDB Vector Search Index

To create a single MongoDB Vector Search index on a collection, call the create_one() method on a mongocxx::search_index_view object and pass in a mongocxx::search_index_model object specifying the index that you want to create.

The mongocxx::search_index_model constructor requires the following arguments:

name: String specifying the name for your index
definition: Document specifying how to configure fields in your index

Tip

For a full list of fields that you can configure in a MongoDB Vector Search index, see the MongoDB Vector Search Index Fields reference section in the MongoDB Vector Search documentation.

The following example shows how to to create a single MongoDB Vector Search index:

// Define the index model with an index name and a definition document
auto model = mongocxx::search_index_model(
  "<vectorSearchIndexName>",
  make_document(
      kvp("fields",
          make_array(make_document(
              kvp("type", "vector"),
              kvp("path", "<fieldName>"),
              kvp("numDimensions", 2048),
              kvp("similarity", "dotProduct"),
              kvp("quantization", "scalar"))))));
model.type("vectorSearch");
// Creates the vector search index
auto result = siv.create_one(model);
std::cout << "New vector search index name: " << result << std::endl;

New vector search index name: vector_search

The vector search index has the following definition:

type: The type of the index is vectorSearch.
path: The index is on the plot_embedding_voyage_3_large field.
numDimensions: The number of dimensions in the vector embeddings is 2048.
similarity: The index measures similarity using dotProduct similarity.
quantization: The index uses scalar quantization.

List MongoDB Vector Search Indexes

To list all search indexes on a collection, call the list() method on a mongocxx::search_index_view object. This method returns a mongocxx::cursor object that you can use to iterate over the collection's MongoDB Vector Search and MongoDB Search indexes.

The following example prints a list of available search indexes on the specified collection:

auto cursor = siv.list(); 
for (auto const& doc : siv.list()) {
    std::cout << bsoncxx::to_json(doc) << std::endl;
}

{ "id" : ..., "name" : "vector_index", "type" : "vectorSearch", ...,
  "latestDefinition" : {  "fields" : [ { "type" : "vector", "path" : "plot_embedding_voyage_3_large", "numDimensions" : 2048, ...}

Alternatively, you can list an individual MongoDB Vector Search index by passing an index name into the list() method. This returns a mongocxx::cursor object that points to a result set containing only the specified index.

The following example uses the list() method to return the index with the name vector_index:

for (auto const& doc : siv.list("vector_index")) {
    std::cout << bsoncxx::to_json(doc) << std::endl;
}

{ "id" : ..., "name" : "vector_index", "type" : "vectorSearch", ...,
  "latestDefinition" : {  "fields" : [ { "type" : "vector", "path" : "plot_embedding_voyage_3_large", "numDimensions" : 2048, ...}

Update a MongoDB Vector Search Index

To update a MongoDB Vector Search index, call the update_one() method on a mongocxx::search_index_view object and pass in the name of the index that you want to update and the definition to update the index to.

The following example shows how to update the existing MongoDB Vector Search index from the previous Create a MongoDB Vector Search Index example to use euclidean instead of dotProduct similarity and binary instead of scalar quantization:

auto definition = make_document(
  kvp("fields",
      make_array(make_document(
          kvp("type", "vector"), kvp("path", "plot_embedding_voyage_3_large"),
          kvp("numDimensions", 2048), kvp("similarity", "euclidean"), 
          kvp("quantization", "binary")))));
siv.update_one("vector_index", definition.view());

Remove a MongoDB Vector Search Index

To remove a MongoDB Vector Search index from a collection, call the drop_one() method on a mongocxx::search_index_view object and pass in the name of the index that you want to remove.

The following example shows how to remove a MongoDB Vector Search index named vector_index:

siv.drop_one("vector_index");

Additional Information

For a sample application that demonstrate how to manage indexes in the C++ driver, see the Indexes guide.

For more detailed guides about how to use the MongoDB Vector Search feature and define MongoDB Vector Search indexes, see the following MongoDB Vector Search documentation pages:

API Documentation

To learn more about the methods discussed in this guide, see the following API documentation:

Back

MongoDB Search Indexes

Run a Database Command