renameCollection
On this page本页内容
Definition定义
renameCollection-
Changes the name of an existing collection.更改现有集合的名称。Specify collection names to指定集合名称以完整命名空间（renameCollectionin the form of a complete namespace (<database>.<collection>).<database>.<collection>）的形式重命名集合。TipIn在mongosh, this command can also be run through therenameCollection()helper method.mongosh中，这个命令也可以通过renameCollection()助手方法运行。Helper methods are convenient for助手方法对mongoshusers, 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.如果不需要方便，或者需要额外的返回字段，请使用数据库命令。Issue the对renameCollectioncommand against the admin database.admin数据库发出renameCollection命令。
Syntax语法
The command has the following syntax:该命令具有以下语法：
db.runCommand(
{
renameCollection: "<source_namespace>",
to: "<target_namespace>",
dropTarget: <true|false>,
writeConcern: <document>,
comment: <any>
}
)
Command Fields命令字段
The command contains the following fields:该命令包含以下字段：
renameCollection | string | The namespace of the collection to rename. The namespace is a combination of the database name and the name of the collection. |
to | string | 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. |
dropTarget | boolean | true, mongod will drop the target of renameCollection prior to renaming the collection. The default value is false. |
writeConcern | document | 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 |
|
Behavior行为
Sharded Collections分片集合
Starting in MongoDB 5.0, you can use the 从MongoDB 5.0开始，您可以使用renameCollection command to change the name of a sharded collection. The target database must be the same as the source database.renameCollection命令更改分片集合的名称。目标数据库必须与源数据库相同。
Unsharded Collections未硬化集合
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.
Time Series Collections时间序列集合
You cannot use renameCollection to rename a time series collection. For more information, see Time Series Collection Limitations.
Existing Target Collection现有目标集合
renameCollection fails if target is the name of an existing collection and you do not specify dropTarget: true.
Performance性能
Changed in version 3.6.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.
Resource Locking in Sharded Clusters分片集群中的资源锁定
Changed in version 5.0.5.0版更改。
When renaming a sharded or unsharded collection in a sharded cluster, the source and target collections are exclusively locked on every shard. Subsequent operations on the source and target collections must wait until the rename operation completes.在分片集群中重命名已分片或未分片的集合时，源集合和目标集合将以独占方式锁定在每个分片上。对源集合和目标集合的后续操作必须等待重命名操作完成。
For more information on locking in MongoDB, see FAQ: Concurrency.有关MongoDB中锁定的更多信息，请参阅常见问题解答：并发。
Resource Locking in Replica Sets副本集中的资源锁定
Changed in version 4.2.4.2版更改。
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.
Prior to MongoDB 4.2, renaming a collection within the same database with renameCollection required an exclusive database lock.
If renaming a collection between different databases, 如果在不同数据库之间重命名集合，renameCollection locking behavior depends on the MongoDB version:renameCollection锁定行为取决于MongoDB版本：
- For MongoDB 4.2.2 and later,
renameCollectionobtains 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 untilrenameCollectionreleases the exclusive database lock. - For MongoDB 4.2.1 and earlier,
renameCollectionobtains an exclusive (W) global lock. Subsequent operations on themongodmust wait untilrenameCollectionreleases the global lock.
For more information on locking in MongoDB, see FAQ: Concurrency.有关MongoDB中锁定的更多信息，请参阅常见问题解答：并发。
local Database
- You cannot rename a collection from a replicated database to the
localdatabase, which is not replicated. - You cannot rename a collection from the
localdatabase, which is not replicated, to a replicated database.
Open Cursors
The db.collection.renameCollection() method and renameCollection command will invalidate open cursors which interrupts queries that are currently returning data.
Change Streams
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.
Interaction with mongodump
A mongodump started with --oplog fails if a client issues the renameCollection command during the dump process. See mongodump.--oplog for more information.
Example实例
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" )