Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/
Referência
/
Comandos de banco de dados
/
Comandos de Administração

Renomear coleção

Nesta página

  • Definição
  • Sintaxe
  • Campos de comando
  • Comportamento
  • Exemplo

Definição

renameCollection

Altera o nome de uma collection existente. Especifique os nomes das collections como renameCollection na forma de umnamespace completo (<database>.<collection>).

Dica

Em mongosh, esse comando também pode ser executado por meio do método auxiliar renameCollection().

Os métodos auxiliares são práticos para os usuários mongosh, mas podem não retornar o mesmo nível de informações que os comandos do banco de dados. Nos casos em que a praticidade não for necessária ou os campos de retorno adicionais forem necessários, use o comando de banco de dados.

Emitir o comando renameCollection no banco de dados admin.

Sintaxe

O comando tem a seguinte sintaxe:

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

Campos de comando

O comando contém os seguintes campos:

Campo
Tipo
Descrição
renameCollection
string
O namespace da collection para renomear. O namespace é uma combinação do nome do banco de dados e do nome da collection.
to
string
O novo namespace da coleção. Se o novo namespace especificar um banco de dados diferente, o comando renameCollection copiará a coleção para o novo banco de dados e descartará a coleção de origem. Consulte Restrições de nomeação.
dropTarget
booleano
Opcional. Se true, mongod descartará o target de renameCollection antes de renomear a coleção. O valor padrão é false.
writeConcern
documento

Opcional. Um documento que expressa a write concern para a operação. Omitir para usar a função de gravação padrão.

Quando emitido em um cluster fragmentado, mongos converte a preocupação de gravação do comando renameCollection e seu auxiliar db.collection.renameCollection() em "majority".

comment
qualquer

Opcional. Um comentário fornecido pelo usuário para anexar a este comando. Depois de definido, esse comentário aparece junto com os registros desse comando nos seguintes locais:

Um comentário pode ser qualquer tipo BSON válido (string, inteiro, objeto, array etc).

Comportamento

Coleções fragmentadas

A partir do MongoDB 5.0, você pode utilizar o comando renameCollection para alterar o nome de uma coleção fragmentada. O banco de dados de destino deve ser o mesmo que o banco de dados de origem.

Collections não fragmentadas

Você pode usar renameCollection para renomear uma coleção não fragmentada em um cluster fragmentado, desde que os bancos de dados de origem e de destino estejam no mesmo fragmento primário.

Coleções de Time Series

Não é possível usar renameCollection para renomear uma coleção de séries temporais. Para obter mais informações, consulte Limitações da coleção de séries temporais.

Collection de destino existente

renameCollection falhará se target for o nome de uma coleção existente e você não especificar dropTarget: true.

Desempenho

Alterado na versão 3.6.

renameCollection tem implicações de desempenho diferentes, dependendo do namespace de destino.

Se o banco de dados de destino for o mesmo que o banco de dados de origem, renameCollection simplesmente alterará o namespace. Esta é uma operação rápida.

Se o banco de dados de destino diferir do banco de dados de origem, o renameCollection copiará todos os documentos da coleção de origem para a de destino. Dependendo do tamanho da coleção, pode levar mais tempo para ser concluída.

Bloqueio de recursos em clusters fragmentados

Alterado na versão 5.0.

Ao renomear uma collection fragmentada ou não fragmentada em um cluster fragmentado, as collections de origem e de destino são bloqueadas exclusivamente em cada shard. As operações subsequentes nas collections de origem e de destino devem aguardar até que a operação de renomeação seja concluída.

Para obter mais informações sobre bloqueios no MongoDB, consulte as Perguntas frequentes: simultaneidade.

Bloqueio de recursos em conjuntos de réplicas

Se estiver renomeando uma coleção no mesmo banco de dados, renameCollection obtém um bloqueio exclusivo nas coleções de origem e destino durante a operação. Todas as operações subsequentes nas coleções devem aguardar até que renameCollection seja concluído.

Ao renomear uma coleção entre bancos de dados diferentes, renameCollection obtém um bloqueio exclusivo (W) no banco de dados de destino, um bloqueio de intenção compartilhada (r) no banco de dados de origem e um bloqueio compartilhado (S) na coleção de origem. Operações subsequentes no banco de dados de destino devem aguardar até que renameCollection libere o bloqueio exclusivo do banco de dados.

Para obter mais informações sobre bloqueios no MongoDB, consulte as Perguntas frequentes: simultaneidade.

local Banco de dados

  • Você não pode renomear uma collection de um banco de dados replicado para o banco de dados do local, que não é replicado.

  • Não pode renomear uma collection a partir da base de dados local , que não é replicada, para uma base de dados replicada.

Abrir cursores

Aviso

O método db.collection.renameCollection() e o comando renameCollection invalidarão os cursores abertos, o que interrompe as queries que estão retornando dados no momento.

Fluxos de alterações

Para Change Streams, o método db.collection.renameCollection() e o comando renameCollection criam uma invalidação para quaisquer Change Streams existentes abertos na coleção de origem ou de destino.

Interação com mongodump

Um mongodump iniciado com --oplog falhará se um cliente emitir o comando renameCollection durante o processo de despejo. Consulte mongodump.--oplog para mais informações.

Exemplo

O exemplo seguinte renomeia uma collection denominada orders no banco de dados do test para orders2014 no banco de dados do test.

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

mongosh fornece o auxiliar db.collection.renameCollection() para o comando de renomear coleções dentro do mesmo banco de dados. O seguinte é equivalente ao exemplo anterior:

use test
db.orders.renameCollection( "orders2014" )
← reIndexar
rotateCertificates →

Nesta página