split

Definition

  • split
  • Splits a chunk in a sharded cluster into twochunks. The mongos instance splits and manageschunks automatically, but for exceptional circumstances thesplit command does allow administrators to manuallycreate splits. See Split Chunks in a Sharded Cluster forinformation on these circumstances, and on the MongoDB shell commandsthat wrap split.

The split command must be run in the admin databaseand uses the following form:

  1. db.adminCommand( { split: <database>.<collection>,
  2.                    <find|middle|bounds> } )

The split command takes a document with the followingfields:

FieldTypeDescriptionsplitstringThe name of the collection where the chunk exists.Specify the collection’s full namespace, including thedatabase name.finddocumentAn query statement that specifies an equality match on the shardkey. The match selects the chunk that contains the specifieddocument. You must specify only one of the following: find,bounds, or middle.

You cannot use the find option on an empty collection.boundsarrayNew in version 2.4: The bounds of a chunk to split. boundsapplies to chunks in collections partitioned using a hashedshard key. The parameter’s array must consist of two documentsspecifying the lower and upper shard-key values of the chunk. Thevalues must match the minimum and maximum values of an existingchunk. Specify only one of the following: find, bounds, ormiddle.

You cannot use the bounds option on an empty collection.middledocumentThe document to use as the split point to create two chunks.split requires one of the following options: find,bounds, or middle.

Considerations

When used with either the find or the bounds option, thesplit command splits the chunk along the median. As such,the command cannot use the find or the bounds option to splitan empty chunk since an empty chunk has no median.

To create splits in empty chunks, use either the middle option withthe split command or use the splitAt command.

Command Formats

To create a chunk split, connect to a mongos instance, andissue the following command to the admin database:

  1. db.adminCommand( { split: <database>.<collection>,
  2.                    find: <document> } )

Or:

  1. db.adminCommand( { split: <database>.<collection>,
  2.                    middle: <document> } )

Or:

  1. db.adminCommand( { split: <database>.<collection>,
  2.                    bounds: [ <lower>, <upper> ] } )

To create a split for a collection that uses a hashed shard key,use the bounds parameter. Do not use the middle parameter forthis purpose.

Warning

Be careful when splitting data in a sharded collection to createnew chunks. When you shard a collection that has existing data,MongoDB automatically creates chunks to evenly distribute thecollection. To split data effectively in a sharded cluster you mustconsider the number of documents in a chunk and the averagedocument size to create a uniform chunk size. When chunks haveirregular sizes, shards may have an equal number of chunks but havevery different data sizes. Avoid creating splits that lead to acollection with differently sized chunks.

See also

moveChunk, sh.moveChunk(),sh.splitAt(), and sh.splitFind(), which wrap thefunctionality of split.

Examples

The following sections provide examples of the split command.

Split a Chunk in Half

  1. db.adminCommand( { split : "test.people", find : { _id : 99 } } )

The split command identifies the chunk in the peoplecollection of the test database, that holds documents that match {_id : 99 }. split does not require that a match exist, in orderto identify the appropriate chunk. Then the command splits it into twochunks of equal size.

Note

split creates two equal chunks by range asopposed to size, and does not use the selected point as a boundary forthe new chunks

Define an Arbitrary Split Point

To define an arbitrary split point, use the following form:

  1. db.adminCommand( { split : "test.people", middle : { _id : 99 } } )

The split command identifies the chunk in the peoplecollection of the test database, that would hold documentsmatching the query { _id : 99 }. split does notrequire that a match exist, in order to identify the appropriatechunk. Then the command splits it into two chunks, with the matchingdocument as the lower bound of one of the split chunks.

This form is typically used when pre-splitting data in acollection.

Split a Chunk Using Values of a Hashed Shard Key

This example uses the hashed shard key userid in apeople collection of a test database. The following commanduses an array holding two single-field documents to represent theminimum and maximum values of the hashed shard key to split the chunk:

  1. db.adminCommand( { split: "test.people",
  2.                   bounds : [ { userid: NumberLong("-5838464104018346494") },
  3.                              { userid: NumberLong("-5557153028469814163") }
  4.              ] } )

Note

MongoDB uses the 64-bit NumberLongtype to represent the hashed value.

Use sh.status() to see the existing bounds of the shard keys.

Metadata Lock Error

If another process, such as a balancerprocess, changes metadata while split is running, you maysee a metadata lock error.

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

This message indicates that the split has failed with no sideeffects. Retry the split command.