Navigation

renameCollection

Definition

renameCollection

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

Issue the renameCollection command against the admin database.

The command takes the following form:

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

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 of renameCollection prior to renaming the collection. The default value is false.
writeConcern document

Optional. A document that expresses the write concern for the operation. Omit to use the default write concern.

When issued on a sharded cluster, mongos converts the write concern of the renameCollection command and its helper db.collection.renameCollection() to "majority".

Note

You cannot rename a sharded collection. You can however rename an unsharded 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 existing collection and you do not specify dropTarget: true.

Performance

Changed in version 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. Other operations which require exclusive access to the affected collections will be blocked until the rename completes.

Resource Locking

Changed in version 4.2.

renameCollection obtains an exclusive lock on the specified collections for the duration of the operation. All subsequent operations on the collections must wait until renameCollection releases the lock.

Prior to MongoDB 4.2, renameCollection obtained 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 the local database, which is not replicated.
  • You cannot rename a collection from the local database, which is not replicated, to a replicated database.

Open Cursors

Warning

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 Event for any existing Change Streams opened on the source or target collection.

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

The mongo shell 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" )

Exceptions

exception 10026:
 Raised if the source namespace does not exist.
exception 10027:
 Raised if the target namespace exists and dropTarget is either false or unspecified.
exception 15967:
 Raised if the target namespace is an invalid collection name.