$listSearchIndexes (aggregation)
On this page
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 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 index. |
name | string | Name of the index. |
status | string | Status of the index. For more information, see Atlas Search Index Statuses. |
queryable | boolean | Indicates whether the index is ready to be queried. |
latestDefinitionVersion | document | Describes the version of the index. |
latestDefinitionVersion.version | integer | Version number associated with the index definition. When you
update an index definition, the version number increments
automatically. |
latestDefinitionVersion.createdAt | date | Time when the current index definition was created. |
latestDefinition | document | The most recent definition for the index. For more information,
see Search Index Definition Syntax. |
statusDetail | array of documents | Contains the status of the index on each search host
( mongot ). |
statusDetail.[n].hostname | string | Hostname of the corresponding mongot . |
statusDetail.[n].status | string | Status of the index on the corresponding mongot . |
statusDetail.[n].queryable | boolean | Indicates whether the index is ready to be queried on the
corresponding mongot . |
statusDetail.[n].mainIndex | document | Contains status information about the active index on the
corresponding For details, see Index Status Details. |
statusDetail.[n].stagedIndex | document | Contains status information about an index being built in the
background on the corresponding For details, see Index Status Details. |
synonymMappingStatus | 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 |
synonymMappingStatusDetail | array of documents | Contains the status of the index's synonym mappings on each
search host ( mongot ). This field (and its subfields) only
appear if the index has synonyms defined. |
synonymMappingStatusDetail.[n].status | string | Status for the corresponding synonym mapping across all
mongot processes. |
synonymMappingStatusDetail.[n].queryable | boolean | Indicates whether the corresponding synonym mapping can support
queries across all mongot processes. |
message | string | Describes an error for the synonym mapping, if applicable. Only
appears if the status for this synonym mapping is FAILED . |
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 |
---|---|---|
status | string | The state of the index generation on the corresponding
mongot . |
queryable | boolean | Indicates whether the index generation is ready to be queried on
the corresponding mongot . |
synonymMappingStatus | string | The state of the index generation's synonym mappings on the
corresponding mongot . Only present if the index has synonyms
defined. |
synonymMappingStatusDetails | document | Contains the status of the index's synonym mappings on the
corresponding For more information, see Synonym Mapping Details. |
definitionVersion | document | Describes the index definition version that this index generation
is being built with. |
definitionVersion.version | integer | Version number that the index generation is using on the
corresponding mongot . When you update an index definition,
the updated index builds with an incremented version number. |
definitionVersion.createdAt | date | Time when the index definition was created. |
definition | 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 |
---|---|---|
status | string | Status for the synonym mapping across on the corresponding
mongot process. |
queryable | boolean | Indicates whether the synonym mapping can support queries on the
corresponding mongot process. |
message | string | Describes an error for the synonym mapping, if applicable. Only
appears if the status for this synonym mapping is FAILED . |
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
An index in the |
DOES_NOT_EXIST | The index does not exist. An index in the |
DELETING | Atlas is deleting the index. An index in the |
FAILED | The index build failed. Indexes can enter the An index in the |
PENDING | Atlas has not yet started building the index. An index in the |
READY | The index is ready and can support queries. An index in the |
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 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:
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
:
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: {} } } } } ] } ]
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