Database Manual / Reference / Database Commands / Sharding

moveRange (database command数据库命令)

Definition定义

moveRange

New in version 6.0.在版本6.0中新增。

Moves ranges between shards. Run the moveRange command with a mongos instance while using the admin database.在分片之间移动范围。在使用管理数据库时，使用mongos实例运行moveRange命令。

Tip

In mongosh, this command can also be run through the sh.moveRange() helper method.在mongosh中，此命令也可以通过sh.moveRange()辅助方法运行。

Helper methods are convenient for mongosh users, but they may not return the same level of information as database commands. 助手方法对mongosh用户来说很方便，但它们可能不会返回与数据库命令相同级别的信息。In cases where the convenience is not needed or the additional return fields are required, use the database command.如果不需要便利性或需要额外的返回字段，请使用数据库命令。

Compatibility兼容性

This command is available in deployments hosted in the following environments:此命令在以下环境中托管的部署中可用：

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud：云中MongoDB部署的完全托管服务

Note

This command is supported in all MongoDB Atlas clusters. 所有MongoDB Atlas集群都支持此命令。For information on Atlas support for all commands, see Unsupported Commands.有关Atlas支持所有命令的信息，请参阅不支持的命令。

  • MongoDB Enterprise: The subscription-based, self-managed version of MongoDB：MongoDB的基于订阅的自我管理版本
  • MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB：MongoDB的源代码可用、免费使用和自我管理版本

Syntax语法

The command has the following syntax:该命令具有以下语法：

db.adminCommand(
  {
    moveRange: <namespace>,
    toShard: <ID of the recipient shard>,
    min: <min key of the range to move>, // conditional
    max: <max key of the range to move>, // conditional
    forceJumbo: <bool>, // optional
    writeConcern: <write concern>, // optional
    secondaryThrottle: <bool> // optional
  }
)

Note

Use the listShards command to retrieve the ID of the recipient shard.使用listShards命令检索收件人分片的ID。

Command Fields命令字段

The command takes the following fields:该命令包含以下字段：

Field字段Type类型Description描述
toShardstring字符串ID of the recipient shard.收件人分片的ID。
minkey

Minimum key of the range to move. Required if you don't specify max.移动范围的最小键。如果未指定max，则为必填项。

If you do not specify min, given a chunk C where max is either the exclusive upper bound of C or C includes the shard key max, min is determined in the following way:如果不指定min，给定一个块C，其中max是C的独占上限，或者C包含分片键max，min按以下方式确定：

  • If the data size of the range between min(C) and max is less than the per-collection chunk size or the default chunk size, the chunk's min value is selected as min = min(C).如果min(C)和max之间的范围的数据大小小于每个集合块大小或默认块大小，则块的min被选择为min=min(C)。
  • Otherwise, key min > min(C) where min depends on the configured chunk size.否则，键min>min(C)，其中min取决于配置的块大小。
maxkey

Maximum key of the range to move. Required if you don't specify min.移动范围的最大键。如果未指定min，则为必填项。

If you do not specify max, given a chunk C including the shard key min, max is determined in the following way:如果不指定max，给定一个包含分片键min的块C，max按以下方式确定：

  • If the data size of the range between min and max(C) is less than the per-collection chunk size or the default chunk size, the chunk's max is selected as max = max(C).如果min和max(C)之间的范围的数据大小小于每个集合的块大小或默认块大小，则块的最大值被选择为max=max(C)。
  • Otherwise, key max < max(C) where max depends on the configured chunk size.否则，键max<max(C)，其中max取决于配置的块大小。
forceJumboboolean布尔值

Optional.可选。

Flag that determines if the command can move a range that is too large to migrate. 用于确定命令是否可以移动太大而无法迁移的范围的标志。The range may or may not be labeled as jumbo.该范围可能标记为巨型，也可能不标记为巨型。

  • If true, the command can move the range.如果为true，则该命令可以移动范围。
  • If false, the command cannot move the range.如果为false，则该命令无法移动范围。

The default is false.默认值为false。

WARNING:警告：

The moveRange command with forceJumbo=true blocks write operations on the collection.forceJumbo=true的moveRange命令阻止了对集合的写入操作。

This option causes the shard to migrate chunks even when they are larger than the configured chunk size. The collection remains unavailable for writes for the duration of the migration.此选项会导致分片迁移块，即使它们大于配置的块大小。在迁移期间，该集合仍不可用于写入。

To migrate these large chunks without this long blocking period, see Balance Ranges that Exceed Size Limit instead.要迁移这些大块而不需要这么长的阻塞期，请参阅超过大小限制的平衡范围。

writeConcerndocument文档

Optional.可选。

Document with the write concern.带有写入关注的文档。

The default is w: majority.默认值为w: majority。

secondaryThrottleboolean布尔值

