Database Manual / Reference / Database Commands / Sharding

addShard (database command数据库命令)

Definition定义

addShard

Adds a shard replica set to a sharded cluster.将分片副本集添加到分片集群。

Tip

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

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.如果不需要便利性或需要额外的返回字段，请使用database命令。

Compatibility兼容性

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

  • 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的源代码可用、免费使用和自我管理版本

Note

This command is not supported in MongoDB Atlas. See Modify your Atlas Sharded Cluster to add or remove shards from your Atlas cluster.MongoDB Atlas不支持此命令。请参阅修改Atlas分片集群以添加或删除Atlas集群中的分片。

Syntax语法

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

db.adminCommand(
   {
     addShard: "<replica_set>/<hostname><:port>",
     name: "<shard_name>"
   }
)

Command Fields命令字段

Note

Starting in version 6.2, MongoDB removes the maxSize field from the addShard command. As a result:从6.2版本开始，MongoDB从addShard命令中删除了maxSize字段。因此：

  • Running addShard with the maxSize field returns an InvalidOptions error.运行带有maxSize字段的addShard会返回InvalidOptions错误。
  • New documents in the shards collection no longer include the maxSize field.分片集合中的新文档不再包含maxSize字段。
  • Any pre-existing maxSize field entries are ignored.任何预先存在的maxSize字段条目都将被忽略。

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

Field字段Type类型Description描述
addShardstring字符串

The replica set name, hostname, and port of at least one member of the shard's replica set. Any additional replica set member hostnames must be comma separated. For example:分片副本集中至少一个成员的副本集名称、主机名和端口。任何其他副本集成员主机名都必须以逗号分隔。例如：

<replica_set>/<hostname><:port>,<hostname><:port>, ...
namestring字符串Optional. 可选。A name for the shard. If this is not specified, MongoDB automatically provides a unique name.分片的名称。如果没有指定，MongoDB会自动提供一个唯一的名称。

The addShard command stores shard configuration information in the config database. addShard命令将分片配置信息存储在配置数据库中。Always run addShard when using the admin database.使用admin数据库时，始终运行addShard。

Considerations注意事项

Storage存储

The shard that you add to your sharded cluster must be empty.您添加到分片集群的分片必须为空。

Balancing平衡

When you add a shard to a sharded cluster, you affect the balance of chunks among the shards of a cluster for all existing sharded collections. 当你向分片集群添加一个分片时，你会影响所有现有分片集合的集群分片之间的块平衡。The balancer will begin migrating chunks so that the cluster will achieve balance. See Balancer Internals for more information.平衡器将开始迁移块，以便集群实现平衡。有关更多信息，请参阅平衡器内部。

Hidden Members隐藏成员

Important

You cannot include a hidden member in the seed list provided to addShard.您不能在提供给addShard的种子列表中包含隐藏成员。

DDL OperationsDDL操作

If you add a shard while your cluster executes a DDL operation (operation that modifies a collection such as reshardCollection), addShard only executes after the concurrent DDL operation finishes.如果在集群执行DDL操作（修改reshardCollection等集合的操作）时添加分片，则addShard仅在并发DDL操作完成后执行。

Required Access所需访问权限

You must have the addShard action on a cluster resource to run the addShard command. 您必须对群集资源执行addShard操作才能运行addShard命令。The clusterAdmin or clusterManager built-in roles contain the addShard action and grant privileges to run the addShard command.clusterAdmin或clusterManager内置角色包含addShard操作，并授予运行addShard命令的权限。

Examples示例

The following command adds a replica set as a shard:以下命令将副本集添加为分片：

use admin
db.runCommand( { addShard: "repl0/mongodb3.example.net:27327"} )

Warning

Do not use localhost for the hostname unless your config server is also running on localhost.除非配置服务器也在localhost上运行，否则不要使用localhost作为主机名。