MongoDB com drivers
Definição
db.collection.renameCollection(target, dropTarget)Renomeia uma coleção. Fornece um wrapper para o comando do banco de dados
renameCollection.
Parâmetros
Parâmetro | Tipo | Descrição |
|---|---|---|
| string | O novo nome da coleção. Coloque a string entre aspas. Consulte Restrições de nomenclatura. |
| booleano | Opcional. Se |
Compatibilidade
Esse método 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
Suporte à API Estável
A partir do MongoDB 8.1, renameCollection está incluído na API estável V1. Para usar o renameCollection na API estável, você deve conectar seu driver a uma implantação que esteja executando o MongoDB 8.1 ou superior.
Comportamento
O método db.collection.renameCollection() opera dentro de uma coleção alterando os metadados associados com uma determinada coleção.
Consulte a documentação renameCollection para obter avisos e mensagens adicionais.
Aviso
O método db.collection.renameCollection() e o comandorenameCollection 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 consultas que estejam retornando dados no momento da coleção renomado.
O método tem as seguintes limitações:
db.collection.renameCollection()não pode mover uma coleção entre bancos de dados. UserenameCollectionpara essas operações de renomeação.Não é possível renomear visualizações.
Você não pode renomear uma collection para si mesma. Se você tentar renomear uma collection para si mesma, um erro
IllegalOperationserá gerado.
Observação
A partir do MongoDB 9.0, você pode usar db.collection.renameCollection() em coleções de séries temporais.
Construções de índice em andamento
A operação de renomeação falha com um erro BackgroundOperationInProgressForNamespace se uma compilação de índice estiver em andamento na collection de origem. A operação também falhará se uma construção de índice estiver em andamento na coleção de destino e você especificar dropTarget: true.
Para renomear a coleção, aguarde a conclusão da compilação do índice e tente novamente a operação. Para verificar se há construções de índice em andamento, use o db.currentOp() método.
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
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.
Interação com mongodump
Um mongodump iniciado com --oplog falhará se um cliente emitir db.collection.renameCollection() durante o processo de despejo. Consulte mongodump.--oplog para obter mais informações.
Exemplo
Você pode chamar o método db.collection.renameCollection() em um objeto de coleção. Por exemplo:
db.rrecord.renameCollection("record")
Esta operação renomeará a coleção rrecord para record. Se o nome do destino (ou seja record) é o nome de uma coleção existente, então a operação falhará.