Docs Menu
Docs Home
/
MongoDB Atlas
/
Atlas Search
/
Create and Manage Indexes

Edit an Atlas Search Index

On this page

  • Required Access
  • Edit an Atlas Search Index

You can change the index definition of an existing Atlas Search index. You cannot rename an index; if you need to change an index's name, you must create a new index and delete the old one.

Required Access

The following table shows the modes of access each role supports.

Role
Action
Atlas UI
Atlas API
Atlas Search API
Atlas CLI

Project Data Access Read Only or higher role

To view Atlas Search analyzers and indexes.

✓

✓

Project Data Access Admin or higher role

To create and manage Atlas Search analyzers and indexes, and assign the role to your API Key.

✓

✓

✓

✓

Project Owner role

To create and assign project access to API Keys.

✓

✓

Organization Owner role

To create access list entries for your API Key and send the request from a client that appears in the access list for your API Key.

✓

✓

Project Search Index Editor

To create, view, edit, and delete Atlas Search indexes using the Atlas UI or API.

✓

✓

✓

Edit an Atlas Search Index

You can edit an Atlas Search index in the Atlas UI, or programmatically by using mongosh, the Atlas CLI, the API, or a supported MongoDB Driver in your preferred language.

Note

You can use the mongosh command or driver helper methods to edit Atlas Search indexes on all Atlas cluster tiers. For a list of supported driver versions, see MongoDB Drivers.

You must have at least the atlasAdmin role or dbAdmin access to the database that contains the indexes. To learn more, see Built-in Roles or Specific Privileges.

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

To edit an Atlas Search index through the API:

1

Send a PATCH request.

Send a PATCH request with either the unique ID or name of the Atlas Search index that you wish to modify to the search/indexes/ endpoint.

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--include \
--request PATCH "https://mongodb.prakticum-team.ru/proxy/cloud.mongodb.com/api/atlas/v2/groups/{groupId}/clusters/{clusterName}/search/indexes/{indexId}" \
--data '
  {
    "definition":
    {
      "analyzer": "lucene.<analyzer>",
      "analyzers": [
        {
          "charFilters": [ ... ],
          "name": "string",
          "tokenFilters": [ ... ],
          "tokenizer": { ... }
        }
      ],
      "mappings": {
        "dynamic": true | false,
        "fields": {
          "property1": {},
          ...
        }
      },
      "searchAnalyzer": "lucene.<analyzer>",
      "storedSource": {
        "include | exclude": [...]
      },
      "synonyms": [
        {
          "analyzer": "lucene.<analyzer>",
          "name": "string",
          "source": {
            "collection": "string"
          }
        }
      ]
    }
  }'

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

2

Review the response.

To update a search index for a cluster using the Atlas CLI, run the following command:

atlas clusters search indexes update <indexId> [options]

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

Tip

See: Related Links

1

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

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

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

  3. If it's not already displayed, click Clusters in the sidebar.

    The Clusters page displays.

2

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.

  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.

    The Atlas Search page displays.

  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.

    The Atlas Search page displays.

  1. Click the cluster's name.

  2. Click the Atlas Search tab.

    The Atlas Search page displays.

3

Click and choose one of the following from the dropdown.

  • Edit with Visual Editor for a guided experience.

  • Edit with JSON Editor to edit the raw index definition.

4

Review current configuration settings and edit them as needed.

Review the following index configuration settings:

Field Name
Description
Necessity

Index Analyzer

Specify the analyzer to use for indexing the collection data. By default, Atlas Search uses the standard analyzer ("lucene.standard").

Corresponds to the analyzer JSON setting.

Optional

Query Analyzer

Specifies the analyzer to apply to query text before searching the text. If you omit this field, the index inherits an analyzer by default in the following order:

  1. The analyzer option for this field if specified.

  2. The searchAnalyzer option for the index if specified.

  3. The analyzer option for the index if specified.

  4. The lucene.standard analyzer.

Corresponds to the searchAnalyzer JSON setting.

Optional

Dynamic Mapping

Specify dynamic or static mapping of fields. To disable dynamic mapping, set "dynamic": to Off. By default, dynamic mapping is enabled. If you disable dynamic mapping, you must specify the fields to index. To learn more about dynamic and static mappings, see Review Atlas Search Index Syntax.

