balancerCollectionStatus (database command数据库命令)

Definition定义

balancerCollectionStatus

Returns a document that contains information about whether the chunks of a sharded collection are balanced (i.e. do not need to be moved) as of the time the command is run or need to be moved because of draining shards, zone violation or imbalance of chunks across shards.返回一个文档，其中包含有关分片集合的块在运行命令时是否平衡（即不需要移动）的信息，或者由于分片耗尽、区域冲突或分片间块不平衡而需要移动的信息。

You can only issue the balancerCollectionStatus against the admin database.您只能对admin数据库发出balancerCollectionStatus。

Tip

In mongosh, this command can also be run through the sh.balancerCollectionStatus() helper method.在mongosh中，此命令也可以通过sh.balancerCollectionStatus()辅助方法运行。

Helper methods are convenient for mongosh users, but they may not return the same level of information as database commands. 助手方法对mongosh用户来说很方便，但它们可能不会返回与数据库命令相同级别的信息。In cases where the convenience is not needed or the additional return fields are required, use the database command.如果不需要便利性或需要额外的返回字段，请使用database命令。

Compatibility兼容性

This command is available in deployments hosted in the following environments:此命令在以下环境中托管的部署中可用：

• MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud：云中MongoDB部署的完全托管服务

• MongoDB Enterprise: The subscription-based, self-managed version of MongoDB：MongoDB的基于订阅的自我管理版本
• MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB：MongoDB的源代码可用、免费使用和自我管理版本

Syntax语法

The command has the following syntax:该命令具有以下语法：

db.adminCommand(
   {
     balancerCollectionStatus: "<db>.<collection>"
   }
)

Specify the full namespace ("<db>.<collection>") of the sharded collection.指定分片集合的完整命名空间（"<db>.<collection>"）。

mongosh provides a wrapper method sh.balancerCollectionStatus().提供了一个包装器方法sh.balancerCollectionStatus()。

Access Control访问控制

When running with access control, the user must have the enableSharding privilege actions on database and/or collection to run the command. 当使用访问控制运行时，用户必须对数据库和/或集合具有enableSharding（启用分片）权限操作才能运行该命令。That is, a user must have a role that grants the following privilege:也就是说，用户必须具有授予以下权限的角色：

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

The built-in clusterManager role provides the appropriate privileges.内置的clusterManager角色提供适当的权限。

Output Document输出文档

The following is an example of a document returned by the command:以下是命令返回的文档示例：

{
   "chunkSize": Long("128"),
   "balancerCompliant" : false,
   "firstComplianceViolation" : "chunksImbalance",
   "ok" : 1,
   "operationTime" : Timestamp(1583192967, 16),
   "$clusterTime" : {
      "clusterTime" : Timestamp(1583192967, 16),
      "signature" : {
         "hash" : BinData(0,"AAAAAAAAAAAAAAAAAAAAAAAAAAA="),
         "keyId" : Long(0)
      }
   }
}

In addition to the command-specific return fields, the command also returns the ok status field, the operationTime field, and the $clusterTime field for the operation. 除了特定于命令的返回字段外，该命令还返回操作的ok状态字段、operationTime字段和$clusterTime字段。For details on these fields, see Response.有关这些字段的详细信息，请参阅响应。

Examples示例

To check whether the chunks of a sharded collection test.contacts is currently in balance, connect to a mongos instance and issue the following command:要检查分片集合test.contacts的块当前是否平衡，请连接到mongos实例并发出以下命令：

db.adminCommand( { balancerCollectionStatus: "test.contacts" } )

If the chunks for the collection do not need to be moved, the command returns an output similar to the following:如果不需要移动集合的块，则该命令返回类似于以下内容的输出：

{
   "chunkSize": Long("128"),
   "balancerCompliant" : true,
   "ok" : 1,
   "operationTime" : Timestamp(1583193238, 1),
   "$clusterTime" : {
      "clusterTime" : Timestamp(1583193238, 1),
      "signature" : {
         "hash" : BinData(0,"AAAAAAAAAAAAAAAAAAAAAAAAAAA="),
         "keyId" : Long(0)
      }
   }
}

{
   "chunkSize": Long("128"),
   "balancerCompliant": false,
   "firstComplianceViolation": "defragmentingChunks",
   "details": {
      "currentPhase": "moveAndMergeChunks",
      "progress": { "remainingChunksToProcess": 1 }
   }
}