列表搜索索引（聚合）

在本页

定义

语法
命令字段
访问控制
输出
索引状态详细信息
同义词映射详细信息
Atlas 搜索索引状态
错误
示例
返回所有搜索索引
按名称返回单个搜索索引
按 id 返回单个搜索索引
了解更多

定义

$listSearchIndexes

新版本7.0: (从 6.0.7 版本开始可用)

返回有关现有Atlas 搜索索引在指定集合上的信息。

重要

此命令只能在托管在 MongoDB Atlas 上的部署上运行，并且在无服务器实例上不支持。

语法

命令语法

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

命令字段

$listSearchIndexes 可以使用以下任一字段

字段	类型	必需性	描述
`id`	字符串	可选	要返回信息索引的id。
`name`	字符串	可选	要返回信息索引的名称。

您不能同时指定 id 和 name。如果省略了 id 和 name 字段，$listSearchIndexes 将返回集合上所有 Atlas Search 索引的信息。

访问控制

如果您的部署实施访问控制，运行 $listSearchIndexes 的用户必须具有listSearchIndexes 权限操作用于数据库或集合

{
   resource: {
      db : <database>,
      collection: <collection>
   },
   actions: [ "listSearchIndexes" ]
}

内置的 read 角色提供了 listSearchIndexes 权限。以下示例在 qa 数据库上授予了 read 角色权限

db.grantRolesToUser(
   "<user>",
   [ { role: "read", db: "qa" } ]
)

输出

$listSearchIndexes 返回一个文档数组。数组中的每个文档包含以下字段

字段	类型	描述
`id`	字符串	索引的唯一标识符。
`name`	字符串	索引的名称。
`状态`	字符串	索引的状态。有关更多信息，请参阅 Atlas Search Index Statuses。
`可查询`	布尔值	指示索引是否已准备好进行查询。
`最新定义版本`	文档	描述索引的版本。
`最新定义版本.version`	整数	与索引定义关联的版本号。当您更新索引定义时，版本号会自动递增。
`最新定义版本.createdAt`	日期	当前索引定义创建的时间。
`最新定义`	文档	索引的最新定义。有关更多信息，请参阅 Search Index Definition Syntax.
`状态详情`	文档数组	包含每个搜索主机（`mongot`）上索引的状态。
`状态详情.[n].hostname`	字符串	对应 `mongot` 的主机名。
`状态详情.[n].status`	字符串	对应 `mongot` 上索引的状态。
`状态详情.[n].queryable`	布尔值	指示索引是否已准备好在对应 `mongot` 上进行查询。
`状态详情.[n].mainIndex`	文档	包含对应 `mongot` 上活动索引的状态信息。有关详细信息，请参阅 Index Status Details。
`状态详情.[n].stagedIndex`	文档	包含对应 `mongot` 上正在后台构建的索引的状态信息。此字段仅在您构建新索引以更新现有活动索引时出现。有关详细信息，请参阅 Index Status Details。
`同义词映射状态`	字符串	索引的同义词映射的状态。此字段仅在索引定义了同义词时出现。可以是以下值之一 `BUILDING` `FAILED` `READY` 返回的状态是每个单独 `mongot` 上同义词映射的摘要。
`同义词映射状态详情`	文档数组	包含每个搜索主机（`mongot`）上索引同义词映射的状态。只有当索引定义了同义词时，此字段（及其子字段）才会出现。
`synonymMappingStatusDetail.[n].status`	字符串	所有 `mongot` 进程中对应同义词映射的状态。
`synonymMappingStatusDetail.[n].queryable`	布尔值	指示对应同义词映射是否支持所有 `mongot` 进程的查询。
`message`	字符串	描述同义词映射的错误，如果有的话。只有当此同义词映射的 `status` 为 `FAILED` 时才会出现。

索引状态详情

以下表格描述了以下文档的嵌入字段：- statusDetail.[mongot].mainIndex - statusDetail.[mongot].stagedIndex

描述特定 mongot 上索引的状态的字段。

