db.collection.findOneAndDelete()

Document Match

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.

Projection

The projection parameter takes a document in the following form:

{ field1: <value>, field2: <value> ... }

Sharded Collections

When using db.collection.findOneAndDelete() against a sharded collection, the query must contain an equality condition on shard key.

Documents in a sharded collection can be missing the shard key fields. To target a document that is missing the shard key, you can use the null equality match in conjunction with another filter condition (such as on the _id field). For example:

{ _id: <value>, <shardkeyfield>: null } // _id of the document missing shard key

Transactions

db.collection.findOneAndDelete() can be used inside distributed transactions.

Do not explicitly set the write concern for the operation if run in a transaction. To use write concern with transactions, see Transactions and Write Concern.

Oplog Entries

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.

Delete A Document

The scores collection contains documents similar to the following:

 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

The scores collection contains documents similar to the following:

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

The operation returns the following document:

{ _id: 6305, name: 'A. MacDyver', assignment: 5, points: 24 }

The document is deleted with the writeConcern options specified.

Sort And Delete A Document

The scores collection contains documents similar to the following:

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 }

Update Document with Time Limit

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

If the operation exceeds the time limit, it returns:

MongoServerError: operation exceeded time limit: { "ok": 0, "code" : 50, "codeName" : "MaxTimeMSExpired" }

Specify Collation

Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.

A collection myColl has the following documents:

db.myColl.insertMany( [
   { _id: 1, category: "café", status: "A" },
   { _id: 2, category: "cafe", status: "a" },
   { _id: 3, category: "cafE", status: "a" }
] )

The following operation includes the collation option:

db.myColl.findOneAndDelete(
   { category: "cafe", status: "a" },
   { collation: { locale: "fr", strength: 1 } }
);

The operation returns the following document:

{ "_id" : 1, "category" : "café", "status" : "A" }