/ /

$listClusterCatalog

定义

$listClusterCatalog

8.0.10版本新增。

警告

$listClusterCatalog聚合阶段不受支持，也不能保证在未来版本中保持稳定。不要构建依赖于此阶段的特定输出格式的功能，因为输出可能会在将来的版本中发生变化。

$listClusterCatalog聚合阶段输出集群中集合的信息，包括名称和创建选项。

$listClusterCatalog 必须是管道的第一阶段。

您必须针对数据库调用此阶段。当您对管理员数据库运行此阶段时，它会返回有关集群中所有集合的信息。当您对任何其他数据库运行它时，它会返回有关该数据库中所有集合的信息。

语法

该阶段采用以下语法：

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

$listClusterCatalog 阶段接受包含以下可选字段的文档：

字段	说明
`shards`	可选。您可以在调用 `$listClusterCatalog` 时指定 `shards: true`，以便该阶段在其返回文档中包含分片列表。
`balancingConfiguration`	可选。如果您在调用 `$listClusterCatalog` 时指定 `balancingConfiguration: true`，则该阶段会在其返回对象中包含 `balancingEnabled`、`balancingEnabledReason`、`autoMergingEnabled` 和 `chunkSize` 字段。

输出

$listClusterCatalog 为每个集合返回一个文档。每个文档可包含以下字段：

{
    "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>
 }

下表包含有关 $listClusterCatalog 返回的字段的信息：

字段	类型	随默认查询一起返回	说明
`ns`	字符串	true	集合的完整命名空间空间，格式为 `"<dbName>.<collectionName>"`。
`db`	字符串	true	集合所在数据库的名称。
`type`	字符串	true	Type of data store. Returns `collection` for collections, `view` for views, and `timeseries` for time series collection.
`idIndex`	文档	true	提供有关集合的 `_id`索引的信息。与 `listCollections` 中返回的 `idIndex`字段相同。视图或时间序列集合不存在此字段。
`options`	文档	true	返回的文档包含以下字段： `viewOn`：文档。要从中创建视图的源集合或视图的名称。仅出现在视图上。 `pipeline`：文档大量。由聚合管道阶段组成。仅出现在视图上。 `validator`：文档。返回验证器规则或表达式。 `timeseries`：文档。返回时间序列选项。仅出现在时间序列存储桶和时间序列视图上。 `clusteredIndex`：文档大量。表示集群化索引。这些选项直接对应于 `db.createCollection()` 中的可用选项。有关详细信息，请参阅事务语法。
`info`	文档	true	列出与集合相关的以下字段： `readOnly`：`boolean`。如果为 `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.
`sharded`	布尔	true	指定集合是分片的还是未分片的。该字段也存在于副本集服务器上。
`shardKey`	文档	仅在集合分片的出现	集合的分片键。
`shards`	字符串数组	false, must specify shards in input document	每个集合的分片数。
`balancingEnabled`	布尔	false, must specify balancingConfiguration in input document	指定是否为该集合启用负载均衡。仅当集合已分片的，此字段才会出现。
`balancingEnabledReason`	文档	false, must specify balancingConfiguration in input document	返回有关使用哪个命令切换负载均衡的信息。该文档包含以下字段： `enableBalancing`：如果使用 `configureCollectionBalancing` 切换负载均衡，则为 `true` `allowMigrations`：如果使用 `setAllowMigrations` 切换负载均衡，则为 `true` 仅当集合已分片的，此字段才会出现。
`autoMergingEnabled`	布尔	false, must specify balancingConfiguration in input document	指定是否为集合启用AutoMerger。仅当集合已分片的，此字段才会出现。
`chunkSize`	int	false, must specify balancingConfiguration in input document	返回集合的数据块大小（以MiB为单位）。仅当集合已分片的，此字段才会出现。

限制

如果对 admin 数据库执行此命令，则需要 listClusterCatalog 权限动作，该动作包含在 clusterMonitor 角色中。

要对特定数据库运行此命令，您需要 listCollections 权限动作，该操作包含在 read 角色中。

示例

列出所有集合的信息

以下示例从 sample_mflix数据库中的所有集合返回默认信息：

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

运行此示例时，它会返回一个大量，其中包含 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}
  },
  ...
]

均衡配置

您可以返回分片的的数据库中所有集合的默认字段和有关负载均衡配置的信息。

以下示例返回 sample_mflix数据库的负载均衡配置：

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

前面的示例返回一个大量，其中包含每个集合的一个文档。其中每个文档都包含默认字段以及分片的集合的 balancingEnabled、balancingEnabledReason、autoMergingEnabled 和 chunkSize 字段。以下代码提供了此输出的示例：

[
  {
    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 示例使用 Atlas 示例数据集中的 sample_mflix数据库。要学习如何创建免费的MongoDB Atlas 集群并加载示例数据集，请参阅MongoDB Node.js驱动程序文档中的入门。

要使用MongoDB Node.js驱动程序将 $listClusterCatalog 阶段添加到聚合管道，请在管道对象中包含 $listClusterCatalog操作符。

列出数据库中所有集合的信息

以下示例创建一个管道阶段，返回 sample_mflix数据库中所有集合的信息。然后，该示例运行管道：

const pipeline = [{ $listClusterCatalog: {} }];
const db = client.db("sample_mflix");
const cursor = db.aggregate(pipeline);
return cursor;

列出集群中所有集合的信息

以下示例创建了一个管道阶段，该阶段返回集群中所有集合的信息。然后，该示例运行管道：

const pipeline = [{ $listClusterCatalog: {} }];
const adminDB = client.db("admin");
const cursor = adminDB.aggregate(pipeline);
return cursor;

均衡配置

以下示例创建一个管道，其中在 sample_mflix数据库中所有集合的返回文档中包含负载均衡信息。然后，该示例运行管道：

const db = client.db("sample_mflix");
const pipeline = [{ $listClusterCatalog: {balancingConfiguration: true} }];
const cursor = db.aggregate(pipeline);
return cursor;