Optional.可选。

  • If true, each document move during chunk migration propagates to at least one secondary before the balancer proceeds with the next document. 如果为true，则块迁移期间的每个文档移动都会在平衡器继续处理下一个文档之前传播到至少一个辅助文档。This is equivalent to a write concern of { w: 2 }.这相当于{ w: 2 }的写入关注。

    Use the writeConcern option to specify a different write concern.使用writeConcern选项指定其他写入关注。

  • If false, the balancer does not wait for replication to a secondary and instead continues with the next document.如果为false，则平衡器不会等待复制到辅助文档，而是继续处理下一个文档。

For more information, see Secondary Throttle.有关更多信息，请参阅辅助阀门。

The range migration section describes how ranges move between shards on MongoDB.范围迁移部分描述了范围如何在MongoDB上的分片之间移动。

Considerations注意事项

Only use the moveRange in scenarios like:仅在以下场景中使用moveRange：

  • an initial ingestion of data初次摄取数据
  • a large bulk import operation大宗进口业务

Allow the balancer to create and balance ranges in sharded clusters in most cases.在大多数情况下，允许平衡器在分片集群中创建和平衡范围。

Tip

Create Ranges in a Sharded Cluster在分片群集中创建范围

Examples示例

The following examples use a collection with:以下示例使用集合：

  • Shard key x分片键x
  • Configured chunk size of 128MB配置的块大小为128MB
  • A chunk with boundaries: 有边界的块：[x: 0, x: 100)

Specify both min and max指定min和max

The following table lists the results of setting min and max to various values:下表列出了将min和max设置为各种值的结果：

minmaxResult结果
0100Moves all the documents in the range to the recipient shard.将该范围内的所有文档移动到收件人分片。
1030

Creates three sub-ranges:创建三个子范围：

  • [x: 0, x: 10)
  • [x: 10, x: 30)
  • [x: 30, x: 100)

Moves all the documents in [x: 10, x: 30) to the recipient shard.将[x: 10, x: 30)中的所有文档移动到收件人分片。

020

Creates two sub-ranges:创建两个子范围：

  • [x: 0, x: 20)
  • [x: 20, x: 100)

Moves all the documents in [x: 0, x: 20) to the recipient shard.将[x: 0, x: 20)中的所有文档移动到收件人分片。

40100

Creates two sub-ranges:创建两个子范围：

  • [x: 0, x: 40)
  • [x: 40, x: 100)

Moves all the documents in [x: 40, x: 100) to the recipient shard.将[x: 40, x: 100)中的所有文档移动到收件人分片。

Specify min but not max指定min，但不指定max

The following table lists the results of setting min to various values:下表列出了将min设置为各种值的结果：

minAmount of Data in Key Range键范围内的数据量Result结果
0Less than 128 MB contained between keys x: 0 and x: 100.键x:0和x:100之间包含的空间小于128 MB。Moves all the documents in the range to the recipient shard.将该范围内的所有文档移动到收件人分片。
10Less than 128 MB contained between keys x: 0 and x: 100.键x:0和x:100之间包含的空间小于128 MB。

Creates two sub-ranges:创建两个子范围：

  • [x: 0, x: 10)
  • [x : 10, x: 100)

Moves all documents in [x: 10, x: 100) to the recipient shard.将[x: 10, x: 100)中的所有文档移动到收件人分片。

10128 MB contained between keys x: 10 and x: 30.键x:10和x:30之间包含128 MB。

Creates three sub-ranges:创建三个子范围：

  • [x: 0, x: 10)
  • [x: 10, x: 30)
  • [x: 30, x: 100)

Moves all documents in [x: 10, x: 30) to the recipient shard.将[x: 10, x: 30)中的所有文档移动到收件人分片。

Specify max but not min指定max，但不指定min

The following table lists the results of setting max to various values:下表列出了将max设置为各种值的结果：

maxAmount of Data in Key Range键范围内的数据量Result结果
100Less than 128 MB contained between keys x: 0 and x: 100.键x:0和x:100之间包含的空间小于128 MB。Moves all the documents in the range to the recipient shard.将该范围内的所有文档移动到收件人分片。
10Less than 128 MB contained between keys x: 0 and x: 100.键x:0和x:100之间包含的空间小于128 MB。

Creates two sub-ranges:创建两个子范围：

  • [x: 0, x: 10)
  • [x : 10, x: 100)

Moves all documents in [x: 0, x: 10) to the recipient shard.将[x: 0, x: 10)中的所有文档移动到收件人分片。

30128 MB contained between keys x: 10 and x: 30.键x:10和x:30之间包含128 MB。

Creates three sub-ranges:创建三个子范围：

  • [x: 0, x: 10)
  • [x: 10, x: 30)
  • [x: 30, x: 100)

Moves all documents in [x: 10, x: 30) to the recipient shard.将[x: 10, x: 30)中的所有文档移动到收件人分片。