Docs Menu

Docs HomeMongoDB Manual

$listSearchIndexes (aggregation)

On this page

  • Definition
  • Syntax
  • Command Fields
  • Access Control
  • Output
  • Atlas Search Index Statuses
  • Examples
  • Return All Search Indexes
  • Return a Single Search Index by Name
  • Return a Single Search Index by id
  • Learn More
$listSearchIndexes

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.

Command syntax:

db.<collection>.aggregate(
[
{
$listSearchIndexes:
{
id: <indexId>,
name: <indexName>
}
}
]
)

$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.

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

$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.

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 BUILDING state:

  • Atlas is building the index or re-building the index after an edit.

  • Atlas Search cannot keep up with indexing changes to the collection. In this case, Atlas rebuilds the index in the background.

When the index is in the BUILDING state:

  • For a new index, Atlas Search cannot use the index for queries until the index build is complete.

  • For an existing index, Atlas Search uses the old index definition for queries until the index rebuild is complete.

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 STALE state due to replication errors.

These examples demonstrate how to:

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 the READY state.

  • frenchIndex01 is in the PENDING state.

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 } }
}
]

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'
}
}
}
}
}
]

To use a mongosh method to view Atlas Search indexes, see db.collection.getSearchIndexes().

To create Atlas Search indexes, see:

←  $listSampledQueries$listSessions →
Share Feedback
© 2023 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2023 MongoDB, Inc.