Docs Menu
Docs Home
/
MongoDB Atlas
/ /

View an Atlas Search Index

On this page

  • Required Access
  • Procedure
  • Search Indexes
  • Review Index Statuses
  • View Status Details

Important

If you use the $out aggregation stage to modify a collection with an Atlas Search index, you must delete and re-create the search index. If possible, consider using $merge instead of $out.

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.

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

Role
Action
Atlas UI
Atlas API
Atlas Search API
Atlas CLI
To view Atlas Search analyzers and indexes.
✓
✓
To create and manage Atlas Search analyzers and indexes, and assign the role to your API Key.
✓
✓
✓
✓
✓
✓
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.
✓
✓
✓

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:

1

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.

2

To retrieve all Atlas Search indexes for a collection:

1

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}"
2

To retrieve all Atlas Search indexes for a cluster:

1

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"
2

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.

Tip

See: Related Links

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.

1
  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

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

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>")

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.

1
2

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:

#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;
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;
}
3
  • Your Atlas connection string. To learn more, see Connect via Drivers.

  • The database and collection for which you want to retrieve the indexes.

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

To use the C++ Driver to retrieve your Atlas Search indexes, call the list() method on a search index view.

1
2

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.

#include <bsoncxx/json.hpp>
#include <mongocxx/client.hpp>
#include <mongocxx/instance.hpp>
#include <mongocxx/search_index_view.hpp>
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;
}
3
  • Your Atlas connection string. To learn more, see Connect via Drivers.

  • The database and collection for which you want to retrieve the indexes.

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

To use the .NET/C# Driver to retrieve your Atlas Search indexes, use the List() or ListAsync() method.

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.

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>");
// 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>

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.

1
2

The following sample application retrieves all Atlas Search indexes on a given collection.

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

4
javac ViewIndex.java
java ViewIndex

To retrieve your Atlas Search indexes through the Node Driver, use the listSearchIndexes helper method.

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.

list-indexes.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>");
// 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.

1
2

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)
3
  • Your Atlas connection string. To learn more, see Connect via Drivers.

  • The database and collection for which you want to retrieve the indexes.

4
python view-index.py

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:

  • - for indexes that you can use to query the collection.

  • X - for indexes that you can't use to query the collection.

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:

  • Click Query to go to the Search Tester for querying the collection.

  • Click and select one of the following actions to 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.

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:

  • For a new index, Atlas Search doesn't serve queries until the index build is complete.

  • For an existing index, you can continue to use the old index for existing and new queries until the index rebuild is complete.

Ready
Index is ready to use.
Stale

Index is stale because of any of the following reasons:

  • Replication stopped due to high disk utilization.

    The pause replication threshold is 90% and the resume replication threshold is 85% disk utilization.

  • If replication stops for a long period, the Atlas Search mongot process falls off the oplog.

    This state commonly occurs when the current replication point is no longer available on the mongod oplog. Atlas rebuilds index if the mongot process falls of the oplog.

  • Index reached the two billion document limit.

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.

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:

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.

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:

  • Primary

  • Secondary

  • Search Node

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.

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.

Back

Resume or Delete a Draft