renameCollection¶

On this page

Definition
Behavior
Example
Exceptions

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:

copy

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

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.
`comment`	any	Optional. A user-provided comment to attach to this command. Once set, this comment appears alongside records of this command in the following locations: mongod log messages, in the `attr.command.cursor.comment` field. Database profiler output, in the `command.comment` field. `currentOp` output, in the `command.comment` field. A comment can be any valid BSON type (string, integer, object, array, etc). New in version 4.4.

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¶

Changed in version 4.2.

If renaming a collection within the same database, 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 an exclusive database lock.

If renaming a collection between different databases, renameCollection locking behavior depends on the MongoDB version:

For MongoDB 4.2.2 and later, renameCollection obtains an exclusive (W) lock on the target database, an intent shared (r) lock on the source database, and a shared (S) lock on the source collection. Subsequent operations on the target database must wait until renameCollection releases the exclusive database lock.
For MongoDB 4.2.1 and earlier, 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.

copy

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:

copy

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.

← reIndex setFeatureCompatibilityVersion →

renameCollection¶

Definition¶

Behavior¶

Sharded Collections¶

Existing Target Collection¶

Performance¶

Resource Locking¶

local Database¶

Open Cursors¶

Change Streams¶

Interaction with mongodump¶

Example¶

Exceptions¶

`local` Database¶

Interaction with `mongodump`¶