db.collection.renameCollection()
On this page
Definition
db.collection.renameCollection(target, dropTarget)
Important
mongosh Method
This page documents a
mongosh
method. This is not the documentation for database commands or language-specific drivers, such as Node.js.For the database command, see the
renameCollection
command.For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.
Renames a collection. Provides a wrapper for the
renameCollection
database command.ParameterTypeDescriptiontarget
stringThe new name of the collection. Enclose the string in quotes. See Naming Restrictions.dropTarget
booleanOptional. Iftrue
,mongod
drops thetarget
ofrenameCollection
prior to renaming the collection. The default value isfalse
.
Compatibility
This method 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 all commands, see Unsupported 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
Behavior
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 invalidate open cursors. This creates
an invalidate event for any existing
change streams opened on the source or target
collection, and also interrupts queries that are currently returning
data from the renamed collection.
The method has the following limitations:
db.collection.renameCollection()
cannot move a collection between databases. UserenameCollection
for these rename operations.You cannot rename views.
db.collection.renameCollection()
is not supported on time series collections.You cannot rename a collection to itself. If you try to rename a collection to itself an
IllegalOperation
error is thrown.
Resource Locking in Sharded Clusters
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.
Resource Locking in Replica Sets
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.
Interaction with mongodump
A mongodump
started with
--oplog
fails if a client issues
db.collection.renameCollection()
during the dump process. See
mongodump.--oplog
for more information.
Example
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.