mergeChunks¶

On this page

Definition
Syntax
Access Control
Behavior
Return Messages

Definition¶

mergeChunks¶: For a sharded collection, mergeChunks combines contiguous chunk ranges on a shard into a single chunk. Issue the mergeChunks command on the admin database from a mongos instance.

Syntax¶

mergeChunks has the following form:

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

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

copy

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

Command Fields¶

The mergeChunks command takes the following fields:

Field	Type	Description
`mergeChunks`	namespace	The fully qualified namespace of the collection where both chunks exist. Namespaces take form of `<database>.<collection>`.
`bounds`	array	An array that contains the minimum and maximum key values of the new chunk.

Access Control¶

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

splitChunk action on the collection.

The built-in role clusterManager provides the required privileges.

Behavior¶

Note

Use the mergeChunks only in special circumstances. For instance, when cleaning up your sharded cluster after removing many documents.

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

In the bounds field, <minkey> and <maxkey> must correspond to the 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 not satisfied.

Return Messages¶

On success, mergeChunks returns to following document:

copy

{
  "ok" : 1,
  "$clusterTime" : {
     "clusterTime" : Timestamp(1510767081, 1),
     "signature" : {
         "hash" : BinData(0,"okKHD0QuzcpbVQg7mP2YFw6lM04="),
         "keyId" : NumberLong("6488693018630029321")
      }
  },
  "operationTime" : Timestamp(1510767081, 1)
}

Another Operation in Progress¶

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

copy

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

If another process, such as balancer process, changes metadata while mergeChunks is running, you may see this error. You can retry 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:

copy

{
  "ok" : 0,
  "errmsg" : "could not merge chunks, collection test.users does not contain a chunk ending at { username: \"user63169\" }",
  "$clusterTime" : {
     "clusterTime" : Timestamp(1510767081, 1),
     "signature" : {
         "hash" : BinData(0,"okKHD0QuzcpbVQg7mP2YFw6lM04="),
         "keyId" : NumberLong("6488693018630029321")
      }
  },
  "operationTime" : Timestamp(1510767081, 1)
}

Noncontiguous Chunks¶

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

copy

{
  "ok" : 0,
  "errmsg" : "could not merge chunks, collection test.users has more than 2 chunks between [{ username: \"user29937\" }, { username: \"user49877\" })"
  "$clusterTime" : {
     "clusterTime" : Timestamp(1510767081, 1),
     "signature" : {
         "hash" : BinData(0,"okKHD0QuzcpbVQg7mP2YFw6lM04="),
         "keyId" : NumberLong("6488693018630029321")
      }
  },
  "operationTime" : Timestamp(1510767081, 1)

}

← movePrimary refineCollectionShardKey →