Menu Docs

db.collection.findOneAndDelete()

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:

db.collection.findOneAndDelete( filter, options )

Deletes a single document based on the filter and sort 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âmetro
Tipo
Descrição

filter

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.

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

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.

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,

O parâmetro projection obtém um documento no seguinte formato:

{ field1: <value>, field2: <value> ... }
Projeção
Descrição

<field>: <1 or true>

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 true.

<field>: <0 or false>

Especifica a exclusão de um campo.

"<field>.$": <1 or true>

Usa o operador de projeção de array $ para retornar o primeiro elemento que corresponde à condição de consulta no campo de array. Se você especificar um número inteiro diferente de zero para o valor de projeção, a operação tratará o valor como true.

Não disponível para visualizações.

<field>: <array projection>

Usa os operadores de projeção de array ($elemMatch, $slice) para especificar os elementos da array a serem incluídos.

Não disponível para visualizações.

<field>: <aggregation expression>

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.

  • Se você especificar um literal não numérico e não booleano (como uma string literal ou uma array ou uma expressão de operador) para o valor de projeção, o campo será projetado com o novo valor, por exemplo:

    • { field: [ 1, 2, 3, "$someExistingField" ] }

    • { field: "New String Value" }

    • { field: { status: "Active", total: { $sum: "$existingArray" } } }

  • Para projetar um valor literal para um campo, use a expressão de aggregation $literal, por exemplo:

    • { field: { $literal: 5 } }

    • { field: { $literal: true } }

    • { field: { $literal: { fieldWithValue0: 0, fieldWithValue1: 1 } } }

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> } }

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.

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:

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

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.

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.

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 }

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 in w: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 for w 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.

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 }

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 }

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.

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" }