View an Atlas Search Index
Important
You can view an Atlas Search index definition in the Index Overview page. For each index, the Index Overview page shows the following:
Namespace for the index.
Index and search analyzers specified in the index definition.
Dynamic or static mapping.
Field mappings in the index definition, if any, including field name, data type, and whether dynamic mapping is enabled for the individual field.
This page describes how to view your index definition in the Index Overview page. You can also Edit an Atlas Search Index with the visual or JSON editor in the Index Overview page.
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 | ✓ | ✓ | |||
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. | ✓ | ✓ | ||
To create, view, edit, and delete Atlas Search indexes using the
Atlas UI or API. | ✓ | ✓ | ✓ |
Procedure
You can retrieve your Atlas Search indexes 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 retrieve
Atlas Search indexes on all Atlas cluster tiers. For a list of supported driver
versions, see MongoDB Drivers.
You must have at least the
readAnyDatabase
role or read
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 retrieve an Atlas Search index through the API:
Send a GET
request.
Send a GET
request with either the unique ID or name of
the Atlas Search index that you wish to retrieve to the search/indexes/
endpoint.
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --header "Accept: application/json" \ --include \ --request GET "https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/clusters/{clusterName}/search/indexes/{indexId}"
To learn more about the syntax and parameters for either endpoint, see Get One By Name and Get One By ID.
To retrieve all Atlas Search indexes for a collection:
Send a GET
request.
Send a GET
request to the search/indexes/
endpoint with the
name of the collection whose indexes you want to retrieve.
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --header "Accept: application/json" \ --include \ --request GET "https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/clusters/{clusterName}/search/indexes/{databaseName}/{collectionName}"
To retrieve all Atlas Search indexes for a cluster:
Send a GET
request.
Send a GET
request to the search/indexes/
endpoint
with the name of the cluster whose indexes you want to
retrieve.
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --header "Accept: application/json" \ --include \ --request GET "https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/clusters/{clusterName}/search/indexes"
Retrieve Atlas Search Indexes for a Cloud Deployment
To list all search indexes for a cluster using the Atlas CLI, run the following command:
atlas clusters search indexes list [options]
To return the details for the search index you specify using the Atlas CLI, run the following command:
atlas clusters search indexes describe <indexId> [options]
To learn more about the syntax and parameters for the previous commands, see the Atlas CLI documentation for atlas clusters search indexes list and atlas clusters search indexes describe.
Retrieve Atlas Search Indexes for a Local Deployment
To describe the specified search index for the specified deployment using the Atlas CLI, run the following command:
atlas deployments search indexes describe [indexId] [options]
To list all search indexes for the specified deployment using the Atlas CLI, run the following command:
atlas deployments search indexes list [options]
To learn more about the syntax and parameters for the previous commands, see the Atlas CLI documentation for atlas deployments search indexes describe and atlas deployments search indexes list.
In Atlas, go to the Clusters page for your project.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
If it's not already displayed, click Clusters in the sidebar.
The Clusters page displays.
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.
The Atlas Search page displays.
Click the Browse Collections button for your cluster.
Expand the database and select the collection.
Click the Search Indexes tab for the collection.
The Atlas Search page displays.
Click the cluster's name.
Click the Atlas Search tab.
The Atlas Search page displays.
To retrieve your Atlas Search indexes through mongosh
, use
the db.collection.getSearchIndexes()
method.
The command has the following syntax. If you omit the index name, Atlas Search returns all indexes on the collection.
db.<collection>.getSearchIndexes("<index-name>")
Example
The following command retrieves a search
index named default
from the movies
collection.
Your results should resemble the example output:
db.movies.getSearchIndexes("default")
[ { id: '648b4ad4d697b73bf9d2e5e0', name: 'default', status: 'READY', queryable: true, latestDefinition: { mappings: { dynamic: true } } } ]
To use the C Driver to retrieve your Atlas Search indexes, use
the mongoc_collection_aggregate()
method to create an aggregation pipeline
that includes the $listSearchIndexes
stage.
Example
Copy the following code example into the file.
The following sample application specifies the $listSearchIndexes
stage
in an aggregation pipeline. Then, the application passes the pipeline and the
target collection to the mongoc_collection_aggregate()
method. This method
returns a cursor from which the code accesses and prints each Atlas Search index:
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; bson_t pipeline = BSON_INITIALIZER; mongoc_cursor_t *cursor = NULL; 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>"); // Create an aggregation pipeline with the $listSearchIndexes stage const char *pipeline_str = BSON_STR ({"pipeline" : [ {"$listSearchIndexes" : {}} ]}); // Convert your aggregation pipeline to BSON if (!bson_init_from_json(&pipeline, pipeline_str, -1, &error)) { fprintf(stderr, "Failed to parse command: %s\n", error.message); ok = false; goto cleanup; } // Run the aggregation operation and iterate through the indexes returned cursor = mongoc_collection_aggregate (collection, MONGOC_QUERY_NONE, &pipeline, NULL, NULL); const bson_t *got; char *str; while (mongoc_cursor_next (cursor, &got)) { str = bson_as_canonical_extended_json (got, NULL); printf ("%s\n", str); bson_free (str); } if (mongoc_cursor_error (cursor, &error)) { fprintf (stderr, "Failed to iterate all documents: %s\n", error.message); ok = false; goto cleanup; } cleanup: mongoc_cursor_destroy(cursor); mongoc_collection_destroy(collection); mongoc_database_destroy(database); mongoc_client_destroy(client); bson_destroy(&pipeline); 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 retrieve the indexes.
To use the C++ Driver to retrieve your Atlas Search indexes, call
the list()
method on a search index view.
Example
Copy the following code example into the file.
The following sample application uses the search_indexes()
method
on the target collection to instantiate a search index view. Then, the
application calls the list()
method on the view. This method returns
a cursor from which the code accesses and prints each Atlas Search index.
using namespace mongocxx; 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 and print the indexes in your collection auto siv = collection.search_indexes(); auto cursor = siv.list(); for (auto&& doc : cursor) { std::cout << bsoncxx::to_json(doc) << std::endl; }; } 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 retrieve the indexes.
To use the .NET/C# Driver to retrieve your Atlas Search indexes,
use the List()
or ListAsync()
method.
Example
The following sample application returns the indexes on a collection. Specify the following values:
Your Atlas connection string. To learn more, see Connect via Drivers.
The database and collection that contains the search indexes that you want to retrieve.
Note
The List()
method returns a cursor instead of the indexes themselves.
To access the indexes, use a cursor paradigm such
as the MoveNext()
method.
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>"); // list your Atlas Search indexes var result = collection.SearchIndexes.List().ToList(); foreach (var index in result) { Console.WriteLine(index); }
To run the sample application, create a new .NET console project named
csharp-list-indexes
and copy the previous code example into the
Program.cs
file. Then, use the following command to run the project:
dotnet run csharp-list-indexes.csproj
<indexes for this collection>
Tip
API Documentation
To learn more about the methods on this page, see the API documentation for the .NET/C# driver.
To retrieve Atlas Search indexes on a collection using the Java
Driver,
use the listSearchIndexes()
method. You must have
Java Driver v4.11.0 or higher.
Copy the following code example into the file.
The following sample application retrieves all Atlas Search indexes on a given collection.
1 import com.mongodb.client.MongoClient; 2 import com.mongodb.client.MongoClients; 3 import com.mongodb.client.MongoCollection; 4 import com.mongodb.client.MongoCursor; 5 import com.mongodb.client.MongoDatabase; 6 import org.bson.Document; 7 public class ViewIndex { 8 public static void main(String[] args) { 9 // connect to your Atlas cluster 10 String uri = "<connection-string>"; 11 try (MongoClient mongoClient = MongoClients.create(uri)) { 12 // set namespace 13 MongoDatabase database = mongoClient.getDatabase("<database-name>"); 14 MongoCollection<Document> collection = database.getCollection("<collection-name>"); 15 // retrieve indexes 16 try (MongoCursor<Document> resultsCursor = collection.listSearchIndexes().iterator()) { 17 while (resultsCursor.hasNext()) { 18 System.out.println(resultsCursor.next()); 19 } 20 } 21 } 22 } 23 }
Replace the following values and then save the file.
<connection-string>
- Your Atlas connection string. To learn more, see Connect via Drivers.<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.
To retrieve your Atlas Search indexes through the Node Driver,
use the listSearchIndexes
helper method.
Example
You can use the following sample application named list-indexes.js
to return the indexes on your collection. Specify the following values:
Your Atlas connection string. To learn more, see Connect via Drivers.
The database and collection that contains the search indexes that you want to retrieve.
The index name if you want to retrieve a specific index. To return all indexes on the collection, omit this value.
Note
The listSearchIndexes
command returns a cursor. As a result,
it doesn't immediately return the indexes matched by the command.
To access the results, use a cursor paradigm such
as the toArray()
method. To learn more, see Access Data From a Cursor.
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>"); // run the helper method const result = await collection.listSearchIndexes("<index-name>").toArray(); console.log(result); } finally { await client.close(); } } run().catch(console.dir);
To run the sample application, use the following command. Your results should resemble the example output:
node list-indexes.js
[ { id: '648b4ad4d697b73bf9d2e5e0', name: 'default', status: 'READY', queryable: true, latestDefinition: { mappings: { dynamic: true } } }, { id: '648b4ad4d697b73bf9d2e5e1', name: 'example-index', status: 'PENDING', queryable: false, latestDefinition: { mappings: { dynamic: false, fields: { text: { type: 'string' } } } } } ]
To use the Python Driver to retrieve your Atlas Search
indexes, call the list_search_indexes()
method on your collection.
Example
Copy the following code example into the file.
The following sample application calls the list_search_indexes()
method
on a collection. This method returns a cursor from which the code accesses
and prints each Atlas Search index:
from pymongo.mongo_client import MongoClient def view_index(): # Connect to your Atlas deployment uri = "<connectionString>" client = MongoClient(uri) # Access your database and collection database = client["<databaseName>"] collection = database["<collectionName>"] # Get a list of the collection's search indexes and print them cursor = collection.list_search_indexes() for index in cursor: print(index)
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 retrieve the indexes.
Search Indexes
In the Atlas UI, the Atlas Search page displays information about Atlas Search indexes for the collections. The page displays the following details for each index on the cluster.
Column | Description |
---|---|
Database | Name of the database that contains the collection. |
Collection | Name of the indexed collection. |
Index Name | Name of the index. |
Type | Type of index. Value can be one of the following types of index:
|
Index Fields | Indexed fields. Value is dynamic if you enabled dynamic
mappings. For static mappings, the column shows all of the indexed
fields. |
Status | Status of the index. To learn more, see Atlas Search Index Statuses. |
Queryable | Icon that identifies whether collection is queryable using the index. Value can be one of the following icons:
|
Size | Size of the index. |
Documents | Approximate number and percentage of indexed documents out of the
total number of documents in the collection during and after the
index build on the primary or search node on the cluster. |
Actions | Actions you can take on the index:
|
You can sort the indexes by the various columns. By default, Atlas
sorts the indexes by first the database name and then the collection
name. To sort by multiple columns, press Shift
and click the
column names in the order in which you want to multi-sort the list of
indexes. Atlas doesn't save your preferred sorting order when you
leave the page.
Review Index Statuses
For each index, the Status column shows the current state of the index on the primary node of the cluster. The following table describes the index statuses.
Status | Description |
---|---|
Pending | Atlas has not yet started building the index. |
Building | Atlas is building the index or re-building the index after an edit. When the index is in this state:
|
Ready | Index is ready to use. |
Stale | Index is stale because of any of the following reasons:
You can still query the existing index. However, the results for queries against a stale index might contain stale data. You can upscale your search nodes for more disk space and delete existing indexes to release disk space. Alternatively, use the error in the View status details modal window to troubleshoot the issue. To learn more, see Fix Atlas Search Issues. |
Failed | Atlas could not build the index. Use the error
in the View status details modal window to
troubleshoot the issue. To learn more, see
Fix Atlas Search Issues. |
Deleting | Atlas is deleting the index from the cluster nodes. |
Does not Exist | Index is invalid because the collection for the index no longer
exists. You can't run queries on this index because there is no
corresponding collection for this index. Atlas will
eventually delete the index. |
View Status Details
The Status column shows the current state of the index on the primary node of the cluster. You can view detailed status in one of the following ways:
Click the View status details link below the status in the Status column.
Click the name of the index and then select Status Details from the menu on the left for the index.
On this page, you can view the following details about the index:
Index Serving Queries
This section displays the index that is being used to serve queries. If you have only one version of the index with this name for the collection, the section contains a link to the Index Overview where you can see the index definition for the index being used.
If you had other indexes with the same name on the collection, the section shows the latest index definition and also shows prior valid versions of the index that you can copy in different tabs.
When you update an index, different nodes apply the updates at different speeds. Therefore, some nodes might use the latest version and some might use the prior version. Atlas displays both versions of the index until the changes are applied to all the nodes.
If you attempt to update the index with an invalid index definition, the index build will fail and Atlas displays only the previous valid index definition.
Status Details by Node
This section displays the status of the index on each node of the cluster. You can see the following details about the index on each node:
Shard | Shard name. |
Node | Node information. |
Status | Status of the index on the node in the shard. |
Queryable | Icon that indicates whether the index can serve queries. |
Message | Reason for the index status. For indexes in Stale or
Failed state, displays the reason why the index is stale or
why the index build failed. |
Node Type | Type of node. Value can be one of the following types:
|
Region | Node region. |
Size | Size of the index on the node. |
Documents | Number and percentage of indexed documents. |
Actions | Actions you can take on the index in the node. You can click the and select one of the following options:
|
Warning
If you shard a collection that already has an Atlas Search index, you might experience a brief period of query downtime when the collection begins to appear on a shard. Also, if you add a shard for an already sharded collection that contains an Atlas Search index, your search queries against that collection will fail until the initial sync process completes on the added shards. To learn more, see initial sync process.
Migration to Search Nodes
This section displays the status of the in-progress migration of your Atlas Search and Atlas Vector Search indexes to search nodes, if applicable. This is only visible if you are currently migrating to search nodes.
Click the View Migration Progress link in the information banner under the Index Status by Search Node section for details on the progress of the migration of the indexes to Search Nodes (on a per node basis).
The Atlas UI displays the following columns for each index on the cluster.
Column | Description |
---|---|
Database | Name of the database that contains the collection. |
Collection | Name of the indexed collection. |
Index Name | Name of the index. |
Index Fields | Indexed fields. Value is dynamic if you enabled dynamic
mappings. For static mappings, the column shows all of the indexed
fields. |
Type | Type of index. Value can be one of the following types of index:
|
Status | Status of the migration. To learn more, see
Migration to Search Nodes. |
Size | Size of the index. |
Documents | Number and percentage of indexed documents out of the total
number of documents in the collection during and after the
migration on the search nodes on the cluster. |
The status column displays the status of the index on the Search Nodes. The status can be one of the following:
Status | Description |
---|---|
Building | The index is currently building on the Search Node. Your queries
can continue to use existing indexes while the new index is
building. |
On Deck | The index is successfully built on the Search Nodes, but the
migration is not yet complete. Note that migration is complete
only when Atlas successfully builds all the indexes on the
Search Nodes. |
Ready | The index on the Search Node is ready for use in your queries.
This displays only when Atlas successfully completes the
migration to the Search Nodes. |
Failed | The index build failed and the migration to separate Search Nodes is stalled. Your queries can continue to use the existing indexes. Atlas will try to rebuild the index, but will timeout after 7 days. To migrate successfully, review error message for the index in the Status Details by Node Message column or in the Status Details page for the index and address issues that are causing the index build to fail on the Search Nodes. |
Your queries can continue to use existing indexes while the new indexes are building on the Search Nodes. The migration to the Search Nodes completes only when Atlas successfully builds all the indexes on the Search Nodes. Then, your queries will be automatically routed to the use the indexes on the Search Nodes.