Docs Menu
Docs Home
/
Languages
/
C++
/
C++ Driver
/
Indexes

Atlas Search Indexes

On this page

  • Overview
  • Sample Data
  • Create an Atlas Search Index
  • Create an Atlas Search Index with Static Mappings
  • Create an Atlas Search Index with Dynamic Mappings
  • Create Multiple Atlas Search Indexes
  • List Atlas Search Indexes
  • Update an Atlas Search Index
  • Remove an Atlas Search Index
  • Additional Information
  • API Documentation

Overview

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

To learn more about Atlas Search, see the Atlas Search Overview in the Atlas 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 Atlas 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 Atlas Search indexes:

  • create_one(): Creates an Atlas Search index with the specified configuration

  • create_many(): Creates multiple Atlas Search indexes with the specified configurations

  • list(): Returns a mongocxx::cursor instance that points to a list of Atlas Search indexes on the collection

  • update_one(): Updates the definition of the specified Atlas Search index

  • drop_one(): Removes the specified index from the collection

Note

Atlas Search Index Management is Asynchronous

The MongoDB C++ Driver manages Atlas Search indexes asynchronously. The library methods described in the following sections return the server response immediately, but the changes to your Atlas 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 Atlas Search index management method.

Create an Atlas Search Index

To create a single Atlas 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 an Atlas Search index, see the Review Atlas Search Index Syntax guide in the Atlas Search documentation.

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

Create an Atlas Search Index with Static Mappings

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

To create a single Atlas 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 Atlas 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 Atlas Search index to your collection.

The following example shows how to create a single Atlas 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 Atlas Search documentation.

Create an Atlas Search Index with Dynamic Mappings

Use dynamic mappings in your Atlas 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 Atlas Search documentation.

To create a single Atlas 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 Atlas Search index to your collection.

The following example shows how to to create a single Atlas 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 Atlas Search documentation.

Create Multiple Atlas Search Indexes

To create multiple Atlas 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 Atlas Search indexes that you want to create.

The following example shows how to create multiple Atlas 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 Atlas Search Indexes

To list the Atlas 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 Atlas Search indexes.

The following example prints a list of Atlas Search indexes by iterating over a cursor::iterator instance that points to the indexes from Create Multiple Atlas 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 Atlas 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 an Atlas Search Index

To update an Atlas 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 Atlas 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 an Atlas Search Index

To remove an Atlas 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 an Atlas 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 Atlas Search feature and define Atlas Search indexes, see the following Atlas Search documentation pages:

API Documentation

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

Back

Compound Indexes

Next

Aggregation