/ /

MongoDB Search Indexes

Overview

The MongoDB Search feature enables you to perform full-text searches on collections hosted on Atlas. Before you can perform MongoDB Search queries, you must create indexes that specify which fields to index and how they are indexed.

To learn more about MongoDB Search, see the MongoDB Search Overview in the MongoDB 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 Get Started with Atlas guide.

To manage MongoDB 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 Search indexes:

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

Note

MongoDB Search Index Management is Asynchronous

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

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

Create a MongoDB Search Index

To create a single MongoDB Search index on a collection, call the create_one() method on a mongocxx::search_index_view instance and pass in a mongoxcc::search_index_model instance 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 containing the mappings field, which specifies how to configure fields in your index

Tip

For a full list of fields that you can configure in a MongoDB Search index, see the Review MongoDB Search Index Syntax guide in the MongoDB Search documentation.

The following sections show how to create a single MongoDB Search index that uses static or dynamic mappings.

Create a MongoDB Search Index with Static Mappings

Use static mappings in your MongoDB Search index to specify the fields that you want to index and configure index options for individual fields.

To create a single MongoDB Search index that uses static mappings, first create a definition document containing the mappings field. In the mappings field, specify a document containing the following fields and values:

dynamic: Set to false.
fields: Document specifying the names of the fields that you want to index and their index configurations. To learn more about mappings.fields options, see the Static Mapping Example in the MongoDB Search documentation.

Then, pass a name string and the definition document into a mongocxx::search_index_model constructor to instantiate a mongocxx::search_index_model. Pass this mongocxx::search_index_model instance into the create_one() method to add the specified MongoDB Search index to your collection.

The following example shows how to create a single MongoDB Search index that uses static mappings:

// Create an index model with your index name and definition containing the fields you want to index
auto name = "myStaticIndex";
auto fields = make_document(kvp("title", make_document(kvp("type", "string"), kvp("analyzer","lucene.standard"))), kvp("year", make_document(kvp("type","number"))));
auto definition = make_document(kvp("mappings", make_document(kvp("dynamic", false), kvp("fields", fields))));
auto model = mongocxx::search_index_model(name, definition.view());
// Create the search index
auto result = siv.create_one(model);
std::cout << "New index name: " << result << std::endl;

New index name: myStaticIndex

Important

You can't index fields that contain the dollar ($) sign at the start of the field name.

To learn more about when to use static mappings, see the Static Mappings section in the MongoDB Search documentation.

Create a MongoDB Search Index with Dynamic Mappings

Use dynamic mappings in your MongoDB Search index to automatically index all fields of supported types. For a list of supported BSON data types, see the Data Types section in the MongoDB Search documentation.

To create a single MongoDB Search index that uses dynamic mappings, first create a definition document containing the mappings field. In the mappings field, specify a document containing the dynamic field with its value set to true. Then, pass a name string and the definition document into a mongocxx::search_index_model constructor to instantiate a mongocxx::search_index_model. Pass this mongocxx::search_index_model instance into the create_one() method to add the specified MongoDB Search index to your collection.

The following example shows how to to create a single MongoDB Search index that uses dynamic mappings:

// Create an index model with your index name and definition
auto name = "myDynamicIndex";
auto definition = make_document(kvp("mappings", make_document(kvp("dynamic", true))));
auto model = mongocxx::search_index_model(name, definition.view());
// Create the search index
auto result = siv.create_one(model);
std::cout << "New index name: " << result << std::endl;

New index name: myDynamicIndex

To learn more about when to use dynamic mappings, see the Dynamic Mappings section in the MongoDB Search documentation.

Create Multiple MongoDB Search Indexes

To create multiple MongoDB Search indexes, call the create_many() method on a mongocxx::search_index_view instance and pass in a vector of mongocxx::search_index_model instances specifying the MongoDB Search indexes that you want to create.

The following example shows how to create multiple MongoDB Search indexes:

// Create a vector to store Search index models
std::vector<mongocxx::search_index_model> models; 
// Add an index model with dynamic mappings to the input vector
auto name_1 = "myDynamicIndex";
auto definition_1 = make_document(kvp("mappings", make_document(kvp("dynamic", true))));
auto model_1 = mongocxx::search_index_model(name_1, definition_1.view()); 
models.push_back(model_1);
// Add an index model with static mappings to the input vector
auto name_2 = "myStaticIndex";
auto fields = make_document(kvp("title", make_document(kvp("type", "string"), kvp("analyzer","lucene.standard"))), kvp("year", make_document(kvp("type","number"))));
auto definition_2 = make_document(kvp("mappings", make_document(kvp("dynamic", false), kvp("fields", fields))));
auto model_2 = mongocxx::search_index_model(name_2, definition_2.view());
models.push_back(model_2); 
// Create the search indexes
auto result = siv.create_many(models);
// Print the search index names
std::cout << "New index names:" << std::endl;
for (const std::string& name : result) {
    std::cout << name << std::endl;
}

New index names:
myDynamicIndex
myStaticIndex

List MongoDB Search Indexes

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

The following example prints a list of MongoDB Search indexes by iterating over a cursor::iterator instance that points to the indexes from Create Multiple MongoDB Search Indexes:

auto cursor = siv.list(); 
for (mongocxx::cursor::iterator it = cursor.begin(); it != cursor.end(); ++it) {
    std::cout << bsoncxx::to_json(*it) << std::endl;
}

{ "id" : ..., "name" : "myDynamicIndex", "type" : "search", ...,
  "latestDefinition" : { "mappings" : { "dynamic" : true } }, ...}
{ "id" : ..., "name" : "myStaticIndex", "type" : "search", ...,
  "latestDefinition" : { "mappings" : { "dynamic" : false, "fields" : { "title" : { "type" : "string", "analyzer" : "lucene.standard" }, "year" : { "type" : "number" } } } }, ...}

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

The following example uses the list() method to print an index with the name myDynamicIndex:

auto cursor = siv.list("myDynamicIndex"); 
for (mongocxx::cursor::iterator it = cursor.begin(); it != cursor.end(); ++it) {
    std::cout << bsoncxx::to_json(*it) << std::endl;
}

{ "id" : ..., "name" : "myDynamicIndex", "type" : "search", ...,
  "latestDefinition" : { "mappings" : { "dynamic" : true } }, ...}

Update a MongoDB Search Index

To update a MongoDB Search index, call the update_one() method on a mongocxx::search_index_view instance 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 MongoDB Search index from Create a Search Index with Static Mappings to use a simple analyzer on the title field:

auto update_fields = make_document(kvp("title", make_document(kvp("type", "string"), kvp("analyzer","lucene.simple"))), kvp("year", make_document(kvp("type","number"))));
auto update_definition = make_document(kvp("mappings", make_document(kvp("dynamic", false), kvp("fields", update_fields))));
siv.update_one("myStaticIndex", update_definition.view());

Remove a MongoDB Search Index

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

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

siv.drop_one("myDynamicIndex");

Additional Information

To view runnable examples that demonstrate how to manage indexes, see Optimize Queries with Indexes.

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

API Documentation

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

Back

Compound Indexes

Aggregation