sh.balancerCollectionStatus()

Definition

sh.balancerCollectionStatus(namespace)

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.

Important

mongosh Method

This page documents a mongosh method. This is not the documentation for database commands or language-specific drivers, such as Node.js.

For the database command, see the balancerCollectionStatus command.

For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.

Compatibility

This method is available in deployments hosted in the following environments:

• MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

• MongoDB Enterprise: The subscription-based, self-managed version of MongoDB

• MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

Syntax

The sh.balancerCollectionStatus() has the following form:

sh.balancerCollectionStatus( <namespace> )

Access Control

When running with access control, the user must have the enableSharding privilege actions on database and/or collection to run the method. 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.

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:

sh.balancerCollectionStatus("test.contacts")

If the chunks for the collection do not need to be moved, the method returns an output similar to the following:

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

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