renameCollection (original) (raw)

renameCollection

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

Tip

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 theadmin database.

This command is available in deployments hosted in the following environments:

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

Note

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

MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

The command has the following syntax:


db.runCommand(

   {

     renameCollection: "<source_namespace>",

     to: "<target_namespace>",

     dropTarget: <true|false>,

     writeConcern: <document>,

     comment: <any>

   }

)

The command contains the following fields:

Field	Type	Description
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	Optional. If true, mongod will drop the target ofrenameCollection prior to renaming the collection. The default value is false.
writeConcern	document	Optional. A document that expresses the write concernfor the operation. Omit to use the default write concern.When issued on a sharded cluster, mongos converts thewrite concern of therenameCollection command and its helperdb.collection.renameCollection() to"majority".
comment	any	Optional. A user-provided comment to attach to this command. Once set, this comment appears alongside records of this command in the following locations:mongod log messages, in theattr.command.cursor.comment field.Database profiler output, in the command.comment field.currentOp output, in the command.comment field.A comment can be any valid BSON type(string, integer, object, array, etc).

Starting in MongoDB 5.0, you can use the renameCollectioncommand 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 have 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.

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.

Changed in version 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.

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 untilrenameCollection 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.

For more information on locking in MongoDB, see FAQ: Concurrency.

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

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

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


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

mongosh provides thedb.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" )