Docs 菜单

renameCollection

renameCollection

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

提示

mongosh 中,该命令也可通过 renameCollection() 辅助方法运行。

辅助方法对 mongosh 用户来说很方便,但它们返回的信息级别可能与数据库命令不同。如果不追求方便或需要额外的返回字段,请使用数据库命令。

Issue the renameCollection command against the 管理库.

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

注意

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

该命令具有以下语法:

{ renameCollection: "<source_namespace>",
to: "<target_namespace>",
dropTarget: <true|false>,
writeConcern: <document>,
comment: <any> }

该命令包含以下字段:

字段
类型
说明

renameCollection

字符串

The namespace of the collection to rename. The namespace is a combination of the database name and the name of the collection.

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 命名限制.

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 写入安全机制 of the renameCollection command and its helper db.collection.renameCollection() to "majority".

comment

any

可选。用户提供的待附加到该命令的注释。设置后,该注释将与该命令的记录一起出现在以下位置:

注释可以是任何有效的 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.

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

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 中锁定的更多信息,请参阅常见问题解答:并发。

  • You cannot rename a collection from a replicated database to the local database, which is not replicated.

  • You cannot rename a collection from the local database, which is not replicated, to a replicated database.

警告

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

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

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

The following example renames a collection named orders in the test database to orders2014 in the test database.

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" )