- Reference >
- Database Commands >
- Administration Commands >
- renameCollection
renameCollection¶
On this page
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:
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 thetarget
ofrenameCollection
prior to renaming the collection. The default value isfalse
.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 therenameCollection
command and its helperdb.collection.renameCollection()
to"majority"
.Note
You cannot rename a sharded collection. However, you can rename an unsharded collection in a sharded cluster as long as the source and target databases are on the same primary shard.
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.
Resource Locking¶
If renaming a collection within the same database,
renameCollection
obtains an exclusive (W) database
lock. Other operations on the database must wait until
renameCollection
completes.
If renaming a collection between different databases,
renameCollection
obtains an exclusive (W) global lock.
Subsequent operations on the mongod
must wait until
renameCollection
releases the global lock.
For more information on locking in MongoDB, see FAQ: Concurrency.
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.
Interaction with mongodump
¶
A mongodump
started with
--oplog
fails if a client issues the
renameCollection
command during the
dump process. See mongodump --oplog
for more information.
Example¶
The following example renames a collection named orders
in the
test
database to orders2014
in the test
database.
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:
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. |