MongoDB findOneAndDelete()

In MongoDB the db.collection.findOneAndDelete() method deletes a single document, and returns the deleted document.

It deletes the first matching document in the collection that matches the filter. The sort parameter can be used to influence which document is deleted.

The collection part is the name of the collection with which to delete the document from.

Example

Suppose we have a collection called pets that contains the following documents:

{ "_id" : 1, "name" : "Wag", "type" : "Dog", "weight" : 20 }
{ "_id" : 2, "name" : "Bark", "type" : "Dog", "weight" : 10 }
{ "_id" : 3, "name" : "Meow", "type" : "Cat", "weight" : 7 }
{ "_id" : 4, "name" : "Scratch", "type" : "Cat", "weight" : 8 }
{ "_id" : 5, "name" : "Bruce", "type" : "Bat", "weight" : 3 }
{ "_id" : 6, "name" : "Fetch", "type" : "Dog", "specs" : { "height" : 400, "weight" : 15, "color" : "brown" } }
{ "_id" : 7, "name" : "Jake", "type" : "Dog", "awards" : [ "Top Dog", "Best Dog", "Biggest Dog" ] }

We can use the db.collection.findOneAndDelete() method to delete one of those documents.

db.pets.findOneAndDelete(
   { "type": "Cat" }
)

Result:

{ "_id" : 3, "name" : "Meow", "type" : "Cat", "weight" : 7 }

In this case I used a query to narrow it to just cats. Only one cat was deleted, even though there are two cats in the collection.

Let’s check the collection.

db.pets.find()

Result:

{ "_id" : 1, "name" : "Wag", "type" : "Dog", "weight" : 20 }
{ "_id" : 2, "name" : "Bark", "type" : "Dog", "weight" : 10 }
{ "_id" : 4, "name" : "Scratch", "type" : "Cat", "weight" : 8 }
{ "_id" : 5, "name" : "Bruce", "type" : "Bat", "weight" : 3 }
{ "_id" : 6, "name" : "Fetch", "type" : "Dog", "specs" : { "height" : 400, "weight" : 15, "color" : "brown" } }
{ "_id" : 7, "name" : "Jake", "type" : "Dog", "awards" : [ "Top Dog", "Best Dog", "Biggest Dog" ] }

We can see that the first cat (document 3) has been deleted.

Embedded Documents

If you have documents that contain embedded documents, you can use the following methods to query data in the embedded documents.

Dot notation (e.g. field.nestedfield: <value>)
Nested form (e.g. { field: { nestedfield: <value> } }). Note that this option is only available from MongoDB 4.4.

Here’s an example that uses dot notation to query within the embedded document.

db.pets.findOneAndDelete({ "specs.height": 400 })

Result:

{
	"_id" : 6,
	"name" : "Fetch",
	"type" : "Dog",
	"specs" : {
		"height" : 400,
		"weight" : 15,
		"color" : "brown"
	}
}

As expected, document 6 was deleted.

The following query deletes the same document, but in this case it uses nested form to refer to the embedded document.

db.pets.findOneAndDelete({ 
    "specs" : {
		"height" : 400,
		"weight" : 15,
		"color" : "brown"
	}
 })

When using the nested form, the query must match whole embedded document exactly. For example, the following query doesn’t match:

db.pets.findOneAndDelete({ 
    "specs" : {
		"height" : 400
	}
 })

Result:

null

Arrays

You can reference data in arrays by referencing the array element by its index or by its value.

If we wanted to delete all dogs with the Top Dog award, we could write the following query (which will return the above dog).

db.pets.findOneAndDelete({ 
    "awards": "Top Dog"
})

Result:

{
	"_id" : 7,
	"name" : "Jake",
	"type" : "Dog",
	"awards" : [
		"Top Dog",
		"Best Dog",
		"Biggest Dog"
	]
}

You can also specify the element index, like this:

db.pets.findOneAndDelete({ 
    "awards.0": "Top Dog"
})

Doing that requires that the specified value is at the specified index. Therefore, the following query does not return the same dog.

db.pets.findOneAndDelete({ 
    "awards.1": "Top Dog"
})

Note that arrays are zero-based, so an index of 0 specifies the first element, 1 specifies the second element, and so on.

The `sort` Parameter

You can use the sort parameter to specify a sorting order for the documents matched by the filter. This will influence which document is deleted.

When using the sort parameter, a value of 1 sorts the documents into ascending order, and a value of -1 sorts them into descending order.

The argument needs to be provided as a document. For example, { sort: { "salary": 1 } } sorts by the salary field in ascending order.

For example, suppose we create a collection called employees with the following documents:

db.employees.insertMany([
    { _id: 1, name: "Sandy", salary: 55000 },
    { _id: 2, name: "Sarah", salary: 128000 },
    { _id: 3, name: "Fritz", salary: 25000 },
    { _id: 4, name: "Chris", salary: 45000 },
    { _id: 5, name: "Beck", salary: 82000 }
    ])

We could run the following code to find documents with a salary of less than 60000, then delete the one that’s the lowest out of those documents.

db.employees.findOneAndDelete(
   { "salary": { $lt: 60000 } },
   {
       sort: { "salary": 1 }
    }
)

Result:

{ "_id" : 3, "name" : "Fritz", "salary" : 25000 }

As expected, the employee with the lowest salary was deleted.

Here’s what the documents look like now.

db.employees.find()

Result:

{ "_id" : 1, "name" : "Sandy", "salary" : 55000 }
{ "_id" : 2, "name" : "Sarah", "salary" : 128000 }
{ "_id" : 4, "name" : "Chris", "salary" : 45000 }
{ "_id" : 5, "name" : "Beck", "salary" : 82000 }

So we can see that Fritz has been deleted.

Let’s revert it back to the original document.

db.employees.remove({})
db.employees.insertMany([
    { _id: 1, name: "Sandy", salary: 55000 },
    { _id: 2, name: "Sarah", salary: 128000 },
    { _id: 3, name: "Fritz", salary: 25000 },
    { _id: 4, name: "Chris", salary: 45000 },
    { _id: 5, name: "Beck", salary: 82000 }
    ])

Now let’s run the same findOneAndDelete() code again, but this time we’ll sort it in descending order.

db.employees.findOneAndDelete(
   { "salary": { $lt: 60000 } },
   {
       sort: { "salary": -1 }
    }
)

Result:

{ "_id" : 1, "name" : "Sandy", "salary" : 55000 }

This time Sandy was deleted.

Let’s check the collection again.

db.employees.find()

Result:

{ "_id" : 2, "name" : "Sarah", "salary" : 128000 }
{ "_id" : 3, "name" : "Fritz", "salary" : 25000 }
{ "_id" : 4, "name" : "Chris", "salary" : 45000 }
{ "_id" : 5, "name" : "Beck", "salary" : 82000 }

As expected, Sandy is no longer in the collection.

More Information

The db.collection.findOneAndDelete() method also accepts other parameters, such as projection (to specify a subset of fields to return), maxTimeMS, and collation.

See the MongoDB documentation for more information.

Example

Embedded Documents

Arrays

The sort Parameter

More Information

The `sort` Parameter