Database Manual / Reference / Query Language / Aggregation Stages

$listClusterCatalog

Definition定义

$listClusterCatalog

New in version 8.1.在版本8.1中新增。

Warning

The $listClusterCatalog aggregation stage is unsupported and is not guaranteed to be stable in a future release. Don't build functionality that relies on a specific output format of this stage, since the output may change in a future release.$listClusterCatalog聚合阶段不受支持,也不能保证在未来的版本中稳定。不要构建依赖于此阶段特定输出格式的功能,因为输出可能会在未来的版本中发生变化。

The $listClusterCatalog aggregation stage outputs information for collections in a cluster, including names and creation options.$listClusterCatalog聚合阶段输出集群中集合的信息,包括名称和创建选项。

$listClusterCatalog must be the first stage in the pipeline.必须是管道中的第一阶段。

You must call this stage against a database. When you run this stage against the admin database, it returns information about all collections in the cluster. When you run it against any other database, it returns information about all collections within that database.您必须针对数据库调用此阶段。当您对admin数据库运行此阶段时,它会返回有关集群中所有集合的信息。当您对任何其他数据库运行它时,它会返回该数据库中所有集合的信息。

Syntax语法

The stage has the following syntax:该阶段具有以下语法:

{
$listClusterCatalog: {
shards: true,
balancingConfiguration: true
}
}

The $listClusterCatalog stage takes a document with the following optional fields:$listClusterCatalog阶段接收一个包含以下可选字段的文档:

Field字段Description描述
shards

Optional. 可选。You can specify shards: true when you call $listClusterCatalog so that the stage includes a list of shards in its return document.您可以在调用$listClusterCatalog时指定shards: true,以便该阶段在其返回文档中包含一个分片列表。

balancingConfiguration

Optional. 可选。If you specify balancingConfiguration: true when you call $listClusterCatalog, the stage includes the balancingEnabled, balancingEnabledReason, autoMergingEnabled, and chunkSize fields in its return object.如果在调用$listClusterCatalog时指定balancingConfiguration:true,则该阶段将在其返回对象中包含balancingEnabledbalancingEnabledReasonautoMergeEnabledchunkSize字段。

Output输出

$listClusterCatalog returns a document per collection. Each document can contain the following fields:为每个集合返回一个文档。每个文档可以包含以下字段:

{
"ns" : <string>,
"db" : <string>,
"type" : <string>,
"idIndex" : <document>,
"options" : <document>,
"info" : <document>,
"sharded" : <boolean>,
"shardKey" : <document>,
"shards" : [<string>],
"balancingEnabled" : <boolean>,
"balancingEnabledReason" : <document>,
"autoMergingEnabled" : <boolean>,
"chunkSize" : <int>
}

The following table contains information about the fields that $listClusterCatalog returns:下表包含有关$listClusterCatalog返回的字段的信息:

Field字段Type类型Returned with default query返回默认查询Description描述
nsstring字符串trueThe full namespace of the collection, in the format "<dbName>.<collectionName>".集合的完整命名空间,格式为"<dbName>.<collectionName>"
dbstring字符串trueName of the database where the collection is located.集合所在的数据库的名称。
typestring字符串trueType of data store. Returns collection for collections, view for views, and timeseries for time series collection.数据存储类型。对集合返回collection、对视图返回view,对时间序列集合返回timeseries
idIndexdocument文档trueProvides information on the _id index for the collection. Identical to the returned idIndex field in listCollections. This field is not present for views or time series collections.提供有关集合的_id索引的信息。与listCollections中返回的idIndex字段相同。此字段不适用于视图或时间序列集合。
optionsdocument文档true

The returned document contains the following fields:返回的文档包含以下字段:

  • viewOn: document. The name of the source collection or view from which to create a view. Only present on views.:文件。要从中创建视图的源集合或视图的名称。仅在视图中显示。
  • pipeline: array of documents. Consists of the aggregation pipeline stages. Only present on views.:文档数组。由聚合管道阶段组成。仅在视图中显示。
  • validator: document. Returns the validator rules or expressions.:文件。返回验证器规则或表达式。
  • timeseries: document. Returns timeseries options. Only present on timeseries buckets and timeseries views.:文件。返回时间序列选项。仅在时间序列桶和时间序列视图上显示。
  • clusteredIndex: array of documents. Represents the clustered indexes.:文档数组。表示聚集索引。

These options correspond directly to the options available in db.createCollection(). 这些选项直接对应于db.createCollection()中可用的选项。For more information, see Syntax.有关更多信息,请参阅语法

infodocument文档true

Lists the following fields related to the collection:列出与集合相关的以下字段:

  • readOnly: boolean. If true the data store is read only. Always true for views.如果为true,则数据存储为只读。对视图永远是true
  • uuid: UUID. Once established, the collection UUID does not change. The collection UUID remains the same across replica set members and shards in a sharded cluster. This field is not present for views or timeseries views.一旦建立,集合UUID就不会改变。在分片集群中,副本集成员和分片之间的集合UUID保持不变。此字段不适用于视图或时间序列视图。
shardedboolean布尔值trueSpecifies whether the collection is sharded or unsharded. This field is also present on replica set servers.指定集合是分片的还是非分片的。此字段也存在于副本集服务器上。
shardKeydocument文档only present if collection is sharded仅当集合被分片时才存在The shard key of the collection.集合的分片键
shardsarray of strings字符串数组false, must specify shards in input documentfalse,必须在输入文档中指定分片Shards per collection.每个集合的分片。
balancingEnabledboolean布尔值false, must specify balancingConfiguration in input documentfalse,必须在输入文档中指定balancingConfigurationSpecifies if the balancing is enabled for that collection. This field is only present if the collection is sharded.指定是否为该集合启用平衡。仅当集合被分片时,此字段才存在。
balancingEnabledReasondocument文档false, must specify balancingConfiguration in input documentfalse,必须在输入文档中指定balancingConfiguration

