Database Manual / Reference / Query Language / Aggregation Stages

$listSearchIndexes (aggregation stage)（聚合阶段）

Definition定义

$listSearchIndexes

New in version 7.0.在版本7.0中新增。 (Also available starting in 6.0.7)

Returns information about existing MongoDB Search indexes on a specified collection or view.返回指定集合或视图上现有MongoDB搜索索引的信息。

Important

This command can only be run on a deployment hosted on MongoDB Atlas.此命令只能在MongoDB Atlas上托管的部署上运行。

Syntax语法

Command syntax:命令语法：

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

Command Fields命令字段

$listSearchIndexes takes either of the following fields:接受以下字段之一：

Field字段Type类型Necessity必要性Description描述
idstring字符串Optional可选The id of the index to return information about.要返回有关信息的索引的id。
namestring字符串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 MongoDB Search indexes on the collection.不能同时指定id和name。如果省略id和name字段，$listSearchIndexes将返回集合上所有MongoDB搜索索引的信息。

Access Control访问控制

If your deployment enforces access control, the user running $listSearchIndexes must have the listSearchIndexes privilege action on the database or collection:如果部署强制执行访问控制，则运行$listSearchIndexes的用户必须对数据库或集合具有listSearchIndexes权限操作：

{
   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:内置的read角色提供listSearchIndexes权限。以下示例授予qa数据库上的read角色：

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描述
idstring字符串Unique identifier for the index.索引的唯一标识符。
namestring字符串Name of the index.索引的名称。
statusstring字符串Status of the index. For more information, see MongoDB Search Index Statuses.索引的状态。有关更多信息，请参阅MongoDB搜索索引状态。
queryableboolean布尔值Indicates whether the index is ready to be queried.指示索引是否已准备好进行查询。
latestDefinitionVersiondocument文档Describes the version of the index.描述索引的版本。
latestDefinitionVersion.versioninteger整数Version number associated with the index definition. When you update an index definition, the version number increments automatically.与索引定义关联的版本号。更新索引定义时，版本号会自动递增。
latestDefinitionVersion.createdAtdate日期Time when the current index definition was created.创建当前索引定义的时间。
latestDefinitiondocument文档The most recent definition for the index. For more information, see Search Index Definition Syntax.指数的最新定义。有关更多信息，请参阅搜索索引定义语法。
statusDetailarray of documents文档数组Contains the status of the index on each search host (mongot).包含每个搜索主机（mongot）上的索引状态。
statusDetail.[n].hostnamestring字符串Hostname of the corresponding mongot.对应mongot的主机名。
statusDetail.[n].statusstring字符串Status of the index on the corresponding mongot.相应mongot的索引状态。
statusDetail.[n].queryableboolean布尔值Indicates whether the index is ready to be queried on the corresponding mongot.指示索引是否已准备好在相应的mongot上查询。
statusDetail.[n].mainIndexdocument文档

Contains status information about the active index on the corresponding mongot.包含有关相应mongot上活动索引的状态信息。

For details, see Index Status Details.有关详细信息，请参阅索引状态详细信息。

statusDetail.[n].stagedIndexdocument文档

Contains status information about an index being built in the background on the corresponding mongot. This field only appears if you are building a new index to update an existing active index.包含有关在相应mongot的后台构建索引的状态信息。仅当您正在构建新索引以更新现有活动索引时，才会显示此字段。

For details, see Index Status Details.有关详细信息，请参阅索引状态详细信息。

synonymMappingStatusstring字符串

Status of the index's synonym mappings. This field only appears if the index has synonyms defined. Can be one of the following values:索引同义词映射的状态。仅当索引定义了同义词时，才会显示此字段。可以是以下值之一：

  • BUILDING
  • FAILED
  • READY

The returned status is a summary of the synonym mappings on each individual mongot.返回的状态是每个mongot上同义词映射的摘要。

synonymMappingStatusDetailarray 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.包含每个搜索主机（mongot）上索引同义词映射的状态。仅当索引定义了同义词时，才会显示此字段（及其子字段）。
synonymMappingStatusDetail.[n].statusstring字符串Status for the corresponding synonym mapping across all mongot processes.所有mongot进程中对应同义词映射的状态。
synonymMappingStatusDetail.[n].queryableboolean布尔值Indicates whether the corresponding synonym mapping can support queries across all mongot processes.指示相应的同义词映射是否可以支持跨所有mongot进程的查询。
messagestring字符串Describes an error for the synonym mapping, if applicable. Only appears if the status for this synonym mapping is FAILED.描述同义词映射的错误（如果适用）。仅当此同义词映射的status为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.这些字段描述了特定mongot的索引状态。

Field字段Type类型Description描述
statusstring字符串The state of the index generation on the corresponding mongot.索引生成的状态对应于mongot。
queryableboolean布尔值Indicates whether the index generation is ready to be queried on the corresponding mongot.指示是否已准备好在相应的mongot上查询索引生成。
synonymMappingStatusstring字符串The state of the index generation's synonym mappings on the corresponding mongot. Only present if the index has synonyms defined.索引生成在相应mongot上的同义词映射的状态。仅当索引定义了同义词时才显示。
synonymMappingStatusDetailsdocument文档

Contains the status of the index's synonym mappings on the corresponding mongot. This field (and its subfields) only appear if the index has synonyms defined.包含索引在相应mongot上的同义词映射的状态。仅当索引定义了同义词时，才会显示此字段（及其子字段）。

For more information, see Synonym Mapping Details.有关更多信息，请参阅同义词映射详细信息。

definitionVersiondocument文档Describes the index definition version that this index generation is being built with.描述用于生成此索引的索引定义版本。
definitionVersion.versioninteger整数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.索引生成在相应mongot上使用的版本号。更新索引定义时，更新的索引将使用递增的版本号构建。
definitionVersion.createdAtdateTime when the index definition was created.创建索引定义的时间。
definitiondocument文档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描述
statusstring字符串Status for the synonym mapping across on the corresponding mongot process.对应mongot进程上同义词映射的状态。
queryableboolean布尔值Indicates whether the synonym mapping can support queries on the corresponding mongot process.指示同义词映射是否可以支持对相应mongot进程的查询。
messagestring字符串Describes an error for the synonym mapping, if applicable. Only appears if the status for this synonym mapping is FAILED.描述同义词映射的错误（如果适用）。仅当此同义词映射的status为FAILED（失败）时才会显示。

MongoDB Search Index StatusesMongoDB搜索索引状态

The status field in the $listSearchIndexes output can be one of the following:$listSearchIndexes输出中的status字段可以是以下之一：

StatusDescription描述
BUILDING

The following scenarios can cause an index to be in the BUILDING state:以下情况可能会导致索引处于BUILDING状态：

  • MongoDB is building the index or re-building the index after an edit.MongoDB正在构建索引或在编辑后重新构建索引。
  • MongoDB Search cannot keep up with indexing changes to the collection. In this case, Atlas rebuilds the index in the background.MongoDB搜索无法跟上对集合的索引更改。在这种情况下，Atlas会在后台重建索引。

When the index is in the BUILDING state:当索引处于BUILDING状态时：

  • For a new index, MongoDB Search cannot use the index for queries until the index build is complete.对于新索引，MongoDB搜索在索引构建完成之前无法使用该索引进行查询。
  • For an existing index, MongoDB Search uses the old index definition for queries until the index rebuild is complete.对于现有索引，MongoDB搜索将使用旧的索引定义进行查询，直到索引重建完成。

An index in the BUILDING state may be queryable or non-queryable.处于BUILDING状态的索引可以是可查询的或不可查询的。

DOES_NOT_EXIST

The index does not exist.索引不存在。

An index in the DOES_NOT_EXIST state is always non-queryable.处于DOES_NOT_EXIST状态的索引始终是不可查询的。

DELETING

MongoDB is deleting the index.MongoDB正在删除索引。

An index in the DELETING state is always non-queryable.处于DELETING状态的索引始终是不可查询的。

FAILED

The index build failed. Indexes can enter the FAILED state due to an invalid index definition.索引构建失败。由于索引定义无效，索引可能会进入FAILED状态。

An index in the FAILED state may be queryable or non-queryable.处于FAILED状态的索引可以是可查询的或不可查询的。

PENDING

MongoDB has not yet started building the index.MongoDB尚未开始构建索引。

An index in the PENDING state is always non-queryable.处于PENDING状态的索引始终是不可查询的。

READY

The index is ready and can support queries.索引已准备就绪，可以支持查询。

An index in the READY state is always queryable.处于READY状态的索引始终是可查询的。

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.由于复制错误，索引可能会进入STALE状态。

An index in the STALE state is always queryable.处于STALE状态的索引始终是可查询的。

Errors错误

Changed in version 7.1.在版本7.1中的更改。 This command throws an error when not executed on Atlas.此命令在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.在以前的版本中，此命令在Atlas上不执行时返回空结果。

Examples示例

MongoDB Shell

These examples demonstrate how to perform the following actions:这些示例演示了如何执行以下操作：

Return All Search Indexes返回所有搜索索引

The following example returns all MongoDB Search indexes on the movies collection:以下示例返回movies集合上的所有MongoDB搜索索引：

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:以下示例返回movies集合上名为synonym-mappings（同义词映射）的索引：

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按id返回单个搜索索引

The following example returns the search index with the provided id value:以下示例返回具有提供的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: {} } }
        }
      }
    ]
  }
]
Node.js

