renameCollection (comando de base de datos)

Definición

renameCollection

Cambia el nombre de una colección existente. Especifique los nombres de las colecciones que se van a renameCollection en forma de un namespace completo (<database>.<collection>).

Tip

En mongosh, este comando también se puede ejecutar a través del método asistente renameCollection().

Los métodos asistente son convenientes para usuarios de mongosh, pero es posible que no proporcionen el mismo nivel de información que los comandos de base de datos. En los casos en que no se necesite la conveniencia o se requieran campos de retorno adicionales, utiliza el comando de base de datos.

Ejecute el comando renameCollection en la base de datos admin.

Compatibilidad

Este comando está disponible en implementaciones alojadas en los siguientes entornos:

MongoDB Atlas: El servicio totalmente gestionado para implementaciones de MongoDB en la nube

Nota

Este comando es compatible con todos los clústeres de MongoDB Atlas. Para obtener información sobre el soporte de Atlas para todos los comandos, consulte Comandos no compatibles.

MongoDB Enterprise: La versión basada en suscripción y autogestionada de MongoDB
MongoDB Community: La versión de MongoDB con código fuente disponible, de uso gratuito y autogestionada.

Compatibilidad con Stable API

A partir de MongoDB 8.1, renameCollection se incluye en la versión V1 de la Stable API. Para utilizar renameCollection en la Stable API, debes conectar tu driver a una implementación que esté ejecutando MongoDB 8.1 o superior.

Sintaxis

El comando tiene la siguiente sintaxis:

db.runCommand(
   {
     renameCollection: "<source_namespace>",
     to: "<target_namespace>",
     dropTarget: <true|false>,
     writeConcern: <document>,
     comment: <any>
   }
)

Campos de comandos

El comando contiene los siguientes campos:

Campo	Tipo	Descripción
`renameCollection`	string	El namespace de la colección que se desea renombrar. El namespace es una combinación del nombre de la base de datos y el nombre de la colección.
`to`	string	El nuevo namespace de la colección. Si el nuevo namespace especifica una base de datos diferente, el comando `renameCollection` copia la colección en la nueva base de datos y descarta la colección de origen. Consulta restricciones de denominación.
`dropTarget`	booleano	opcional. Si `true`, `mongod` descartará el `target` de `renameCollection` antes de cambiar el nombre de la colección. El valor por defecto es `false`.
`writeConcern`	Documento	Opcional. Un documento que expresa el nivel de confirmación de escritura para la operación. Omite usar el nivel de confirmación de escritura por defecto. Cuando se emite en un clúster particionado, `mongos` convierte el nivel de confirmación de escritura (write concern) del comando `renameCollection` y su asistente `db.collection.renameCollection()` a `"majority"`.
`comment`	any	Opcional. Un comentario proporcionado por el usuario para adjuntar a este comando. Una vez configurado, este comentario aparece junto a los registros de este comando en las siguientes ubicaciones: Mensajes de registro de mongod, en el campo `attr.command.cursor.comment`. Salida del perfilador de base de datos, en el campo `command.comment`. `currentOp` de salida, en el campo `command.comment`. Un comentario puede ser de cualquier tipo BSON válido (string, objeto, arreglo, etc.).

Comportamiento

Colecciones fragmentadas

Puedes usar el comando renameCollection para cambiar el nombre de una colección particionada. La base de datos de destino debe ser la misma que la base de datos de origen. Esta operación preserva todos los índices.

Colecciones no particionadas

Puedes usar renameCollection para renombrar una colección sin particionar en un clúster particionado siempre que las bases de datos de origen y destino tengan la misma partición primaria. Si ejecutas renameCollection para renombrar una colección en la misma base de datos, la operación conserva los datos y los índices de la colección. Si ejecutas renameCollection contra una base de datos diferente, la operación reescribe los datos de la colección y los índices en archivos nuevos.

Colecciones de series de tiempo

A partir de MongoDB 9.0, puede renombrar colecciones de series temporales con renameCollection.

