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't use the mongosh command or driver helper methods to edit Atlas Search indexes on M0, M2, or M5 Atlas clusters. To create and manage Atlas Search indexes using mongosh or the driver, upgrade to a dedicated cluster tier.

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:

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://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.

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

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

If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
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.

In the sidebar, click Atlas Search under the Services heading.
From the Select data source dropdown, select your cluster and click Go to Atlas Search.

Click the Browse Collections button for your cluster.
Expand the database and select the collection.
Click the Search Indexes tab for the collection.

Click the cluster's name.
Click the Atlas Search tab.

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.

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: The `analyzer` option for this field if specified. The `searchAnalyzer` option for the index if specified. The `analyzer` option for the index if specified. 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. Note 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: Click Add Field to open the Add Field Mapping window. 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. 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. Note Unlike compound indexes, the order of fields in the Atlas Search index definition is not important. Fields can be defined 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: Select the field to store on Atlas Search from the dropdown in the Field Name column. Click Add to add the field to the list of fields to store. Click Add Field and repeat steps a and b for each field to add to the list. (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. Select the field to exclude from the dropdown in the Field Name column. Click Add to add the field to the list of fields to exclude. Click Add Field, and repeat steps a and b for each field to exclude from the list. (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. Note 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: Language analyzers: `lucene.kuromoji` `lucene.cjk` Custom analyzer tokenizers: nGram Tokenizer edgeGram Tokenizer Custom analyzer token filters: daitchMokotoffSoundex Token Filter nGram Token Filter edgeGram Token Filter shingle Token Filter Corresponds to the `synonyms` JSON setting.	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: The `analyzer` option for this field if specified. The `searchAnalyzer` option for the index if specified. The `analyzer` option for the index if specified. 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`. Note 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. Note Unlike compound indexes, the order of fields in the Atlas Search index definition is not important. Fields can be defined in any order.	Conditional
`storedSource`	Note `storedSource` is only available on Atlas clusters running one of the following versions: MongoDB 5.0.6+ MongoDB 6.0+ MongoDB 7.0+ 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`. To learn more about the syntax and fields, see Define Stored Source Fields in Your Atlas Search Index. Note You can store fields of all supported Data Types on Atlas Search.	Optional
`synonyms`	Specify synonym mappings to use in your index. To learn more, see Define Synonym Mappings in Your Atlas Search Index. Note 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

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

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

Create a new file named `edit-index.c`.

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;
}

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.

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

Create a new file named `edit-index.cpp`.

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;
}

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.

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.

Create a new file named `EditIndex.java`.

Copy the following code example into the file.

1 import com.mongodb.client.MongoClient;
2 import com.mongodb.client.MongoClients;
3 import com.mongodb.client.MongoCollection;
4 import com.mongodb.client.MongoDatabase;
5 import org.bson.Document;
6 
7 public 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 }

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.

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 View an Atlas Search Index.

Tip

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

Create a new file named `edit-index.py`.

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)

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.

Run the file using the following command.

python edit-index.py

Back

View

Delete

1	import com.mongodb.client.MongoClient;
2	import com.mongodb.client.MongoClients;
3	import com.mongodb.client.MongoCollection;
4	import com.mongodb.client.MongoDatabase;
5	import org.bson.Document;
6
7	public 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	}

Edit an Atlas Search Index.leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-1l4s55v{margin-top:-175px;position:absolute;padding-bottom:2px;}

Required Access

Edit an Atlas Search Index

Note

Send a PATCH request.

Review the response.

Tip

See: Related Links

In Atlas, go to the .css-h15tq0{font-style:normal;font-weight:700;}Clusters page for your project.

Go to the Atlas Search page for your cluster.

Click and choose one of the following from the dropdown.

Review current configuration settings and edit them as needed.

Note

Note

Note

Note

Note

Note

Note

Note

Click Save to apply the changes.

Example

Note

Example

Create a new file named edit-index.c.

Copy the following code example into the file.

Specify the following values and save the file.

Compile and run the file using the following commands.

Example

Create a new file named edit-index.cpp.

Copy the following code example into the file.

Specify the following values and save the file.

Compile and run the file using the following commands.

Example

Note

Tip

API Documentation

Create a new file named EditIndex.java.

Copy the following code example into the file.

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

Note

Compile and run the file.

Tip

See also:

Example

Note

Example

Create a new file named edit-index.py.

Copy the following code example into the file.

Specify the following values and save the file.

Run the file using the following command.

Edit an Atlas Search Index

Send a `PATCH` request.

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

Create a new file named `edit-index.c`.

Create a new file named `edit-index.cpp`.

Create a new file named `EditIndex.java`.

Create a new file named `edit-index.py`.