db.collection.findOneAndDelete()
Nesta página
MongoDB com drivers
Esta página documenta um método mongosh
. Para ver o método equivalente em um driver do MongoDB, consulte a página correspondente da sua linguagem de programação:
Definição
db.collection.findOneAndDelete( filter, options )
Deletes a single document based on the
filter
andsort
criteria, returning the deleted document.O método
findOneAndDelete()
tem o seguinte formato:db.collection.findOneAndDelete( <filter>, { writeConcern: <document>, projection: <document>, sort: <document>, maxTimeMS: <number>, collation: <document> } ) O método
findOneAndDelete()
utiliza os seguintes parâmetros:ParâmetroTipoDescriçãofilter
documento
The selection criteria for the deletion. The same query selectors as in the
find()
method are available.Especifique um documento vazio
{ }
para excluir o primeiro documento retornado na coleção.Se não for especificado, o padrão será um documento vazio.
Se o argumento de consulta não for um documento, a operação será executada.
writeConcern
documento
Opcional. Um documento que expressa o write concern. Omitir para usar o write concern padrão.
{ w: <value>, j: <boolean>, wtimeout: <number> } See Delete A Document Using WriteConcern for usage.
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.
projection
documento
Opcional. Um subconjunto de campos para retornar.
Para retornar todos os campos no documento retornado, omita este parâmetro.
Se o argumento de projeção não for um documento, ocorrerá um erro na operação.
sort
documento
Opcional. Especifica uma ordem de classificação para os documentos correspondidos pelo
filter
.Se o argumento de classificação não for um documento, ocorrerá um erro com a operação.
Consulte
cursor.sort()
.maxTimeMS
número
Opcional. Especifica um limite de tempo em milissegundos dentro do qual a operação deve ser concluída. Lança um erro se o limite for excedido.
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:
collation: { locale: <string>, caseLevel: <boolean>, caseFirst: <string>, strength: <int>, numericOrdering: <boolean>, alternate: <string>, maxVariable: <string>, backwards: <boolean> } Ao especificar agrupamento, o campo
locale
é obrigatório; todos os outros campos de agrupamento são opcionais. Para obter descrições dos campos, consulte Documento de agrupamento.Se o agrupamento não for especificado, mas a coleção tiver um agrupamento padrão (consulte
db.createCollection()
), a operação usará o agrupamento especificado para a coleção.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.
Retorna: Returns the deleted document.
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
Comportamento
Correspondência de documento
findOneAndDelete()
deletes the first matching
document in the collection that matches the filter
.
The sort
parameter can be used to influence which document is deleted.
Projeção
Importante
Consistência de linguagem
Como parte da criação da projeção find()
e findAndModify()
consistente com o estágio $project
da agregação,
A projeção
find()
efindAndModify()
pode aceitar expressões de agregação e sintaxe.O MongoDB impõe restrições adicionais em relação às projeções. Consulte Restrições de Projeção para detalhes.
O parâmetro projection
obtém um documento no seguinte formato:
{ field1: <value>, field2: <value> ... }
Projeção | Descrição |
---|---|
| Especifica a inclusão de um campo. Se você especificar um número inteiro diferente de zero para o valor de projeção, a operação tratará o valor como |
| Especifica a exclusão de um campo. |
| Usa o operador de projeção de array Não disponível para visualizações. |
| Usa os operadores de projeção de array ( Não disponível para visualizações. |
| Especifica o valor do campo projetado. Com o uso de expressões de agregação e sintaxe, incluindo o uso de literais e variáveis de agregação, você pode projetar novos campos ou projetar campos existentes com novos valores.
|
Especificação de campo incorporada
Para campos em documentos incorporados, você pode especificar o campo usando:
notação de pontos, por exemplo
"field.nestedfield": <value>
formulário aninhado, por exemplo
{ field: { nestedfield: <value> } }
_id
Projeção de campo
O campo _id
é incluído nos documentos retornados por padrão, a menos que você especifique explicitamente _id: 0
na projeção para suprimir o campo.
Inclusão ou exclusão
Uma projection
não pode conter especificações de inclusão e exclusão, com exceção do campo _id
:
Em projeções que incluem explicitamente campos, o campo
_id
é o único campo que você pode excluir explicitamente.Em projeções que excluem explicitamente campos, o campo
_id
é o único campo que você pode incluir explicitamente; entretanto, o campo_id
é incluído por padrão.
Para obter mais informações sobre "projection", consulte também:
Coleções fragmentadas
Documentos em uma coleção fragmentada podem estar faltando os campos de chave de estilhaço. Para direcionar um documento que não tenha a chave de fragmento, você pode usar a correspondência de igualdade null
em conjunto com outra condição de filtro (como no campo _id
). Por exemplo:
{ _id: <value>, <shardkeyfield>: null } // _id of the document missing shard key
Transações
db.collection.findOneAndDelete()
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.
Entradas de oplog
If a db.collection.findOneAndDelete()
operation successfully deletes
a document, the operation adds an entry on the oplog (operations
log). If the operation fails or does not find a document to delete, the
operation does not add an entry on the oplog.
Exemplos
Delete A Document
A collection scores
contém documentos semelhantes aos seguintes:
db.scores.insertMany( [ { _id: 6305, name : "A. MacDyver", "assignment" : 5, "points" : 24 }, { _id: 6308, name : "B. Batlock", "assignment" : 3, "points" : 22 }, { _id: 6312, name : "M. Tagnum", "assignment" : 5, "points" : 30 }, { _id: 6319, name : "R. Stiles", "assignment" : 2, "points" : 12 }, { _id: 6322, name : "A. MacDyver", "assignment" : 2, "points" : 14 }, { _id: 6234, name : "R. Stiles", "assignment" : 1, "points" : 10 } ] )
The following operation finds the first document where name : M. Tagnum
and deletes it:
db.scores.findOneAndDelete( { "name" : "M. Tagnum" } )
The operation returns the original document that has been deleted:
{ _id: 6312, name: "M. Tagnum", "assignment" : 5, "points" : 30 }
Delete A Document Using WriteConcern
A collection scores
contém documentos semelhantes aos seguintes:
db.scores.insertMany( [ { _id: 6305, name : "A. MacDyver", "assignment" : 5, "points" : 24 }, { _id: 6308, name : "B. Batlock", "assignment" : 3, "points" : 22 }, { _id: 6312, name : "M. Tagnum", "assignment" : 5, "points" : 30 }, { _id: 6319, name : "R. Stiles", "assignment" : 2, "points" : 12 }, { _id: 6322, name : "A. MacDyver", "assignment" : 2, "points" : 14 }, { _id: 6234, name : "R. Stiles", "assignment" : 1, "points" : 10 } ] )
The following operation uses a write concern document inside of the
db.collection.findOneAndDelete()
method with options:
w:1
to requests acknowledgment that the write operation has propagated to the standalone mongod or the primary in a replica set.j:true
to tell the number of MongoDB instances specified inw:1
to have the delete written to on-disk journel.wtimeout : 1000
to specify a time limit, in milliseconds, for the write concern.wtimeout
is only applicable forw
values greater than 1.
db.scores.findOneAndDelete( { name: "A. MacDyver" }, { writeConcern: { w : 1, j : true, wtimeout : 1000 } } )
A operação retorna o seguinte documento:
{ _id: 6305, name: 'A. MacDyver', assignment: 5, points: 24 }
The document is deleted with the writeConcern options specified.
Sort And Delete A Document
A collection scores
contém documentos semelhantes aos seguintes:
db.scores.insertMany( [ { _id: 6305, name : "A. MacDyver", "assignment" : 5, "points" : 24 }, { _id: 6308, name : "B. Batlock", "assignment" : 3, "points" : 22 }, { _id: 6312, name : "M. Tagnum", "assignment" : 5, "points" : 30 }, { _id: 6319, name : "R. Stiles", "assignment" : 2, "points" : 12 }, { _id: 6322, name : "A. MacDyver", "assignment" : 2, "points" : 14 }, { _id: 6234, name : "R. Stiles", "assignment" : 1, "points" : 10 } ] )
The following operation first finds all documents where
name : "A. MacDyver"
. It then sorts by points
ascending before
deleting the document with the lowest points value:
db.scores.findOneAndDelete( { "name" : "A. MacDyver" }, { sort : { "points" : 1 } } )
The operation returns the original document that has been deleted:
{ _id: 6322, name: "A. MacDyver", "assignment" : 2, "points" : 14 }
Projecting the Deleted Document
The following operation uses projection to only return the _id
and
assignment
fields in the returned document:
db.scores.findOneAndDelete( { "name" : "A. MacDyver" }, { sort : { "points" : 1 }, projection: { "assignment" : 1 } } )
The operation returns the original document with the
assignment
and _id
fields:
{ _id: 6322, "assignment" : 2 }
Atualizar documento com limite de tempo
The following operation sets a 5ms time limit to complete the deletion:
try { db.scores.findOneAndDelete( { "name" : "A. MacDyver" }, { sort : { "points" : 1 }, maxTimeMS : 5 } ) } catch(e){ print(e) }
Se a operação exceder o limite de tempo, ela retornará:
MongoServerError: operation exceeded time limit: { "ok": 0, "code" : 50, "codeName" : "MaxTimeMSExpired" }
Observação
This error message has been shortened for brevity.
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:
db.myColl.insertMany( [ { _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.findOneAndDelete( { category: "cafe", status: "a" }, { collation: { locale: "fr", strength: 1 } } );
A operação retorna o seguinte documento:
{ "_id" : 1, "category" : "café", "status" : "A" }