Colección de objetivos existente

renameCollection falla si target es el nombre de una colección existente y no especificas dropTarget: true.

Compilaciones de índices en curso

La operación de cambio de nombre falla con un error BackgroundOperationInProgressForNamespace si hay una creación de índices en curso en la colección de origen. La operación también falla si hay una creación de índices en curso en la colección de destino y especifica dropTarget: true.

Para cambiar el nombre de la colección, espere a que finalice la creación de índices y, a continuación, vuelva a intentar la operación. Para comprobar si hay creación de índices en curso, utilice el método db.currentOp().

Rendimiento

renameCollection tiene diferentes implicaciones en el rendimiento dependiendo del objetivo namespace.

Si la base de datos de destino es la misma que la base de datos de origen, renameCollection simplemente cambia el namespace. Esta es una operación rápida.

Si la base de datos de destino difiere de la base de datos de origen, renameCollection copia todos los documentos de la colección de origen a la colección de destino. Dependiendo del tamaño de la colección, esto puede tardar más en completarse.

Bloqueo de recursos en clústeres compartidos

Cambiado en la versión 5.0.

Al cambiar el nombre de una colección particionada o no particionada en un clúster, las colecciones de origen y destino se bloquean exclusivamente en cada partición. Las operaciones posteriores en las colecciones de origen y destino deben esperar hasta que se complete la operación de cambio de nombre.

Para obtener más información sobre el bloqueo en MongoDB, consulta FAQ: Concurrency.

Bloqueo de recursos en conjuntos de réplicas

Cuando se cambia el nombre de una colección dentro de la misma base de datos, renameCollection obtiene un bloqueo exclusivo en las colecciones de origen y destino durante toda la operación. Todas las operaciones posteriores en las colecciones deben esperar hasta que renameCollection se complete.

A partir de MongoDB 9.0, al renombrar una colección entre bases de datos diferentes, renameCollection obtiene un bloqueo exclusivo sobre las colecciones de origen y destino durante la duración de la operación. Las operaciones DDL y las escrituras en las colecciones de origen y destino deben esperar hasta que renameCollection finalice. La mayoría de las operaciones de lectura utilizan lecturas sin bloqueo y no se bloquean.

En versiones anteriores a 9.0, durante un cambio de nombre entre bases de datos, renameCollection mantenía solo un bloqueo compartido (S) en la colección de origen durante la fase de copia y liberaba el bloqueo antes de completar el cambio de nombre.

El cambio de bloqueo afecta solo a los set de réplicas. Los clústeres particionados ya bloquean ambas colecciones mientras dure el cambio de nombre, como se describió anteriormente en esta página.

Para obtener más información sobre el bloqueo en MongoDB, consulta FAQ: Concurrency.

`local` Database

No puede renombrar una colección de una base de datos replicada a la base de datos local, que no está replicada.
No se puede cambiar el nombre de una colección de la base de datos local, que no está replicada, a una base de datos replicada.

Abrir cursores y Change Streams

Advertencia

El db.collection.renameCollection() método y el renameCollection comando invalidan los cursores abiertos. Esto crea un evento de invalidación para cualquier corriente de cambios existente abierta en la colección de origen o de destino, y también interrumpe las consultas que están devolviendo datos de la colección renombrada.

Interacción con `mongodump`

Se produce un error al mongodump iniciado con --oplog si un cliente emite el comando renameCollection durante el proceso de vaciados. Consulta mongodump.--oplog para obtener más información.

Ejemplo

El siguiente ejemplo renombra una colección llamada orders en la base de datos test a orders2014 en la base de datos test.

db.adminCommand( { renameCollection: "test.orders", to: "test.orders2014" } )

mongosh provee el db.collection.renameCollection() asistente para el comando de renombrar colecciones dentro de la misma base de datos. Lo siguiente es equivalente al ejemplo anterior:

use test
db.orders.renameCollection( "orders2014" )

Volver

removeQuerySettings

rotateCertificates