renameCollection

Definition

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

Issue the renameCollection command against theadmin database.

The command takes the following form:

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

The command contains the following fields:

FieldTypeDescriptionrenameCollectionstringThe namespace of the collection to rename. The namespace is acombination of the database name and the name of the collection.tostringThe new namespace of the collection. If the new namespace specifies adifferent database, the renameCollection command copiesthe collection to the new database and drops the source collection.See Naming Restrictions.dropTargetbooleanOptional. If true, mongod will drop the target ofrenameCollection prior to renaming the collection. Thedefault value is false.writeConcerndocumentOptional. A document that expresses the write concernfor the operation. Omit to use the default writeconcern.

When issued on a sharded cluster, mongos converts thewrite concern of therenameCollection command and its helperdb.collection.renameCollection() to"majority".

Note

You cannot rename a sharded collection. You can however rename anunsharded collection in a sharded cluster.

Behavior

Sharded Collections

renameCollection is not compatible with sharded collections.

Existing Target Collection

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

Performance

Changed in version 3.6.

renameCollection has different performance implications dependingon the target namespace.

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

If the target database differs from the source database,renameCollection copies all documents from the source collectionto the target collection. Depending on the size of the collection, thismay take longer to complete. Other operations which require exclusiveaccess to the affected collections will be blocked until the renamecompletes.

Resource Locking

Changed in version 4.2.

renameCollection obtains an exclusive lockon the specified collections for the duration of the operation. Allsubsequent operations on the collections must wait untilrenameCollection releases the lock.

Prior to MongoDB 4.2, renameCollectionobtained an exclusive lock on the parent database of the source _and_target collection, blocking all operations on the both databases _and_all their collections until the operation completed.

local Database

• 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 isnot replicated, to a replicated database.

Open Cursors

Warning

The db.collection.renameCollection() method andrenameCollection command will invalidate open cursorswhich interrupts queries that are currently returning data.

Change Streams

For Change Streams, thedb.collection.renameCollection() method andrenameCollection command create aninvalidate Event for any existing Change Streamsopened on the source or target collection.

Example

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

The mongo shell provides thedb.collection.renameCollection() helper for the command torename collections within the same database. The following isequivalent to the previous example:

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

Exceptions