字段	类型	描述
`状态`	字符串	对应 `mongot` 上索引生成状态。
`可查询`	布尔值	指示索引生成是否在对应 `mongot` 上准备好进行查询。
`同义词映射状态`	字符串	对应 `mongot` 上索引生成同义词映射的状态。只有当索引定义了同义词时才会出现。
`synonymMappingStatusDetails`	文档	包含索引同义词映射的状态。只有当索引定义了同义词时，此字段（及其子字段）才会出现。有关更多信息，请参阅同义词映射详情。
`definitionVersion`	文档	描述此索引生成正在使用的索引定义版本。
`definitionVersion.version`	整数	在对应 `mongot` 上，索引生成正在使用的版本号。当您更新索引定义时，更新的索引将使用递增的版本号构建。
`definitionVersion.createdAt`	日期	索引定义创建的时间。
`definition`	文档	此索引正在使用的定义。

同义词映射详情

以下表格描述了以下对象的嵌入字段

状态详情的主索引的同义词映射状态详情.
状态详情的预建立索引的同义词映射状态详情

字段	类型	描述
`状态`	字符串	对应 `mongot` 进程上的同义词映射状态。
`可查询`	布尔值	指示同义词映射是否支持对应 `mongot` 进程上的查询。
`message`	字符串	描述同义词映射的错误，如果有的话。只有当此同义词映射的 `status` 为 `FAILED` 时才会出现。

Atlas 搜索索引状态

在 $listSearchIndexes 输出的 status 字段可以是以下之一

状态	描述
`BUILDING`	以下情况可能导致索引处于 `BUILDING` 状态 Atlas 正在建立索引或在编辑后重新建立索引。 Atlas 搜索无法跟上集合的索引更改。在这种情况下，Atlas 在后台重新建立索引。当索引处于 `BUILDING` 状态时对于新索引，Atlas 搜索在索引构建完成之前无法使用索引进行查询。对于现有索引，Atlas 搜索在索引重建完成之前使用旧索引定义进行查询。处于 `BUILDING` 状态的索引可能是可查询的或不可查询的。
`DOES_NOT_EXIST`	索引不存在。处于 `DOES_NOT_EXIST` 状态的索引始终不可查询。
`DELETING`	Atlas 正在删除索引。处于 `DELETING` 状态的索引始终不可查询。
`FAILED`	索引构建失败。索引可以进入 `FAILED` 状态，因为索引定义无效。处于 `FAILED` 状态的索引可能是可查询的或不可查询的。
`PENDING`	Atlas 尚未开始建立索引。处于 `PENDING` 状态的索引始终不可查询。
`READY`	索引已准备就绪，可以支持查询。处于 `READY` 状态的索引始终可查询。
`STALE`	索引可查询，但已停止从索引的集合中复制数据。对索引的搜索可能返回过时数据。索引可以因为复制错误而进入 `STALE` 状态。处于 `STALE` 状态的索引始终可查询。

错误

已更改版本7.1: 当不在 Atlas 上执行此命令时，会抛出错误。

db.names.aggregate( [
   { $listSearchIndexes: { } }
] )

MongoServerError: PlanExecutor error during aggregation :: caused by :: Search index commands are only supported with Atlas.

在以前的版本中，当不在 Atlas 上执行此命令时，会返回空结果。

示例

以下示例演示了如何

返回所有搜索索引
按名称返回单个搜索索引
按 id 返回单个搜索索引

返回所有搜索索引

以下示例返回 movies 集合上的所有 Atlas 搜索索引

db.movies.aggregate(
   [
      {
         $listSearchIndexes: { }
      }
   ]
)

示例输出

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

按名称返回单个搜索索引

以下示例返回 movies 集合上名为 synonym-mappings 的索引

db.movies.aggregate(
   [
      {
         $listSearchIndexes:
            {
               name: "synonym-mappings"
            }
      }
   ]
)

示例输出

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

通过id返回单个搜索索引

以下示例返回提供的 id 的搜索索引

db.movies.aggregate(
   [
      {
         $listSearchIndexes:
            {
               id: "6524096020da840844a4c4a7"
            }
      }
   ]
)

示例输出

[
  {
    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: {} } }
        }
      }
    ]
  }
]

了解更多

要使用 mongosh 方法查看Atlas Search索引，请参阅 db.collection.getSearchIndexes().

要创建Atlas Search索引，请参阅

db.collection.createSearchIndex() mongosh 方法
createSearchIndexes 数据库命令

$listSampledQueries

下一步

$listSessions