renameCollection（数据库命令）

定义

renameCollection

更改现有集合的名称。以完整命名空间 (<database>.<collection>) 的形式，为 renameCollection 指定集合名称。

提示

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.

对管理员数据库发出 renameCollection 命令。

兼容性

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

MongoDB Atlas：用于云中 MongoDB 部署的完全托管服务

注意

所有 MongoDB Atlas 集群都支持此命令。有关 Atlas 对所有命令的支持的信息，请参阅不支持的命令。

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

语法

该命令具有以下语法：

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

命令字段

该命令包含以下字段：

字段	类型	说明
`renameCollection`	字符串	要重命名的集合的命名空间。命名空间是数据库名称和集合名称的组合。
`to`	字符串	集合的新命名空间。如果新命名空间指定了不同的数据库，则 `renameCollection` 命令会将集合复制到新数据库，并删除源集合。请参阅命名限制。在 MongoDB Atlas 部署中，`atlasAdmin` 角色仅授予 `renameCollectionSameDB` 权限操作，因此您无法将集合重命名为不同的数据库。
`dropTarget`	布尔	可选。如果为 `true`，则 `mongod` 将在重命名该集合之前删除 `renameCollection` 中的 `target`。默认值为 `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 类型（字符串、整型、对象、数组等）。

行为

分片集合

从 MongoDB 5.0 开始，您可以使用 renameCollection 命令来更改分片集合的名称。目标数据库必须与源数据库相同。

未分片集合

只要源数据库和目标数据库在同一主节点上，就可以使用 renameCollection 对分片集合中的未分片集合进行重命名。

时间序列集合

不能使用 renameCollection 来重命名时间序列集合。有关详细信息，请参阅时间序列集合限制。

现有目标集合

renameCollection 如果 target 是现有集合的名称并且您未指定 dropTarget: true，则操作将失败。

正在进行的索引构建

The rename operation fails with a BackgroundOperationInProgressForNamespace error if an index build is in progress on the source collection. The operation also fails if an index build is in progress on the target collection and you specify dropTarget: true.

To rename the collection, wait for the index build to finish and then retry the operation. To check for in-progress index builds, use the db.currentOp() method.

性能

renameCollection 对性能会产生不同的影响，具体取决于目标命名空间。

如果目标数据库与源数据库相同，则 renameCollection 只需更改命名空间即可。这是一项快速操作。

如果目标数据库与源数据库不同，renameCollection 会将所有文档从源集合复制到目标集合中。这可能需要更长的时间才能完成，具体取决于集合的大小。

分片集群中的资源锁定

在版本5.0中进行了更改。

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

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

副本集中的资源锁定

如果对同一数据库中的集合进行重命名，renameCollection 会在该操作期间获得对源集合和目标集合的独占锁。对集合的所有后续操作都必须一直等到 renameCollection 完成。

如果在不同数据库之间重命名集合，则 renameCollection 会获取目标数据库上的独占 (W) 锁、源数据库上的意向共享 (r) 锁，以及源集合上的共享 (S) 锁。对目标数据库的后续操作必须等到 renameCollection 释放独占数据库锁。

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

`local` Database

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

打开游标和 Change Streams

警告

The db.collection.renameCollection() method and renameCollection command invalidate open cursors. This creates an invalidate event for any existing change streams opened on the source or target collection, and also interrupts queries that are currently returning data from the renamed 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" )