Renomear coleção

Nesta página

Definição

Compatibilidade
Sintaxe
Campos de comando
Comportamento
Exemplo

Definição

renameCollection

Altera o nome de uma coleção existente. Especifique nomes de coleção para renameCollection no formato 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 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 é aceito em todos os clusters do MongoDB Atlas. Para obter informações sobre o suporte do Atlas a todos os comandos, consulte Comandos não suportados.

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: mensagens de log do mongod, no campo `attr.command.cursor.comment`. Saída do perfil do banco de dados, no campo `command.comment`. Saída de `currentOp`, no campo `command.comment`. 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 Cursors e Chnge Streams

Aviso

O método db.collection.renameCollection() e o comando renameCollection invalidam cursores abertos. Isso cria um evento inválido para quaisquer fluxos de alterações existentes abertos na coleção de origem ou destino e também interromper queries 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

rotateCertificates