db.collection.remove()
Importante
Método de mongosh obsoleto
Esse método está obsoleto em mongosh
. Para obter métodos alternativos, consulte Alterações de compatibilidade com o shell mongo legado.
Definição
db.collection.remove()
Remove documentos de uma collection.
Retorna: Um objeto WriteResult que contém o status da operação.
Compatibilidade
Você pode utilizar o db.collection.remove()
para implantações hospedadas nos seguintes ambientes:
MongoDB Atlas: o serviço totalmente gerenciado para implantações do MongoDB na nuvem
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 método db.collection.remove()
pode ter uma de duas sintaxes. O método remove()
pode receber um documento de query e um booleano justOne
opcional:
db.collection.remove( <query>, <justOne> )
O método pode aceitar um documento de query e, opcionalmente, um documento com as opções de remoção.
Alterado na versão 5.0.
db.collection.remove( <query>, { justOne: <boolean>, writeConcern: <document>, collation: <document>, let: <document> // Added in MongoDB 5.0 } )
O método remove()
utiliza os seguintes parâmetros:
Parâmetro | Tipo | Descrição | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
query | documento | Define os critérios de exclusão utilizando operadores de query. Para excluir todos os documentos de uma collection, passe um documento vazio ( {} ). | ||||||||||
justOne | booleano | Opcional. Para limitar a exclusão a apenas um documento, defina como true . Omita para usar o valor padrão de false e excluir todos os documentos que correspondam aos critérios de exclusão. | ||||||||||
writeConcern | documento | Opcional. Um documento expressando a preocupação de gravação. Omita o uso da preocupação de gravação padrão. Consulte Preocupação de gravação. Não defina explicitamente a preocupação de gravação para a operação se for executada em uma transação. Para usar write concern com transações, consulte Transações e write concern. | ||||||||||
collation | documento | Opcional. Especifica o agrupamento a ser usado para a operação. A colocação permite que os usuários especifiquem regras específicas do idioma para comparação de strings, como regras para letras maiúsculas e marcas de acento. A opção de agrupamento tem a seguinte sintaxe:
Ao especificar agrupamento, o campo Se o agrupamento não for especificado, mas a coleção tiver um agrupamento padrão (consulte Se nenhum agrupamento for especificado para a coleção ou para as operações, o MongoDB usa a comparação binária simples usada nas versões anteriores para comparações de strings. Você não pode especificar vários agrupamentos para uma operação. Por exemplo, você não pode especificar agrupamentos diferentes por campo ou, se estiver realizando uma busca com uma classificação, não poderá usar um agrupamento para a busca e outro para a classificação. | ||||||||||
documento | Opcional. ... include:: /includes/let-variables-syntax.rst ... include:: /includes/let-variables-syntax-note.rst Para um exemplo completo utilizando Novidades na versão 5.0. |
Comportamento
Escreva preocupação
O método remove()
usa o comando delete
, que usa a preocupação de gravação padrão. Para especificar uma preocupação de gravação diferente, inclua a preocupação de gravação no parâmetro de opções.
Considerações de query
Por padrão, o remove()
remove todos os documentos que correspondem à expressão query
. Especifique a opção justOne
para limitar a operação para remover um único documento. Para excluir um único documento classificado por uma ordem especificada, use o método findAndModify().
Remover vários documentos da collection pode ser feito alternadamente com outras operações de leitura e/ou gravação.
Coleções de Time Series
Não é possível usar o método remove()
em uma coleção de séries temporais.
Coleções fragmentadas
Para usar operações remove()
em uma coleção fragmentada que especifique a opção justOne: true
:
Se você segmentar apenas um fragmento, poderá usar uma chave de fragmento parcial na especificação da consulta ou,
Você pode fornecer a chave de estilhaço ou o campo
_id
na especificação de consulta.
Transações
db.collection.remove()
pode ser usado dentro de transações distribuídas.
Não defina explicitamente a preocupação de gravação para a operação se for executada em uma transação. Para usar write concern com transações, consulte Transações e write concern.
Importante
Na maioria dos casos, uma transação distribuída incorre em um custo de desempenho maior do que as gravações de um único documento, e a disponibilidade de transações distribuídas não deve substituir o design eficaz do esquema. Em muitos cenários, o modelo de dados desnormalizado (documentos e arrays incorporados) continuará a ser ideal para seus dados e casos de uso. Ou seja, para muitos cenários, modelar seus dados adequadamente minimizará a necessidade de transações distribuídas.
Para considerações adicionais sobre o uso de transações (como limite de tempo de execução e limite de tamanho do oplog), consulte também Considerações de produção.
Exemplos
Os exemplos a seguir são do método remove()
.
Remover todos os documentos de uma collection
Para remover todos os documentos em uma coleção, chame o método remove
com um documento de query {}
vazio. A operação a seguir exclui todos os documentos da coleção bios:
db.bios.remove( { } )
Esta operação não é equivalente ao método drop()
.
Para remover todos os documentos de uma collection de forma eficaz, considere usar o método drop()
para excluir a collection completamente, incluindo os índices, e depois recriar a collection e seus índices.
Remova todos os documentos que correspondam a uma condição
Para remover os documentos que correspondem a um critério de exclusão, chame o método remove()
com o parâmetro <query>
:
A operação a seguir remove todos os documentos da collection products
onde qty
é maior que 20
:
db.products.remove( { qty: { $gt: 20 } } )
Substituir preocupação de gravação padrão
A operação a seguir em um conjunto de réplicas remove todos os documentos da collection products
onde qty
é maior que 20
e especifica uma preocupação de gravação de w: 2
com um wtimeout
de 5000 milissegundos. Essa operação retorna depois que a gravação se propaga para o primary e um secundário ou expira após 5 segundos.
db.products.remove( { qty: { $gt: 20 } }, { writeConcern: { w: "majority", wtimeout: 5000 } } )
Remover um único documento que corresponda a uma condição
Para remover o primeiro documento que corresponda a um critério de exclusão, chame o método remove
com os critérios query
e o parâmetro justOne
definido como true
ou 1
.
A operação a seguir remove o primeiro documento da collection products
onde qty
é maior que 20
:
db.products.remove( { qty: { $gt: 20 } }, true )
Especifique o agrupamento
A colocação permite que os usuários especifiquem regras específicas do idioma para comparação de strings, como regras para letras maiúsculas e marcas de acento.
Uma coleção myColl
possui os seguintes documentos:
{ _id: 1, category: "café", status: "A" } { _id: 2, category: "cafe", status: "a" } { _id: 3, category: "cafE", status: "a" }
A seguinte operação inclui a opção coleção:
db.myColl.remove( { category: "cafe", status: "A" }, { collation: { locale: "fr", strength: 1 } } )
Usar variáveis em let
Novidades na versão 5.0.
Para definir variáveis que você pode acessar em outro lugar no comando, use a opção let .
Observação
Para filtrar resultados usando uma variável, você deve acessar a variável dentro do operador $expr
.
Criar uma coleção cakeFlavors
:
db.cakeFlavors.insertMany( [ { _id: 1, flavor: "chocolate" }, { _id: 2, flavor: "strawberry" }, { _id: 3, flavor: "cherry" } ] )
O exemplo a seguir define uma variável targetFlavor
em let
e usa a variável para excluir o sabor do bolo de morango:
db.cakeFlavors.remove( { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } }, { let : { targetFlavor: "strawberry" } } )
WriteResult
Resultados bem-sucedidos
O remove()
retorna um objeto WriteResult()
que contém o status da operação. Após a operação bem-sucedida, o objeto WriteResult()
apresentará o total de documentos removidos:
WriteResult({ "nRemoved" : 4 })
Erros de preocupação de gravação
Se o método remove()
encontrar erros de preocupação de gravação, os resultados incluirão o campo WriteResult.writeConcernError
:
WriteResult({ "nRemoved" : 7, "writeConcernError" : { "code" : 64, "codeName" : "WriteConcernFailed", "errmsg" : "waiting for replication timed out", "errInfo" : { "wtimeout" : true, "writeConcern" : { "w" : "majority", "wtimeout" : 1, "provenance" : "getLastErrorDefaults" } } } })
Erros não relacionados a preocupação de gravação
Se o método remove()
encontrar um erro que não seja preocupação de gravação, os resultados incluirão o campo WriteResult.writeError
:
WriteResult({ "nRemoved" : 0, "writeError" : { "code" : 2, "errmsg" : "unknown top level operator: $invalidFieldName" } })