Docs Home → MongoDB Manual

db.collection.getSearchIndexes()

On this page本页内容

Definition

db.collection.getSearchIndexes()

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:

FieldTypeNecessityDescription
indexNamestringOptionalName 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:

FieldTypeDescription
idstringUnique identifier for the Atlas Search index.
namestringName of the Atlas Search index.
statusstringStatus of the Atlas Search index. For more information, see Atlas Search Index Statuses.
queryablebooleanIndicates whether the index is ready to be queried.
latestDefinitiondocumentThe 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:

StatusDescription
BUILDINGThe 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.
FAILEDThe index build failed. Indexes can enter the FAILED state due to an invalid index definition.
PENDINGAtlas has not yet started building the index.
READYThe index is ready and can support queries.
STALEThe 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.

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 the READY state.
  • frenchIndex01 is in the PENDING 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 } }
  }
]