$listSearchIndexes (aggregation)
On this page
Definition
Returns information about existing Atlas Search indexes on a specified collection.
Important
This command can only be run on a deployment hosted on MongoDB Atlas, and requires an Atlas cluster tier of at least M10.
Syntax
Command syntax:
db.<collection>.aggregate( [ { $listSearchIndexes: { id: <indexId>, name: <indexName> } } ] )
Command Fields
$listSearchIndexes
takes either of the following fields:
Field | Type | Necessity | Description |
---|---|---|---|
id | string | Optional | The id of the index to return information about. |
name | string | Optional | The name of the index to return information about. |
You cannot specify both id
and name
. If you omit both the id
and name
fields, $listSearchIndexes
returns information about
all Atlas Search indexes on the collection.
Access Control
If your deployment enforces access control, the user running
$listSearchIndexes
must have the listSearchIndexes
privilege
action on the database or collection:
{ resource: { db : <database>, collection: <collection> }, actions: [ "listSearchIndexes" ] }
The built-in read
role provides the the
listSearchIndexes
privilege. The following example grants the
read
role on the qa
database:
db.grantRolesToUser( "<user>", [ { role: "read", db: "qa" } ] )
Output
$listSearchIndexes
returns an array of documents. Each document in the array
contains the following fields:
Field | Type | Description |
---|---|---|
id | string | Unique identifier for the Atlas Search index. |
name | string | Name of the Atlas Search index. |
status | string | Status of the Atlas Search index. For more information, see
Atlas Search Index Statuses. |
queryable | boolean | Indicates whether the index is ready to be queried. |
latestDefinition | document | The most recent index definition set for this index. For more
information, see Search Index Definition Syntax. |
Atlas Search Index Statuses
The status
field in the $listSearchIndexes
output can be one of the
following:
Status | Description |
---|---|
BUILDING | The following scenarios can cause an index to be in the
When the index is in the
|
FAILED | The index build failed. Indexes can enter the FAILED state
due to an invalid index definition. |
PENDING | Atlas has not yet started building the index. |
READY | The index is ready and can support queries. |
STALE | The index is queryable but has stopped replicating data from the indexed collection. Searches on the index may return out-of-date data. Indexes can enter the |
Examples
These examples demonstrate how to:
Return All Search Indexes
The following example returns all Atlas Search indexes on the movies
collection:
db.movies.aggregate( [ { $listSearchIndexes: { } } ] )
Sample output:
[ { id: '648b5397d8261c7d7d6f720e', name: 'searchIndex01', status: 'READY', queryable: true, latestDefinition: { mappings: { dynamic: true } } }, { id: '648b6110912df5513228465f', name: 'frenchIndex01', status: 'PENDING', queryable: false, latestDefinition: { mappings: { fields: { subject: { fields: { fr: { analyzer: 'lucene.french', type: 'string' } }, type: 'document' } } } } } ]
The movies
collection contains two indexes:
searchIndex01
is in theREADY
state.frenchIndex01
is in thePENDING
state.
Return a Single Search Index by Name
The following example returns the searchIndex01
index on the
movies
collection:
db.movies.aggregate( [ { $listSearchIndexes: { name: "searchIndex01" } } ] )
Sample output:
[ { id: '648cb60e06f6780ba87a9913', name: 'searchIndex01', status: 'READY', queryable: true, latestDefinition: { mappings: { dynamic: true } } } ]
Return a Single Search Index by id
The following example returns the frenchIndex01
index based on the
index id:
db.movies.aggregate( [ { $listSearchIndexes: { id: "648b6110912df5513228465f" } } ] )
Sample output:
[ { id: '648b6110912df5513228465f', name: 'frenchIndex01', status: 'PENDING', queryable: true, latestDefinition: { mappings: { fields: { subject: { fields: { fr: { analyzer: 'lucene.french', type: 'string' } }, type: 'document' } } } } } ]
Learn More
To use a mongosh
method to view Atlas Search indexes, see
db.collection.getSearchIndexes()
.
To create Atlas Search indexes, see:
The
db.collection.createSearchIndex()
mongosh
methodThe
createSearchIndexes
database command