Navigation

db.collection.renameCollection()

On this page

  • Definition
  • Behavior
  • Example
db.collection.renameCollection(target, dropTarget)
Important
mongosh Method

This is a mongosh method. This is not the documentation for Node.js or other programming language specific driver methods.

In most cases, mongosh methods work the same way as the legacy mongo shell methods. However, some legacy methods are unavailable in mongosh.

For the legacy mongo shell documentation, refer to the documentation for the corresponding MongoDB Server release:

For MongoDB API drivers, refer to the language specific MongoDB driver documentation.

Renames a collection. Provides a wrapper for the renameCollection database command.

Parameter
Type
Description
target
string
The new name of the collection. Enclose the string in quotes. See Naming Restrictions.
dropTarget
boolean
Optional. If true, mongod drops the target of renameCollection prior to renaming the collection. The default value is false.

The db.collection.renameCollection() method operates within a collection by changing the metadata associated with a given collection.

Refer to the documentation renameCollection for additional warnings and messages.

Warning

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

Changed in version 4.2.

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 obtaining an exclusive database lock.

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

Call the db.collection.renameCollection() method on a collection object. For example:

db.rrecord.renameCollection("record")

This operation will rename the rrecord collection to record. If the target name (i.e. record) is the name of an existing collection, then the operation will fail.

Give Feedback

On this page

  • Definition
  • Behavior
  • Example