renameCollection (comando de banco de dados)

Definição

renameCollection

Altera o nome de uma coleção existente. Especifique os nomes das coleções para renameCollection na forma de um namespace completo (<database>.<collection>).

Dica

In mongosh, this command can also be run through the renameCollection() helper method.

Helper methods are convenient for mongosh users, but they may not return the same level of information as database commands. In cases where the convenience is not needed or the additional return fields are required, use the database command.

Emita o comando renameCollection no banco de dados admin.

Compatibilidade

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

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

Observação

This command is supported in all MongoDB Atlas clusters. For information on Atlas support for all commands, see Unsupported Commands.

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.

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. When issued on a sharded cluster, `mongos` converts the write concern of the `renameCollection` command and its helper `db.collection.renameCollection()` to `"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

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. Essa operação preserva todos os índices.

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. Se você executar renameCollection para renomear uma coleção no mesmo banco de dados, a operação preservará os dados e os índices da coleção. Se você executar o renameCollection em um banco de dados diferente, a operação reescreverá os dados de coleção e índices para novos arquivos.

Coleções de Time Series

Starting in MongoDB 9.0, you can rename time series collections with renameCollection.

Collection de destino existente

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

Construções de índice em andamento

A operação de renomeação falha com um erro BackgroundOperationInProgressForNamespace se uma construção de índice estiver em andamento na coleção de origem. A operação também falha 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 construção de índice e, em seguida, tente novamente a operação. Para verificar construções de índice em andamento, use o método db.currentOp().

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

Quando você renomeia 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.

A partir do MongoDB 9.0, ao renomear uma coleção entre diferentes bancos de dados, renameCollection obtém um bloqueio exclusivo nas coleções de origem e destino durante a operação. As operações DDL e gravar nas coleções de origem e destino devem aguardar até que renameCollection seja concluído. A maioria das operações de leitura usa leituras sem bloqueio e não é bloqueada.

Em versões anteriores à 9.0, durante um renomeamento entre bancos de dados, o renameCollection mantinha apenas um bloqueio compartilhado (S) na coleção de origem durante a fase de cópia e liberava o bloqueio antes de concluir o renomeamento.

A alteração de bloqueio afeta apenas conjuntos de réplicas. Os clusters já aplicam bloqueio a ambas as coleções durante a renomeação, conforme descrito anteriormente nesta página.

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

The db.collection.renameCollection() method and renameCollection command invalidate open cursors. This creates an invalidate event for any existing change streams opened on the source or target collection, and also interrupts queries that are currently returning data from the renamed collection.

Interação com `mongodump`

A mongodump started with --oplog fails if a client issues the renameCollection command during the dump process. See mongodump.--oplog for more information.

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 provides the db.collection.renameCollection() helper for the command to rename collections within the same database. The following is equivalent to the previous example:

use test
db.orders.renameCollection( "orders2014" )

Voltar

removeQuerySettings

rotateCertificates