renameCollection（数据库命令）

定义

renameCollection

Changes the name of an existing collection. Specify collection names to renameCollection in the form of a complete namespace (<database>.<collection>).

提示

In mongosh, this command can also be run through the renameCollection() helper method.

Helper methods are convenient for mongosh users, but they may not return the same level of information as database commands. In cases where the convenience is not needed or the additional return fields are required, use the database command.

Issue the renameCollection command against the admin database.

兼容性

此命令可用于以下环境中托管的部署：

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

注意

This command is supported in all MongoDB Atlas clusters. For information on Atlas support for all commands, see Unsupported Commands.

MongoDB Enterprise：基于订阅、自我管理的 MongoDB 版本
MongoDB Community：源代码可用、免费使用且可自行管理的 MongoDB 版本

语法

该命令具有以下语法：

db.runCommand(
   {
     renameCollection: "<source_namespace>",
     to: "<target_namespace>",
     dropTarget: <true|false>,
     writeConcern: <document>,
     comment: <any>
   }
)

命令字段

该命令包含以下字段：

字段	类型	说明
`renameCollection`	字符串	要重命名的集合的命名空间。命名空间是数据库名称和集合名称的组合。
`to`	字符串	The new namespace of the collection. If the new namespace specifies a different database, the `renameCollection` command copies the collection to the new database and drops the source collection. See Naming Restrictions. 在 MongoDB Atlas 部署中，`atlasAdmin` 角色仅授予 `renameCollectionSameDB` 权限操作，因此您无法将集合重命名为不同的数据库。
`dropTarget`	布尔	Optional. If `true`, `mongod` will drop the `target` of `renameCollection` prior to renaming the collection. The default value is `false`.
`writeConcern`	文档	可选。表达该操作的写关注的文档。省略以使用默认的写关注。 When issued on a sharded cluster, `mongos` converts the write concern of the `renameCollection` command and its helper `db.collection.renameCollection()` to `"majority"`.
`comment`	any	可选。用户提供的待附加到该命令的注释。设置后，该注释将与该命令的记录一起出现在以下位置： mongod 日志消息，位于 `attr.command.cursor.comment` 字段中。 `command.comment` 字段中的数据库分析器输出。 `currentOp` 输出，在 `command.comment` 字段。注释可以是任何有效的 BSON 类型（字符串、整型、对象、数组等）。

行为

分片集合

Starting in MongoDB 5.0, you can use the renameCollection command to change the name of a sharded collection. The target database must be the same as the source database.

未分片集合

You can use renameCollection to rename an unsharded collection in a sharded cluster as long as the source and target databases are on the same primary shard.

时间序列集合

You cannot use renameCollection to rename a time series collection. For more information, see Time Series Collection Limitations.

现有目标集合

renameCollection fails if target is the name of an existing collection and you do not specify dropTarget: true.

正在进行的索引构建

如果源集合上正在进行索引构建，重命名操作将失败并显示 BackgroundOperationInProgressForNamespace 错误。如果目标集合上正在进行索引构建，并且您指定 dropTarget: true，则操作也会失败。

要重命名集合，请等待索引构建完成，然后重试该操作。要检查是否有正在进行的索引构建，请使用 db.currentOp() 方法。

性能

在版本3.6中进行了更改。

renameCollection has different performance implications depending on the target namespace.

If the target database is the same as the source database, renameCollection simply changes the namespace. This is a quick operation.

If the target database differs from the source database, renameCollection copies all documents from the source collection to the target collection. Depending on the size of the collection, this may take longer to complete.

分片集群中的资源锁定

在版本5.0中进行了更改。

重命名分片集群中的分片集合或非分片集合时，源集合和目标集合都以独占方式锁定在每个分片上。对源集合和目标集合的后续操作必须等待重命名操作完成。

有关 MongoDB 中锁定的更多信息，请参阅常见问题解答：并发。

副本集中的资源锁定

If renaming a collection within the same database, renameCollection obtains an exclusive lock on the source and target collections for the duration of the operation. All subsequent operations on the collections must wait until renameCollection completes.

If renaming a collection between different databases, renameCollection obtains an exclusive (W) lock on the target database, an intent shared (r) lock on the source database, and a shared (S) lock on the source collection. Subsequent operations on the target database must wait until renameCollection releases the exclusive database lock.

有关 MongoDB 中锁定的更多信息，请参阅常见问题解答：并发。

`local` Database

您无法将已复制数据库中的集合重命名为未复制的 local 数据库中的集合名称。
您无法将未复制的 local 数据库中的集合重命名为已复制数据库中的集合名称。

打开游标

警告

The db.collection.renameCollection() method and renameCollection command will invalidate open cursors which interrupts queries that are currently returning data.

Change Streams

For MongoDB Change Streams, the db.collection.renameCollection() method and renameCollection command create an invalidate Event for any existing MongoDB Change Streams opened on the source or target collection.

互动 `mongodump`

A mongodump started with --oplog fails if a client issues the renameCollection command during the dump process. See mongodump.--oplog for more information.

例子

以下示例会将 test 数据库中名为 orders 的集合重命名为 test 数据库中的orders2014。

db.adminCommand( { renameCollection: "test.orders", to: "test.orders2014" } )

mongosh provides the db.collection.renameCollection() helper for the command to rename collections within the same database. The following is equivalent to the previous example:

use test
db.orders.renameCollection( "orders2014" )