Docs Menu

Docs HomeMongoDB Manual

sh.balancerCollectionStatus()

On this page

  • Definition
  • Syntax
  • Access Control
  • Examples
sh.balancerCollectionStatus(namespace)

New in version 4.4.

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.

The mongosh method sh.balancerCollectionStatus() wraps the balancerCollectionStatus command.

The sh.balancerCollectionStatus() has the following form:

sh.balancerCollectionStatus( <namespace> )

The sh.balancerCollectionStatus() method takes the following parameter:

Parameter
Type
Description
String

The namespace of the collection to shard in the form "<database>.<collection>".

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.

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)
}
}
}

If the queried namespace is going through chunk defragmentation, the sh.balancerCollectionStatus method returns output similar to the following:

{
"balancerCompliant": false,
"firstComplianceViolation": "defragmentingChunks",
"details": {
"currentPhase": "moveAndMergeChunks",
"progress": { "remainingChunksToProcess": 1 }
}
}

Note

Chunk defragmentation occurs in multiple phases. The progress field only pertains to the current phase.

For the description of the output, see balancerCollectionStatus Output.

←  sh.addTagRange()sh.commitReshardCollection() →
Give Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.