Corresponds to the mappings.dynamic JSON setting.

Required

Review the following advanced configuration settings:

Field Name
Description
Necessity

Field Mappings

Required if Dynamic Mapping in the Index Configurations section is disabled.

Defining your own field mappings is recommended for advanced users only.

Specify the fields to index. To add the fields, you must do the following:

  1. Click Add Field to open the Add Field Mapping window.

  2. Specify the following information about the field:

    • Field name - Name of the field to index.

    • Data Type Configuration - Field data type. To learn more about the supported data types and their options, see Data Types.

    • Enable Dynamic Mapping - Static or dynamic mapping to use for fields of document and embeddedDocument types. If you disable dynamic mapping, the data in the field isn't automatically indexed.

  3. Click Add to add the field.

    You can, optionally, click the ellipses (...) icon for the field in the Actions column to do the following:

    • Modify the settings for the field by clicking Edit.

    • Configure additional data types for the field by clicking Add Data Type.

    • Remove the field from the index by clicking Delete.

You can define fields in the Atlas Search index definition in any order.

Corresponds to the mappings.fields JSON setting.

Conditional

Stored Source Fields

Specify the fields to store on Atlas Search. You can choose one of the following:

  • None - (Default) If selected, Atlas Search doesn't store any field.

  • All - If selected, Atlas Search stores all the fields in the documents.

  • Specified - If selected, Atlas Search stores _id and the fields you specify. You can specify the fields by doing the following:

    1. Select the field to store on Atlas Search from the dropdown in the Field Name column.

    2. Click Add to add the field to the list of fields to store.

    3. Click Add Field and repeat steps a and b for each field to add to the list.

    4. (Optional) Click one of the following:

      • Edit to select a different field.

      • Delete to remove the field from the list of fields to store.

  • All Except Specified - If selected, Atlas Search excludes specific fields from storage on Atlas Search.

    1. Select the field to exclude from the dropdown in the Field Name column.

    2. Click Add to add the field to the list of fields to exclude.

    3. Click Add Field, and repeat steps a and b for each field to exclude from the list.

    4. (Optional) Click one of the following:

      • Edit to select a different field.

      • Delete to remove the field from the list of fields to exclude.

To learn more about storing fields, see Define Stored Source Fields in Your Atlas Search Index.

Corresponds to the storedSource JSON setting.

Optional

Synonyms Mappings

Specify synonym mappings to use in your index. To learn more, see Define Synonym Mappings in Your Atlas Search Index.

To add synonym mappings, you must specify the following settings for each synonym:

  • Synonym mapping name - Label that identifies the synonym mapping to refer to at query time. You must specify a unique value. You can't specify an empty string value.

  • Synonym source collection - Label that identifies the MongoDB collection in the same database as the Atlas Search index. Documents in this collection use the format described in the Synonyms Source Collection Documents. You can also add an empty collection or load a sample collection.

  • Analyzer - Label that identifies the analyzer to use with this synonym mapping.

    You can use a synonym mapping to query only fields analyzed with the same analyzer. By default, Atlas Search uses the standard analyzer ("lucene.standard").

    You can specify any Atlas Search analyzer except the following:

Corresponds to the synonyms JSON setting.

Optional.

Index Partitions

The number of partitions to use if field objects exceed 2.1 billion.

Corresponds to the numPartitions JSON setting.

Important

The numPartitions option is available as a Preview feature.

Optional.

Review the following index configuration settings:

Field Name
Description
Necessity

analyzer

Specify the analyzer to use for indexing the collection data. By default, Atlas Search uses the standard analyzer ("lucene.standard").

Optional

searchAnalyzer

Specifies the analyzer to apply to query text before searching the text. If you omit this field, the index inherits an analyzer by default in the following order:

  1. The analyzer option for this field if specified.

  2. The searchAnalyzer option for the index if specified.

  3. The analyzer option for the index if specified.

  4. The lucene.standard analyzer.

Optional

mappings.dynamic

Specify dynamic or static mapping of fields. To disable dynamic mapping, set "dynamic": to false. By default, dynamic mapping is enabled. If you disable dynamic mapping, you must specify the fields to index. To learn more about dynamic and static mappings, see Review Atlas Search Index Syntax.

Required

