Docs 菜单

Docs 主页 → 开发应用程序 → MongoDB Manual

$listSearchIndexes（聚合）

在此页面上

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

定义

$listSearchIndexes

7.0 版本中的新增功能：（也可从 6.0.7 开始使用）

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

重要

此命令只能在MongoDB Atlas上托管的部署上运行，并且需要至少为 M 10的 Atlas 集群层。

语法

命令语法：

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

命令字段

$listSearchIndexes 采用以下任一字段：

字段
类型
必要性
说明
id
字符串
Optional
要返回信息的索引的 ID。
name
字符串
Optional
要返回其相关信息的索引的名称。

您不能同时指定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
字符串
索引的名称。
status
字符串
索引的状态。有关更多信息，请参阅Atlas Search 索引状态。
queryable
布尔
指示索引是否已准备好接受查询。
latestDefinitionVersion
文档
描述索引的版本。
latestDefinitionVersion.version
整型
与索引定义关联的版本号。更新索引定义时，版本号会自动递增。
latestDefinitionVersion.createdAt
日期
当前索引定义的创建时间。
latestDefinition
文档
索引的最新定义。有关详细信息，请参阅搜索索引定义语法。
statusDetail
文档数组
包含每个搜索主机 ( mongot ) 上的索引状态。
statusDetail.[n].hostname
字符串
相应mongot的主机名。
statusDetail.[n].status
字符串
相应mongot上的索引状态。
statusDetail.[n].queryable
布尔
指示索引是否准备好在相应的mongot上进行查询。
statusDetail.[n].mainIndex
文档

包含相应mongot上活动索引的状态信息。

有关详细信息，请参阅索引状态详细信息。

statusDetail.[n].stagedIndex
文档

包含有关在相应mongot上后台构建的索引的状态信息。仅当您正在构建新索引以更新现有的活动索引时，才会显示此字段。

有关详细信息，请参阅索引状态详细信息。

synonymMappingStatus
字符串

索引同义词映射的状态。仅当索引定义了同义词时才会显示此字段。可以是以下值之一：

  • BUILDING

  • FAILED

  • READY

返回的状态是每个mongot上同义词映射的摘要。

synonymMappingStatusDetail
文档数组
包含每个搜索主机 ( mongot ) 上索引同义词映射的状态。仅当索引定义了同义词时，才会显示此字段（及其子字段）。
synonymMappingStatusDetail.[n].status
字符串
所有mongot进程的相应同义词映射状态。
synonymMappingStatusDetail.[n].queryable
布尔
指示相应的同义词映射是否可以支持跨所有mongot进程的查询。
message
字符串
描述同义词映射错误（如果适用）。仅当此同义词映射的status为FAILED时才会出现。

索引状态详细信息

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

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

字段
类型
说明
status
字符串
相应mongot上的索引生成状态。
queryable
布尔
指示索引生成是否已准备好在相应的mongot上进行查询。
synonymMappingStatus
字符串
相应mongot上索引生成的同义词映射的状态。仅当索引定义了同义词时才出现。
synonymMappingStatusDetails
文档

包含相应mongot上索引同义词映射的状态。仅当索引定义了同义词时，才会显示此字段（及其子字段）。

有关更多信息，请参阅同义词映射详情。

definitionVersion
文档
描述用于构建此索引生成的索引定义版本。
definitionVersion.version
整型
索引生成在相应mongot上使用的版本号。更新索引定义时，更新后的索引会使用递增的版本号进行构建。
definitionVersion.createdAt
日期
索引定义的创建时间。
definition
文档
构建此索引所使用的定义。

同义词映射详细信息

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

  • statusDetail.mainIndex.synonymMappingStatusDetails.<synonymMapping>

  • statusDetail.stagedIndex.synonymMappingStatusDetails<synonymMapping>

字段
类型
说明
status
字符串
相应mongot进程上的同义词映射状态。
queryable
布尔
指示同义词映射是否可以支持对相应mongot进程的查询。
message
字符串
描述同义词映射错误（如果适用）。仅当此同义词映射的status为FAILED时才会出现。

Atlas Search 索引状态

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

状态
说明
BUILDING

以下情况可能导致索引处于BUILDING状态：

  • Atlas 正在构建索引或在编辑后重新构建索引。

  • Atlas Search 无法跟上集合的索引更改。在这种情况下，Atlas 会在后台重建索引。

当索引处于BUILDING状态时：

  • 对于新索引，在索引构建完成之前，Atlas Search 无法使用该索引进行查询。

  • 对于现有索引，Atlas Search 会使用旧索引定义进行查询，直到索引重建完成。

处于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 上执行此命令，则会返回空结果。

举例

这些示例演示如何：

返回所有搜索索引

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

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 索引，请参阅：

← $listSampledQueries
$listSessions →

在此页面上