$rename (operador de atualização)

Definição

$rename: The $rename operator updates the name of a field.

Sintaxe

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

O novo nome de campo deve ser diferente do nome de campo existente. Para especificar um <field> em um documento incorporado, use notação de ponto.

Considere o seguinte exemplo:

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

A operação anterior renomeia o campo nickname para alias e o campo cell para mobile em um documento onde _id é 1.

Comportamento

Ao executar uma operação do $rename, o MongoDB executa as seguintes ações:

Excluir o antigo <field> e o campo com <newName> do documento (usando $unset).
Executar uma operação $set com <newName>, usando o valor de <field>.

Atomicidade

Cada documento correspondido por um comando de atualização é atualizado em uma operação individual. As operações de atualização (como $rename) só garantem a atomicidade em um único documento.

Ordem do campo

A operação $rename pode não preservar a ordem dos campos no documento.

Atualizar ordem de processamento

A partir do MongoDB 5.0, os operadores de atualização processam campos de documento com nomes baseados em cadeia de caracteres em ordem lexicográfica. Os campos com nomes numéricos são processados em ordem numérica. Consulte Atualizar Comportamento de Operadores para detalhes.

Renomear campos de documentos incorporados

O operador $rename pode mover campos para dentro e para fora de documentos incorporados.

$rename não funciona em documentos incorporados em arrays.

Outras Considerações

If the document already has a field with the <newName>, the $rename operator removes that field and renames the specified <field> to <newName>.
If the field to rename does not exist in a document, $rename does nothing.
Starting in MongoDB 5.0, mongod no longer raises an error when you use an update operator like $rename with an empty operand expression ( { } ). An empty update results in no changes and no oplog entry is created (meaning that the operation is a no-op).

Exemplos

Crie a coleção 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" }
   }
] )

Os documentos contêm um erro, nmae deve ser name. Os exemplos nas seções a seguir atualizam os documentos na collection.

Renomear um campo

Para renomear um campo, chame o operador $rename com o nome atual do campo e o novo nome:

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

Esta operação verifica se há documentos em que o campo nmae não é nulo e atualiza esses documentos para renomear o campo nmae para 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" }
}

Renomear um campo em um documento incorporado

To rename a field in an embedded document, call the $rename operator using the dot notation to refer to the field. If the field is to remain in the same embedded document, also use the dot notation in the new name, as in the following:

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

Esta operação renomeia o campo incorporado first para fname:

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

Renomear um campo que não existe

When renaming a field and the existing field name refers to a field that does not exist, the $rename operator does nothing, as in the following:

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

Esta operação não faz nada porque não há nenhum campo chamado wife.

Dica

Voltar

$mul

$set