$rename (operador de actualización)

Esta versión de la documentación está archivada y ya no recibe soporte. Para actualizar su implementación 6.0, consulte Procedimientos de actualización de MongoDB.7.0

Definición

$rename: El $rename operador actualiza el nombre de un campo.

Sintaxis

{ $rename: { <field1>: <newName1>, <field2>: <newName2>, ... } }

El nuevo nombre del campo debe ser diferente del nombre del campo existente. Para especificar un <field> en un documento incrustado, utilice notación de puntos.

Considera el siguiente ejemplo:

db.students.updateOne(
   { _id: 1 }, { $rename: { 'nickname': 'alias', 'cell': 'mobile' } }
)

La operación anterior renombra el campo nickname a alias y el campo cell a mobile en un documento donde _id es 1.

Comportamiento

Cuando ejecutas una $rename Operación, MongoDB realiza las siguientes acciones:

Borre el <field> antiguo y el campo con <newName> del documento (usando $unset).
Realice una operación $set con <newName>, usando el valor de <field>.

Atomicidad

Cada documento que coincide con un comando para actualizar se actualiza mediante una operación individual. Las operaciones de actualización (como $rename) solo garantizan la atomicidad a nivel de un solo documento.

Orden de campos

Es posible que la operación $rename no mantenga el orden de los campos en el documento.

Actualizar el orden de procesamiento

A partir de MongoDB 5.0, los operadores de actualización procesan los campos de documentos con nombres basados en cadenas en orden lexicográfico. Los campos con nombres numéricos se procesan en orden numérico. Consulta Comportamiento del operador de actualización para obtener más información.

Renombra los campos del documento incrustado

El operador $rename puede mover campos hacia dentro y hacia fuera de documentos incrustados.

$rename no funciona en documentos incrustados en arreglos.

Otras consideraciones

Si el documento ya tiene un campo con el <newName>, el operador $rename elimina ese campo y renombra el <field> especificado a <newName>.
Si el campo que se va a renombrar no existe en un documento, $rename no realiza ninguna acción.
A partir de MongoDB 5.0, mongod ya no genera un error cuando utiliza un operador de actualización como $rename con una expresión de operando vacía ( { } ). Una actualización vacía no produce cambios y no genera ninguna entrada en el oplog (lo que significa que la operación es una “no-op").

Ejemplos

Crear la colección students:

db.students.insertMany( [
   {
     "_id": 1,
     "alias": [ "The American Cincinnatus", "The American Fabius" ],
     "mobile": "555-555-5555",
     "nmae": { "first" : "george", "last" : "washington" }
   },
   {
     "_id": 2,
     "alias": [ "My dearest friend" ],
     "mobile": "222-222-2222",
     "nmae": { "first" : "abigail", "last" : "adams" }
   },
   {
     "_id": 3,
     "alias": [ "Amazing grace" ],
     "mobile": "111-111-1111",
     "nmae": { "first" : "grace", "last" : "hopper" }
   }
] )

Los documentos contienen un error, nmae debería ser name. Los ejemplos en las siguientes secciones actualizan los documentos de la colección.

Renombrar un campo

Para renombrar un campo, llamar al operador $rename con el nombre actual del campo y el nuevo nombre:

db.students.updateMany(
   { "nmae": { $ne: null } },
   { $rename: { "nmae": "name" } }
)

Esta operación verifica documentos donde el campo nmae no es nulo y actualiza esos documentos para renombrar el campo nmae a name:

{
  "_id": 1,
  "alias": [ "The American Cincinnatus", "The American Fabius" ],
  "mobile": "555-555-5555",
  "name": { "first" : "george", "last" : "washington" }
}
{
   "_id" : 2,
   "alias" : [ "My dearest friend" ],
   "mobile" : "222-222-2222",
   "name" : { "first" : "abigail", "last" : "adams" }
}
{
   "_id" : 3,
  "alias" : [ "Amazing grace" ],
  "mobile" : "111-111-1111",
  "name" : { "first" : "grace", "last" : "hopper" }
}

Renombrar un campo en un documento incrustado

Para renombrar un campo en un documento incrustado, llamar al operador $rename utilizando la notación de puntos para referirse al campo. Si el campo debe permanecer en el mismo documento incrustado, también utilizar la notación de puntos en el nuevo nombre, como en el siguiente ejemplo:

db.students.updateOne( { _id: 1 }, { $rename: { "name.first": "name.fname" } } )

Esta operación renombra el campo incrustado first a fname:

{
  _id: 1,
  alias: [ 'The American Cincinnatus', 'The American Fabius' ],
  mobile: '555-555-5555',
  name: { last: 'washington', fname: 'george' }
}

Renombrar un campo que no existe

Al renombrar un campo y el nombre del campo existente se refiere a un campo que no existe, el operador $rename no hace nada, como en el siguiente ejemplo:

db.students.updateOne( { _id: 1 }, { $rename: { 'wife': 'spouse' } } )

Esta operación no realiza ninguna acción porque no existe un campo llamado wife.

Tip

Volver

$mul

$set