Menu Docs

Página inicial do Docs → Desenvolver aplicações → Manual do MongoDB

$renomear

Nesta página

  • Definição
  • Sintaxe
  • Comportamento
  • Exemplos

Definição

$rename

O operador $rename atualiza o nome de um campo.

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

  • Se o documento já tiver um campo com o <newName>, o operador $rename removerá esse campo e renomeará o <field> especificado para <newName>.

  • Se o campo a ser renomeado não existir em um documento, $rename não fará nada.

  • A partir do MongoDB 5.0, mongod não gera mais um erro quando você usa um operador de atualização como $rename com uma expressão de operando vazia ( { } ). Uma atualização vazia não resulta em nenhuma alteração e nenhuma entrada no oplog é criada (o que significa que a operação é um 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

Para renomear um campo em um documento incorporado, chame o operador $rename usando a notação de ponto para se referir ao campo. Se o campo tiver que permanecer no mesmo documento incorporado, use também a notação de ponto no novo nome, como no exemplo a seguir:

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

Ao renomear um campo e o nome de campo existente refere-se a um campo que não existe, o operador $rename não faz nada, como a seguir:

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

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

Dica

Veja também:

← $mul
$set →

Nesta página