db.collection.getSearchIndexes()
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.
Important
mongosh Method
This page documents a mongosh
method. This is not
the documentation for a language-specific driver, such as Node.js.
For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.
Syntax
Command syntax:
db.<collection>.getSearchIndexes(<indexName>)
Command Fields
getSearchIndexes()
takes this field:
Field | Type | Necessity | Description |
---|---|---|---|
indexName | string | Optional | Name of the index to return information about. If you omit the
indexName field, getSearchIndexes() returns information
about all Atlas Search indexes on the collection. |
Access Control
If your deployment enforces access control, the user running
getSearchIndexes()
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
getSearchIndexes()
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 getSearchIndexes()
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.getSearchIndexes()
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
The following example returns the searchIndex01
index on the
movies
collection:
db.movies.getSearchIndexes("searchIndex01")
Sample output:
[ { id: '648cb60e06f6780ba87a9913', name: 'searchIndex01', status: 'READY', queryable: true, latestDefinition: { mappings: { dynamic: true } } } ]