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

Renomear coleção

Nesta página

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

Definição

renameCollection

Altera o nome de uma collection existente. Especifique nomes de coleção para renameCollection no formato 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.

Emita o comando renameCollection no banco de dados admin.

Compatibilidade

Esse comando está disponível em implantações hospedadas nos seguintes ambientes:

  • MongoDB Atlas: o serviço totalmente gerenciado para implantações do MongoDB na nuvem

Observação

Este comando é suportado em todos os clusters do MongoDB Atlas. Para obter informações sobre todos os comandos, consulte Comandos sem suporte.

  • MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB

  • MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB

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 eliminará 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
any

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 tenham o 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

renameCollection tem implicações de desempenho diferentes, dependendo do namespacede 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 coleção de destino. Dependendo do tamanho da collection, 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 Database

  • 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 e fluxos de change streams

Aviso

O método db.collection.renameCollection() e o comandorenameCollection invalidam cursores abertos. Isso cria um evento inválido para quaisquer change streams existentes abertos na coleção de origem ou destino e também interromper consultas que estejam retornando dados no momento da coleção renomado.

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 obter 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" )

Voltar

removeQuerySettings

Próximo

rotateCertificates