Definition
New in version 7.0: (Also available starting in 6.0.7)
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 is not supported in serverless instances.
Syntax
Command syntax:
db.<collection>.aggregate( [ { $listSearchIndexes: { id: <indexId>, name: <indexName> } } ] )
Command Fields
$listSearchIndexes
takes either of the following fields:
Field | Type | Necessity | Description |
---|---|---|---|
| string | Optional | The id of the index to return information about. |
| 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 |
---|---|---|
| string | Unique identifier for the index. |
| string | Name of the index. |
| string | Status of the index. For more information, see Atlas Search Index Statuses. |
| boolean | Indicates whether the index is ready to be queried. |
| document | Describes the version of the index. |
| integer | Version number associated with the index definition. When you update an index definition, the version number increments automatically. |
| date | Time when the current index definition was created. |
| document | The most recent definition for the index. For more information, see Search Index Definition Syntax. |
| array of documents | Contains the status of the index on each search host
( |
| string | Hostname of the corresponding |
| string | Status of the index on the corresponding |
| boolean | Indicates whether the index is ready to be queried on the
corresponding |
| document | Contains status information about the active index on the
corresponding For details, see Index Status Details. |
| document | Contains status information about an index being built in the
background on the corresponding For details, see Index Status Details. |
| string | Status of the index's synonym mappings. This field only appears if the index has synonyms defined. Can be one of the following values:
The returned status is a summary of the synonym mappings on each
individual |
| array of documents | Contains the status of the index's synonym mappings on each
search host ( |
| string | Status for the corresponding synonym mapping across all
|
| boolean | Indicates whether the corresponding synonym mapping can support
queries across all |
| string | Describes an error for the synonym mapping, if applicable. Only
appears if the |
Index Status Details
The following table describes the embedded fields of the following
documents:
- statusDetail.[mongot].mainIndex
- statusDetail.[mongot].stagedIndex
The fields describe the index status on a specific mongot
.
Field | Type | Description |
---|---|---|
| string | The state of the index generation on the corresponding
|
| boolean | Indicates whether the index generation is ready to be queried on
the corresponding |
| string | The state of the index generation's synonym mappings on the
corresponding |
| document | Contains the status of the index's synonym mappings on the
corresponding For more information, see Synonym Mapping Details. |
| document | Describes the index definition version that this index generation is being built with. |
| integer | Version number that the index generation is using on the
corresponding |
| date | Time when the index definition was created. |
| document | The definition that this index is being built with. |
Synonym Mapping Details
The following table describes the embedded fields of the following objects:
statusDetail.mainIndex.synonymMappingStatusDetails.<synonymMapping>
statusDetail.stagedIndex.synonymMappingStatusDetails<synonymMapping>
Field | Type | Description |
---|---|---|
| string | Status for the synonym mapping across on the corresponding
|
| boolean | Indicates whether the synonym mapping can support queries on the
corresponding |
| string | Describes an error for the synonym mapping, if applicable. Only
appears if the |
Atlas Search Index Statuses
The status
field in the $listSearchIndexes
output can be one of the
following:
Status | Description |
---|---|
| The following scenarios can cause an index to be in the
When the index is in the
An index in the |
| The index does not exist. An index in the |
| Atlas is deleting the index. An index in the |
| The index build failed. Indexes can enter the An index in the |
| Atlas has not yet started building the index. An index in the |
| The index is ready and can support queries. An index in the |
| 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 An index in the |
Errors
Changed in version 7.1: This command throws an error when not executed on Atlas.
db.names.aggregate( [ { $listSearchIndexes: { } } ] )
MongoServerError: PlanExecutor error during aggregation :: caused by :: Search index commands are only supported with Atlas.
In previous releases, this command returns an empty result when not executed on Atlas.
Examples
These examples demonstrate how to perform the following actions:
Return All Search Indexes
The following example returns all Atlas Search indexes on the movies
collection:
db.movies.aggregate( [ { $listSearchIndexes: { } } ] )
Sample output:
[ { id: '6524096020da840844a4c4a7', name: 'default', status: 'BUILDING', queryable: true, latestDefinitionVersion: { version: 2, createdAt: ISODate("2023-10-09T14:51:57.355Z") }, latestDefinition: { mappings: { dynamic: true }, storedSource: { include: [ 'awards.text' ] } }, statusDetail: [ { hostname: 'atlas-n1cm1j-shard-00-02', status: 'BUILDING', queryable: true, mainIndex: { status: 'READY', queryable: true, definitionVersion: { version: 0, createdAt: ISODate("2023-10-09T14:08:32.000Z") }, definition: { mappings: { dynamic: true, fields: {} } } }, stagedIndex: { status: 'PENDING', queryable: false, definitionVersion: { version: 1, createdAt: ISODate("2023-10-09T14:51:29.000Z") }, definition: { mappings: { dynamic: true, fields: {} }, storedSource: true } } }, { hostname: 'atlas-n1cm1j-shard-00-01', status: 'BUILDING', queryable: true, mainIndex: { status: 'READY', queryable: true, definitionVersion: { version: 0, createdAt: ISODate("2023-10-09T14:08:32.000Z") }, definition: { mappings: { dynamic: true, fields: {} } } }, stagedIndex: { status: 'PENDING', queryable: false, definitionVersion: { version: 1, createdAt: ISODate("2023-10-09T14:51:29.000Z") }, definition: { mappings: { dynamic: true, fields: {} }, storedSource: true } } }, { hostname: 'atlas-n1cm1j-shard-00-00', status: 'BUILDING', queryable: true, mainIndex: { status: 'READY', queryable: true, definitionVersion: { version: 0, createdAt: ISODate("2023-10-09T14:08:32.000Z") }, definition: { mappings: { dynamic: true, fields: {} } } } } ] }, { id: '65240be420da840844a4d077', name: 'synonym_mappings', status: 'READY', queryable: true, latestDefinitionVersion: { version: 0, createdAt: ISODate("2023-10-09T14:19:16.305Z") }, latestDefinition: { mappings: { dynamic: true, fields: { fullplot: { type: 'string' } } }, synonyms: [ { name: 'synonym_mapping', analyzer: 'lucene.english', source: { collection: 'synonyms' } } ] }, synonymMappingStatus: 'READY', synonymMappingStatusDetail: [ { synonym_mapping: { status: 'READY', queryable: true } } ], statusDetail: [ { hostname: 'atlas-n1cm1j-shard-00-02', status: 'READY', queryable: true, mainIndex: { status: 'READY', queryable: true, definitionVersion: { version: 0, createdAt: ISODate("2023-10-09T14:19:16.000Z") }, definition: { mappings: { dynamic: true, fields: { fullplot: { type: 'string', indexOptions: 'offsets', store: true, norms: 'include' } } }, synonyms: [ { name: 'synonym_mapping', analyzer: 'lucene.english', source: { collection: 'synonyms' } } ] }, synonymMappingStatus: 'READY', synonymMappingStatusDetail: [ { synonym_mapping: { status: 'READY', queryable: true } } ] } }, { hostname: 'atlas-n1cm1j-shard-00-01', status: 'READY', queryable: true, mainIndex: { status: 'READY', queryable: true, definitionVersion: { version: 0, createdAt: ISODate("2023-10-09T14:19:16.000Z") }, definition: { mappings: { dynamic: true, fields: { fullplot: { type: 'string', indexOptions: 'offsets', store: true, norms: 'include' } } }, synonyms: [ { name: 'synonym_mapping', analyzer: 'lucene.english', source: { collection: 'synonyms' } } ] }, synonymMappingStatus: 'READY', synonymMappingStatusDetail: [ { synonym_mapping: { status: 'READY', queryable: true } } ] } }, { hostname: 'atlas-n1cm1j-shard-00-00', status: 'READY', queryable: true, mainIndex: { status: 'READY', queryable: true, definitionVersion: { version: 0, createdAt: ISODate("2023-10-09T14:19:16.000Z") }, definition: { mappings: { dynamic: true, fields: { fullplot: { type: 'string', indexOptions: 'offsets', store: true, norms: 'include' } } }, synonyms: [ { name: 'synonym_mapping', analyzer: 'lucene.english', source: { collection: 'synonyms' } } ] }, synonymMappingStatus: 'READY', synonymMappingStatusDetail: [ { synonym_mapping: { status: 'READY', queryable: true } } ] } } ] } ]
Return a Single Search Index by Name
The following example returns the index named synonym-mappings
on
the movies
collection:
db.movies.aggregate( [ { $listSearchIndexes: { name: "synonym-mappings" } } ] )
Sample output:
[ { id: '65240be420da840844a4d077', name: 'synonym_mappings', status: 'READY', queryable: true, latestDefinitionVersion: { version: 0, createdAt: ISODate("2023-10-09T14:19:16.305Z") }, latestDefinition: { mappings: { dynamic: true, fields: { fullplot: { type: 'string' } } }, synonyms: [ { name: 'synonym_mapping', analyzer: 'lucene.english', source: { collection: 'synonyms' } } ] }, synonymMappingStatus: 'READY', synonymMappingStatusDetail: [ { synonym_mapping: { status: 'READY', queryable: true } } ], statusDetail: [ { hostname: 'atlas-n1cm1j-shard-00-02', status: 'READY', queryable: true, mainIndex: { status: 'READY', queryable: true, definitionVersion: { version: 0, createdAt: ISODate("2023-10-09T14:19:16.000Z") }, definition: { mappings: { dynamic: true, fields: { fullplot: { type: 'string', indexOptions: 'offsets', store: true, norms: 'include' } } }, synonyms: [ { name: 'synonym_mapping', analyzer: 'lucene.english', source: { collection: 'synonyms' } } ] }, synonymMappingStatus: 'READY', synonymMappingStatusDetail: [ { synonym_mapping: { status: 'READY', queryable: true } } ] } }, { hostname: 'atlas-n1cm1j-shard-00-01', status: 'READY', queryable: true, mainIndex: { status: 'READY', queryable: true, definitionVersion: { version: 0, createdAt: ISODate("2023-10-09T14:19:16.000Z") }, definition: { mappings: { dynamic: true, fields: { fullplot: { type: 'string', indexOptions: 'offsets', store: true, norms: 'include' } } }, synonyms: [ { name: 'synonym_mapping', analyzer: 'lucene.english', source: { collection: 'synonyms' } } ] }, synonymMappingStatus: 'READY', synonymMappingStatusDetail: [ { synonym_mapping: { status: 'READY', queryable: true } } ] } }, { hostname: 'atlas-n1cm1j-shard-00-00', status: 'READY', queryable: true, mainIndex: { status: 'READY', queryable: true, definitionVersion: { version: 0, createdAt: ISODate("2023-10-09T14:19:16.000Z") }, definition: { mappings: { dynamic: true, fields: { fullplot: { type: 'string', indexOptions: 'offsets', store: true, norms: 'include' } } }, synonyms: [ { name: 'synonym_mapping', analyzer: 'lucene.english', source: { collection: 'synonyms' } } ] }, synonymMappingStatus: 'READY', synonymMappingStatusDetail: [ { synonym_mapping: { status: 'READY', queryable: true } } ] } } ] } ]
Return a Single Search Index by id
The following example returns the search index with the provided id
value:
db.movies.aggregate( [ { $listSearchIndexes: { id: "6524096020da840844a4c4a7" } } ] )
Sample output:
[ { id: '6524096020da840844a4c4a7', name: 'default', status: 'BUILDING', queryable: true, latestDefinitionVersion: { version: 2, createdAt: ISODate("2023-10-09T14:51:57.355Z") }, latestDefinition: { mappings: { dynamic: true }, storedSource: { include: [ 'awards.text' ] } }, statusDetail: [ { hostname: 'atlas-n1cm1j-shard-00-02', status: 'BUILDING', queryable: true, mainIndex: { status: 'READY', queryable: true, definitionVersion: { version: 0, createdAt: ISODate("2023-10-09T14:08:32.000Z") }, definition: { mappings: { dynamic: true, fields: {} } } }, stagedIndex: { status: 'PENDING', queryable: false, definitionVersion: { version: 1, createdAt: ISODate("2023-10-09T14:51:29.000Z") }, definition: { mappings: { dynamic: true, fields: {} }, storedSource: true } } }, { hostname: 'atlas-n1cm1j-shard-00-01', status: 'BUILDING', queryable: true, mainIndex: { status: 'READY', queryable: true, definitionVersion: { version: 0, createdAt: ISODate("2023-10-09T14:08:32.000Z") }, definition: { mappings: { dynamic: true, fields: {} } } }, stagedIndex: { status: 'PENDING', queryable: false, definitionVersion: { version: 1, createdAt: ISODate("2023-10-09T14:51:29.000Z") }, definition: { mappings: { dynamic: true, fields: {} }, storedSource: true } } }, { hostname: 'atlas-n1cm1j-shard-00-00', status: 'BUILDING', queryable: true, mainIndex: { status: 'READY', queryable: true, definitionVersion: { version: 0, createdAt: ISODate("2023-10-09T14:08:32.000Z") }, definition: { mappings: { dynamic: true, fields: {} } } } } ] } ]
To use the MongoDB Node.js driver to add a $listSearchIndexes
stage to
an aggregation pipeline, use the $listSearchIndexes
operator in a
pipeline object.
Note
The Node.js driver provides a helper method, listSearchIndexes(), that
performs the same operation as the $listSearchIndexes
pipeline
stage. To learn more, see the Indexes page in the
MongoDB Node.js driver documentation.
Return All Search Indexes
The following example returns all Atlas Search indexes on a collection:
const pipeline = [{ $listSearchIndexes: {} }]; const cursor = collection.aggregate(pipeline); return cursor;
Return a Single Search Index by Name
The following example returns the index named synonym-mappings
:
const pipeline = [{ $listSearchIndexes: { name: "synonym-mappings" } }]; const cursor = collection.aggregate(pipeline); return cursor;
Return a Single Search Index by id
The following example returns the search index with the provided id
value:
const pipeline = [{ $listSearchIndexes: { id: "6524096020da840844a4c4a7" } }]; const cursor = collection.aggregate(pipeline); return cursor;
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