To use the MongoDB Node.js driver to add a $listSearchIndexes stage to an aggregation pipeline, use the $listSearchIndexes operator in a pipeline object.要使用MongoDB Node.js驱动程序将$listSearchIndexes阶段添加到聚合管道中，请在管道对象中使用$listSearchIndexes运算符。

Note

The Node.js driver provides a helper method, listSearchIndexes(), that performs the same operation as the $listSearchIndexes pipeline stage. Node.js驱动程序提供了一个辅助方法listSearchIndexes()，它执行与$listSearchIndexs管道阶段相同的操作。To learn more, see the Indexes page in the MongoDB Node.js driver documentation.要了解更多信息，请参阅MongoDB Node.js驱动程序文档中的索引页面。

Return All Search Indexes返回所有搜索索引

The following example returns all MongoDB Search indexes on a collection:以下示例返回集合上的所有MongoDB搜索索引：

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:以下示例返回名为synonym-mappings（同义词映射）的索引：

const pipeline = [{ $listSearchIndexes: { name: "synonym-mappings" } }];

const cursor = collection.aggregate(pipeline);
return cursor;

Return a Single Search Index by id按id返回单个搜索索引

The following example returns the search index with the provided id value:以下示例返回具有提供的id值的搜索索引：

const pipeline = [{ $listSearchIndexes: { id: "6524096020da840844a4c4a7" } }];

const cursor = collection.aggregate(pipeline);
return cursor;

Learn More了解更多

To use a mongosh method to view MongoDB Search indexes, see db.collection.getSearchIndexes().要使用mongosh方法查看MongoDB搜索索引，请参阅db.collection.getSearchIndexes()。

To create MongoDB Search indexes, see:要创建MongoDB搜索索引，请参阅：