mergeChunks

Definition

  • mergeChunks
  • For a sharded collection, mergeChunks combinescontiguous chunk ranges on a shard into a singlechunk. Issue the mergeChunks command on the admin database from amongos instance.

Syntax

mergeChunks has the following form:

  1. db.adminCommand( { mergeChunks : <namespace> ,
  2.                  bounds : [ { <shardKeyField>: <minFieldValue> },
  3.                             { <shardKeyField>: <maxFieldValue> } ] } )

For compound shard keys, you must include the full shard key in thebounds specification. For example, if the shard key is { x: 1, y:1 }, mergeChunks has the following form:

  1. db.adminCommand( { mergeChunks : <namespace> ,
  2.                  bounds : [ { x: <minValue>, y: <minValue> },
  3.                             { x: <maxValue>, y: <maxValue> } ] } )

Command Fields

The mergeChunks command takes the following fields:

FieldTypeDescription
mergeChunksnamespaceThe fully qualified namespace of the collectionwhere both chunks exist. Namespaces take form of<database>.<collection>.
boundsarrayAn array that contains the minimum and maximum key values of the newchunk.

Access Control

On deployments running with authorization, theuser must have access that includes the following privileges:

The built-in role clusterManager provides the requiredprivileges.

Behavior

Note

Use the mergeChunks only in special circumstances. Forinstance, when cleaning up your sharded cluster after removingmany documents.

In order to successfully merge chunks, the following must be true:

  • In the bounds field, <minkey> and <maxkey> must correspond tothe lower and upper bounds of the chunks to merge.
  • The chunks must reside on the same shard.
  • The chunks must be contiguous.

mergeChunks returns an error if these conditions are notsatisfied.

Return Messages

On success, mergeChunks returns to following document:

  1. {
  2.   "ok" : 1,
  3.   "$clusterTime" : {
  4.      "clusterTime" : Timestamp(1510767081, 1),
  5.      "signature" : {
  6.          "hash" : BinData(0,"okKHD0QuzcpbVQg7mP2YFw6lM04="),
  7.          "keyId" : NumberLong("6488693018630029321")
  8.       }
  9.   },
  10.   "operationTime" : Timestamp(1510767081, 1)
  11. }

Another Operation in Progress

mergeChunks returns the following error message if anothermetadata operation is in progress on the chunks collection:

  1. errmsg: "The collection's metadata lock is already taken."

If another process, such as balancer process, changes metadata whilemergeChunks is running, you may see this error. You canretry the mergeChunks operation without side effects.

Chunks on Different Shards

If the input chunks are not on the same shard,mergeChunks returns an error similar to the following:

  1. {
  2.   "ok" : 0,
  3.   "errmsg" : "could not merge chunks, collection test.users does not contain a chunk ending at { username: \"user63169\" }",
  4.   "$clusterTime" : {
  5.      "clusterTime" : Timestamp(1510767081, 1),
  6.      "signature" : {
  7.          "hash" : BinData(0,"okKHD0QuzcpbVQg7mP2YFw6lM04="),
  8.          "keyId" : NumberLong("6488693018630029321")
  9.       }
  10.   },
  11.   "operationTime" : Timestamp(1510767081, 1)
  12. }

Noncontiguous Chunks

If the input chunks are not contiguous,mergeChunks returns an error similar to the following:

  1. {
  2.   "ok" : 0,
  3.   "errmsg" : "could not merge chunks, collection test.users has more than 2 chunks between [{ username: \"user29937\" }, { username: \"user49877\" })"
  4.   "$clusterTime" : {
  5.      "clusterTime" : Timestamp(1510767081, 1),
  6.      "signature" : {
  7.          "hash" : BinData(0,"okKHD0QuzcpbVQg7mP2YFw6lM04="),
  8.          "keyId" : NumberLong("6488693018630029321")
  9.       }
  10.   },
  11.   "operationTime" : Timestamp(1510767081, 1)
  12.  
  13. }