Returns information on which command has been used to toggle balancing. This document has the following fields:返回有关已使用哪个命令切换平衡的信息。本文档包含以下字段:

This field is only present if the collection is sharded.仅当集合被分片时,此字段才存在。

autoMergingEnabledboolean布尔值false, must specify balancingConfiguration in input documentfalse,必须在输入文档中指定balancingConfigurationSpecifies if the AutoMerger is enabled for the collection. 指定是否为该集合启用了自动合并This field is only present if the collection is sharded.仅当集合被分片时,此字段才存在。
chunkSizeintfalse, must specify balancingConfiguration in input documentfalse,必须在输入文档中指定balancingConfigurationReturns the chunk size, in MiB, of the collection. This field is only present if the collection is sharded.返回集合的大小,单位为MiB。仅当集合被分片时,此字段才存在。

Restrictions限制

If you execute this command against the admin database, you need the listClusterCatalog privilege action, which is included in the clusterMonitor role.如果对admin数据库执行此命令,则需要clusterMonitor角色中包含的listClusterCatalog权限操作。

To run this command against a specific database, you need the listCollections privilege action, which is included in the read role.要对特定数据库运行此命令,您需要read角色中包含的listCollections权限操作。

Examples示例

MongoDB Shell

List Information from All Collections列出所有集合的信息

The following example returns default information from all collections in the sample_mflix database:以下示例返回sample_mflix数据库中所有集合的默认信息:

use sample_mflix

db.aggregate([
{
$listClusterCatalog: {}
}
])

When you run this example, it returns an array containing a document for each collection in the sample_mflix database. Each of these documents contains the default fields described in the preceding table:运行此示例时,它返回一个数组,其中包含sample_mflix数据库中每个集合的文档。这些文档中的每一个都包含上表中描述的默认字段:

[
{
ns: "sample_mflix.movies",
db: "sample_mflix",
type: "collection",
idIndex: { v: 2, key: { _id: 1 }, name: '_id' },
options: { ... },
sharded: false,
info: {
readOnly: false,
uuid: new UUID("6c46c8b9-4999-4213-bcef-9a36b0cff228")
}
},
{
ns: "sample_mflix.comments",
db: "sample_mflix",
type: "collection",
options: { ... },
sharded: true,
info: {
readOnly: true,
uuid: new UUID("6c448eb9-4090-4213-bbaf-9a36bb7fc98e")
}
shardKey: { _id: 1}
},
...
]

Balancing Configuration平衡配置

You can return the default fields and information about the balancing configuration for all collections in a database with sharded collections.您可以为具有分片集合的数据库中的所有集合返回默认字段和有关平衡配置的信息。

The following example returns balancing configurations for the sample_mflix database:以下示例返回sample_mflix数据库的平衡配置:

use sample_mflix

db.aggregate([
{
$listClusterCatalog: {
balancingConfiguration: true
}
}
])

The preceding example returns an array containing a document for each collection. Each of these documents contains the default fields along with the balancingEnabled, balancingEnabledReason, autoMergingEnabled, and chunkSize fields for sharded collections. The following code provides an example of this output:前面的示例返回一个数组,其中包含每个集合的文档。这些文档中的每一个都包含默认字段以及分片集合的balancingEnabledbalancingEnabledReasonautoMergeEnabledchunkSize字段。以下代码提供了此输出的示例:

[
{
ns: "sample_mflix.movies",
db: "sample_mflix",
type: "collection",
idIndex: { v: 2, key: { _id: 1 }, name: '_id' },
options: { ... },
sharded: false,
...
},
{
ns: "sample_mflix.comments",
db: "sample_mflix",
type: "collection",
sharded: true,
shardKey: { _id: 1},
balancingEnabled: true,
balancingEnabledReason: {
enableBalancing: true,
allowMigrations: false
},
autoMergingEnabled: false,
chunkSize: 256,
...
},
...
]
Node.js

The Node.js examples on this page use the sample_mflix database from the Atlas sample datasets. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see Get Started in the MongoDB Node.js driver documentation.本页上的Node.js示例使用Atlas示例数据集中的sample_mflix数据库。要了解如何创建免费的MongoDB Atlas集群并加载示例数据集,请参阅MongoDB Node.js驱动程序文档中的入门

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

List Information from All Collections in a Database列出数据库中所有集合的信息

The following example creates a pipeline stage that returns information for all collections in the sample_mflix database. The example then runs the pipeline:以下示例创建了一个管道阶段,该阶段返回sample_mflix数据库中所有集合的信息。然后,该示例运行管道:

const pipeline = [{ $listClusterCatalog: {} }];

const db = client.db("sample_mflix");

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

List Information from All Collections in a Cluster列出群集中所有集合的信息

The following example creates a pipeline stage that returns information for all collections in a cluster. The example then runs the pipeline:以下示例创建了一个管道阶段,该阶段返回集群中所有集合的信息。然后,该示例运行管道:

const pipeline = [{ $listClusterCatalog: {} }];

const adminDB = client.db("admin");

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

Balancing Configuration平衡配置

The following example creates a pipeline that includes balancing information in the return documents for all collections in the sample_mflix database. The example then runs the pipeline:以下示例创建了一个管道,该管道在sample_mflix数据库中所有集合的返回文档中包含平衡信息。然后,该示例运行管道:

const db = client.db("sample_mflix");

const pipeline = [{ $listClusterCatalog: {balancingConfiguration: true} }];

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