Menu Docs

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

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 um namespace 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 convenientes 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 conveniência 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 administrativo.

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 collection. Se o novo namespace especificar um banco de dados diferente, o comando renameCollection copiará a collection para o novo banco de dados e descartará a collection de origem. Consulte Restrições de nomenclatura.
dropTarget
boleano
Opcional. Se true, mongod eliminará o target de renameCollection antes de renomear a collection. 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, o mongos converte o write concern do comando renameCollection e seu db.collection.renameCollection() auxiliar 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 partilhadas

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 um collection não fragmentado em um cluster fragmentado, desde que os bancos de dados de origem e de destino estejam no mesmo primary shard.

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 das Coleções de séries temporais.

Collection de destino existente

renameCollection falhará se target for o nome de uma collection 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 collection de origem para a collection 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

Alterado na versão 4,2.

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

Antes do MongoDB 4.2, renomear uma collection dentro do mesmo banco de dados com renameCollection exigiu um bloqueio de banco de dados exclusivo.

Se renomear uma collection entre diferentes bancos de dados, o comportamento de bloqueio do renameCollection dependerá da versão MongoDB:

  • Para MongoDB 4.2. O 2 e posterior, o renameCollection obtém um bloqueio exclusivo (W) no banco de dados de destino, um bloqueio compartilhado (r) de intenção no banco de dados de origem e um bloqueio compartilhado (S) na collection de origem. Operações subsequentes no banco de dados de destino devem aguardar até que o renameCollection libere o bloqueio exclusivo do banco de dados.

  • Para MongoDB 4.2.1 e anteriores, renameCollection obtém um bloqueio global exclusivo (W). As operações subsequentes no mongod deverão esperar até que renameCollection libere a trava global.

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 qualquer Change Streams existente aberto 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 helper db.collection.renameCollection() para o comando renomear collections dentro do mesmo banco de dados. O seguinte é equivalente ao exemplo anterior:

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

Nesta página