Review the following advanced configuration settings:

Field Name
Description
Necessity

mappings.fields

Required if mappings.dynamic is false.

Defining your own field mappings is recommended for advanced users only.

Specify the fields that you would like to index. To learn more, see Define Field Mappings.

You can define fields in the Atlas Search index definition in any order.

Conditional

storedSource

Specify fields in the documents to store on Atlas Search. Value can be one of the following:

  • true, to store all fields

  • false, to not store any fields

  • Object that specifies the fields to include or exclude from storage

If omitted, defaults to false.

storedSource is only available on Atlas clusters running one of the following versions:

  • MongoDB 5.0.6+

  • MongoDB 6.0+

  • MongoDB 7.0+

You can store fields of all supported Data Types on Atlas Search. To learn more about the syntax and fields, see Define Stored Source Fields in Your Atlas Search Index.

Optional

synonyms

Specify synonym mappings to use in your index. To learn more, see Define Synonym Mappings in Your Atlas Search Index.

You can use a synonym mapping to query only fields analyzed with the same analyzer. By default, Atlas Search uses the standard analyzer ("lucene.standard").

Optional

numPartitions

The number of partitions to use if field objects exceed 2.1 billion. .. include:: /includes/fact-numpartitions-preview.rst

Optional.

To learn more about these index definition settings, see Review Atlas Search Index Syntax.

5

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 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 Search index through mongosh, use the db.collection.updateSearchIndex() method.

The command has the following syntax. Specify the name of the index that you want to edit and define the new index definition. This definition replaces the index's existing definition. To learn more, see Review Atlas Search Index Syntax.

db.<collection>.updateSearchIndex(
     "<index-name>",
     /* updated search index definition */
)

Example

The following command updates a search index named default from the movies collection to use static mappings:

db.movies.updateSearchIndex(
    "default",
    {
        "mappings": {
        "dynamic": false,
        "fields": {
            "<field-name>": {
                 "type": "<field-type>"
            }
        }
    }
)

Note

The db.collection.updateSearchIndex() command doesn't return an output. You can use the Atlas UI to view the index status.

To use the C Driver to edit your Atlas Search indexes, specify the updated index information in your application and call the mongoc_collection_command_simple() method.

Example

1

Create a new file named edit-index.c.

2

Copy the following code example into the file.

The following sample application specifies the updateSearchIndex command, an updated index definition, and an existing index name. Then, the application converts the command and updated index information to BSON and passes this information to the mongoc_collection_command_simple() method to edit the search index.

#include <mongoc/mongoc.h>
#include <stdlib.h>
int main (void)
{
    mongoc_client_t *client = NULL;
    mongoc_collection_t *collection = NULL;
    mongoc_database_t *database = NULL;
    bson_error_t error;
    bson_t cmd = BSON_INITIALIZER;
    bool ok = true;
    mongoc_init();
    // Connect to your Atlas deployment
    client = mongoc_client_new("<connectionString>");
    if (!client) {
        fprintf(stderr, "Failed to create a MongoDB client.\n");
        ok = false;
        goto cleanup;
    }
    // Access your database and collection
    database = mongoc_client_get_database(client, "<databaseName>");
    collection = mongoc_database_get_collection(database, "<collectionName>");
    // Specify the command and the updated index definition
    const char *cmd_str = BSON_STR({
        "updateSearchIndex" : "<collectionName>",
        "definition" : {"mappings" : {"dynamic" : true}},
        "name" : "<indexName>"
	});
    // Convert your command to BSON
    if (!bson_init_from_json(&cmd, cmd_str, -1, &error)) {
        fprintf(stderr, "Failed to parse command: %s\n", error.message);
        ok = false;
        goto cleanup;
    }
    // Update the Atlas search index by running the command
    if (!mongoc_collection_command_simple (collection, &cmd, NULL, NULL, &error)) {
        fprintf(stderr, "Failed to run updateSearchIndex: %s\n", error.message);
        ok = false;
        goto cleanup;
    }
    printf ("Index updated!\n");
cleanup:
   mongoc_collection_destroy (collection);
   mongoc_database_destroy (database);
   mongoc_client_destroy (client);
   bson_destroy (&cmd);
   mongoc_cleanup ();
   return ok ? EXIT_SUCCESS : EXIT_FAILURE;
}
3

Specify the following values and save the file.

  • Your Atlas connection string. To learn more, see Connect via Drivers.

  • The database and collection for which you want to update an index.

  • The name of the index that you want to update.

  • The fields to redefine your search index. To learn more, see Review Atlas Search Index Syntax.

4

Compile and run the file using the following commands.

gcc -o edit-index edit-index.c $(pkg-config --libs --cflags libmongoc-1.0)
./edit-index

To use the C++ Driver to edit an Atlas Search index, call the update_one() method on a search index view.

Example

1

Create a new file named edit-index.cpp.

2

Copy the following code example into the file.

The following sample application instantiates a search index view and specifies a new Atlas Search index definition. Then, the application passes this definition and an existing index name to the update_one() method, which updates the existing index to reflect the new definition document.

#include <bsoncxx/builder/basic/document.hpp>
#include <mongocxx/client.hpp>
#include <mongocxx/instance.hpp>
#include <mongocxx/search_index_view.hpp>
using namespace mongocxx;
using bsoncxx::builder::basic::make_document;
int main()
{ 
    mongocxx::instance instance{};
    try
    {
        // Connect to your Atlas deployment
        mongocxx::uri uri("<connectionString>");
        mongocxx::client client(uri); 
        // Access your database and collection
        auto db = client["<databaseName>"];
        auto collection = db["<collectionName>"];
        // Access the indexes in your collection
        auto siv = collection.search_indexes();
        // Specify a new definiton and update your search index
        auto newDefinition = make_document(kvp("mappings", make_document(kvp("dynamic", true))));
        siv.update_one("<indexName>", newDefinition.view());
        
    }
    catch (const std::exception& e) 
    {
        std::cout<< "Exception: " << e.what() << std::endl;
    }
    return 0;
}
3

Specify the following values and save the file.

  • Your Atlas connection string. To learn more, see Connect via Drivers.

  • The database and collection for which you want to update an index.

  • The name of the index that you want to update.

  • The fields to redefine your search index. To learn more, see Review Atlas Search Index Syntax.

4

Compile and run the file using the following commands.

g++ -o edit-index edit-index.cpp $(pkg-config --cflags --libs libmongocxx)
./edit-index

To use the .NET/C# Driver to edit an Atlas Search index, use the Update() or UpdateAsync() method.

Example

The following sample application updates an existing index definition. Specify the following values:

  • Your Atlas connection string. To learn more, see Connect via Drivers.

  • The database and collection where you created the search index.

  • The new index definition to replace the existing definition. In the example, you update an index to use static mappings. You can alter this definition to suit your specific indexing needs. To learn more, see Review Atlas Search Index Syntax.

  • The name of the index that you want to update.

Program.cs
using MongoDB.Bson;
using MongoDB.Driver;
// connect to your Atlas deployment
var uri = "<connection-string>";
var client = new MongoClient(uri);
var db = client.GetDatabase("<databaseName>");
var collection = db.GetCollection<BsonDocument>("<collectionName>");
// define your Atlas Search index
var index = new BsonDocument
{
  // updated search index definition
  { "mappings", new BsonDocument
    {
      { "dynamic", false },
      { "fields", new BsonDocument
        {
          { "<field-name>", new BsonDocument
            {
              { "type", "<field-type>" }
            }
          }
        }
      }
    }
  }
};
collection.SearchIndexes.Update("<index-name>", index);

To run the sample application, create a new .NET console project named csharp-update-index and copy the previous code example into the Program.cs file. Then, use the following command to run the project:

dotnet run csharp-update-index.csproj

Note

The Update() method doesn't return an output. You can use the Atlas UI to view the index status.

Tip

API Documentation

To learn more about the methods on this page, see the API documentation for the .NET/C# driver.

To edit an Atlas Search index on a collection using the Java Driver, construct a document that modifies the search index settings, and then pass the document to the updateSearchIndex() method. You must have Java Driver v4.11.0 or higher.

1

Create a new file named EditIndex.java.

2

Copy the following code example into the file.

1import com.mongodb.client.MongoClient;
2import com.mongodb.client.MongoClients;
3import com.mongodb.client.MongoCollection;
4import com.mongodb.client.MongoDatabase;
5import org.bson.Document;
6
7public class EditIndex {
8    public static void main(String[] args) {
9        // connect to your Atlas cluster
10        String uri = "<connection-string>";
11
12        try (MongoClient mongoClient = MongoClients.create(uri)) {
13            // set namespace
14            MongoDatabase database = mongoClient.getDatabase("<document-name>");
15            MongoCollection<Document> collection = database.getCollection("<collection-name>");
16            // define field mappings
17            Document index = new Document("analyzer", "<analyzer-name>").append(
18                            "mappings", new Document("dynamic", <true|false>)
19                                    .append("fields", new Document("<field-name>",
20                                           new Document("type", "<field-type>"))));
21            // run the updateSearchIndex() method
22            collection.updateSearchIndex("<index-name>", index);
23        }
24    }
25}
3

Replace the following values in the code and then save the file.

  • <connection-string> - Your Atlas connection string. To learn more, see Connect via Drivers.

    Note

    In your connection string, don't include the writeConcern setting.

  • <database-name> - The name of the database that contains the collection.

  • <collection-name> - The name of the collection for which you want to retrieve the index.

  • <analyzer-name> - The name of the analyzer.

  • dynamic - The flag that indicates whether or not to automatically index the fields.

  • <field-name> - The name of the field to index.

  • <field-type> - The field data type.

  • <index-name> - The name of the index.

4

Compile and run the file.

javac EditIndex.java
java EditIndex

The updateSearchIndex() method runs asynchronously. Use the listSearchIndexes() method to determine if the changes have been applied to your index. To learn more about retrieving Atlas Search indexes, see Procedure.

Tip

See also:

Atlas Search Indexes

To edit an Atlas Search index through the Node Driver, use the updateSearchIndex helper method.

Example

You can use the following sample application named update-index.js to update an existing index definition. Specify the following values:

  • Your Atlas connection string. To learn more, see Connect via Drivers.

  • The database and collection where you created the search index.

  • The new index definition to replace the existing definition. In the example, you update an index to use static mappings. You can alter this definition to suit your specific indexing needs. To learn more, see Review Atlas Search Index Syntax.

  • The name of the index that you want to update.

update-index.js
import { MongoClient } from "mongodb";
// connect to your Atlas deployment
const uri =  "<connection-string>";
const client = new MongoClient(uri);
async function run() {
  try {
    const database = client.db("<databaseName>");
    const collection = database.collection("<collectionName>");
    // define your Atlas Search index
    const index = {
        /* updated search index definition */
        "mappings": {
            "dynamic": false,
            "fields": {
              "<field-name>": {
                "type": "<field-type>"
              }
            }
        }
    }
    // run the helper method
    await collection.updateSearchIndex("<index-name>", index);
  } finally {
    await client.close();
  }
}
run().catch(console.dir);

To run the sample application, use the following command:

node update-index.js

Note

The updateSearchIndex method doesn't return an output. You can use the Atlas UI to view the index status.

To use the Python Driver to update your Atlas Search indexes, call the update_search_index() method on your collection.

Example

1

Create a new file named edit-index.py.

2

Copy the following code example into the file.

The following sample application specifies a new Atlas Search index definition. Then, the application passes this definition and an existing index name to the update_search_index() method, which updates the existing index to reflect the new definition document.

from pymongo.mongo_client import MongoClient
def edit_index():
    # Connect to your Atlas deployment
    uri = "<connectionString>"
    client = MongoClient(uri)
    # Access your database and collection
    database = client["<databaseName>"]
    collection = database["<collectionName>"]
    # Specify a new index definition
    definition = {
            "mappings": {
                "dynamic": True
            },
    }
    
    # Update your search index
    collection.update_search_index("<indexName>", definition)
3

Specify the following values and save the file.

  • Your Atlas connection string. To learn more, see Connect via Drivers.

  • The database and collection for which you want to update an index.

  • The name of the index that you want to update.

  • The fields to redefine your search index. To learn more, see Review Atlas Search Index Syntax.

4

Run the file using the following command.

python edit-index.py

Note

While your new index is building, different nodes may update at varying speeds. During this period, you may experience mixed query results, reflecting both the new index definition and the previous index definition. You can view the index that is serving queries in the index status details page.

Back

View

Next

Delete