Learn how to remove and replace documents in MongoDB.

CRUD II: Deleting Documents

Great job! Let's go over a quick summary of what we've learned about deleting in MongoDB:

- The `.deleteOne()` method deletes a single document from a collection. It accepts a filter document specifying which document to delete as the first parameter.

- The `.deleteOne()` method will only delete the *first* matching document in the collection.

- The `.deleteMany()` method deletes all matching documents from a collection. It accepts a filter document specifying which document to delete as the first parameter.

- The `.replaceOne()` method replaces an entire document from a collection. It takes in filtering criteria specifying the document to replace as the first parameter and a replacement document as the second one.

- The `.replaceOne()` method will only replace the *first* matching document in the collection.

- Since `.replaceOne()` replaces an entire document, only fields included in the second parameter will be present in the document after the operation executes.

In addition to the syntax we’ve learned throughout this lesson, MongoDB offers us other syntax and commands that can be useful when deleting or replacing documents:

- The [`.findOneAndReplace()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.findOneAndReplace/?utm_campaign=academia_partners&utm_source=codecademy&utm_medium=referral) method is very similar to `.replaceOne()`. It replaces a document in a collection based on filter criteria, but instead of returning a document that acknowledges the operation, it returns either the original document or the replacement document.
- The [`.findOneAndDelete()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.findOneAndDelete/?utm_campaign=academia_partners&utm_source=codecademy&utm_medium=referral) method deletes a document, and returns the deleted document.

Congrats! You've learned a lot in the past exercises. Now you can use your knowledge and experiment with the provided collection!

Review

So far we have learned how to **C**reate, **R**ead, and **U**pdate data using different methods provided by MongoDB. Let's explore the last CRUD operation, **D**elete. 

There are certain situations when data is no longer necessary or becomes obsolete. MongoDB provides us a couple options to permanently remove unwanted documents from a collection. In this exercise, we'll focus on learning how to use the [`.deleteOne()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.deleteOne/?utm_campaign=academia_partners&utm_source=codecademy&utm_medium=referral) method to remove a single document from a collection.

In order to use `.deleteOne()`, we must provide specific filtering criteria to find the document we want to delete. MongoDB will look for the first document in the collection that matches the criteria and delete it. Let's take a closer look at the syntax:

```
db.<collection>.deleteOne(<filter>, <options>);
```

Note in the syntax above, the `.deleteOne()` method takes two arguments: 
- `filter`: A document that provides selection criteria for the document to delete.
- `options`: A document where we can include optional fields to provide more specifications to our operation, such as a [`writeConcern`](https://www.mongodb.com/docs/manual/reference/method/db.collection.deleteOne/?utm_campaign=academia_partners&utm_source=codecademy&utm_medium=referral#std-label-deleteOne-wc). 

To see `.deleteOne()` in action, consider a collection, `monsters`, with the following documents:

```js
{
  _id: ObjectId(...),
  name: "Luca",
  age: 100,
  type: "Hydra"
},
{
  _id: ObjectId(...),
  name: "Lola",
  age: 95,
  type: "Hydra"
},
{
  _id: ObjectId(...),
  name: "Igor",
  age: 95,
  type: "Chimera"
},
```

If we want to delete a single monster with an age of `95`, we can run the following command:

```js
db.monsters.deleteOne({ age: 95 });
```

If the command is successful, MongoDB will confirm the document was deleted with the following output:

```js
{ acknowledged: true, deletedCount: 1 }
```

The collection would then be left with these remaining documents: 

```js
{
  _id: ObjectId(...),
  Name: "Luca",
  age: 100,
  type: "Hydra"
},
{
  _id: ObjectId(...),
  name: "Igor",
  age: 95,
  type: "Chimera"
},
```

Notice that only one of the documents in the collection with the `age` of `95` was deleted. When the filter criteria is non-unique, the document that gets deleted is the first one that MongoDB identifies when performing the operation. Which document is found first depends on several factors which can include insertion order and the presence of indexes relevant to the filter.

In the following exercises, we'll practice using the `.deleteOne()` method with the same collection from the previous lesson, `restaurants`.

Deleting a Document

We might encounter situations where we need to delete a document and immediately replace it with another one. We could achieve this by running two separate methods, `.deleteOne()`, then `.insertOne()`.  Fortunately,  MongoDB provides us with a single method, `.replaceOne()`, that can both delete and insert all at once! 

The [`.replaceOne()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.replaceOne/?utm_campaign=academia_partners&utm_source=codecademy&utm_medium=referral/) method replaces the first document in a collection that matches the given filter. The syntax for this method looks as follows:

```
db.<collection>.replaceOne(
  <filter>, 
  <replacement>, 
  <options>
);
```
Note in the syntax above that the `.replaceOne()` method takes three arguments:

- `filter`: A document that provides selection criteria for the document to replace.
- `replacement`: The replacement document.
- `options`: A document where we can include optional fields to provide more specifications to our operation, such as `upsert`. 

The replacement document can contain a subset of fields of the original document or entirely unique fields. To see it in action, consider a collection named `employees` with the following documents:

```js
{
  _id: ObjectId(...),
  name: "Rohit Kohli",
  department: "Customer Analytics"
  position: "Senior Software Engineer"
},
{
  _id: ObjectId(...),
  name: "Rin Paterson",
  department: "People Operations",
  position: "Head of People Operations"
}
```
Imagine `"Rohit Kohli"` leaves the company. We still want to store their name, and update their position to `"N/A"` but no longer need a `department` field and value. We'd then need to replace Rohit's current document with a new document that only contains two fields: `name`, and `position`. We can accomplish this with `.replaceOne()`:

```js
db.employees.replaceOne(
  { name: "Rhoit Kohli" }, 
  { name: "Rohit Kohli", position: "N/A" }
);
```
If successful, this would produce the following output:

```js
{
  acknowledged: true,
  insertedId: null,
  matchedCount: 1,
  modifiedCount: 1,
  upsertedCount: 0
}
```

After running this command, we'd be left with the following collection:

```js
{
  _id: ObjectId(...),
  name: "Rohit Kohli",
  position: "N/A"
},
{
  _id: ObjectId(...),
  name: "Gary Paterson",
  department: "HR",
  position: "Head of Human Resources"
}
```

Notice how the other fields were completely removed. This is the key difference between `.replaceOne()` and `.updateOne()`. Whereas `.updateOne()` updates specific fields based on the update modifiers provided, `.replaceOne()` replaces the entire document and will only include fields specified in the `<replacement>` parameter. 

Now let's practice what we've learned about `.replaceOne()` with the following exercises.

Replacing a Document

We now know how to delete a single document from a collection, but what if we want to delete multiple documents that match certain criteria? We can accomplish this with the `.deleteMany()` method. 

The [`.deleteMany()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.deleteMany/?utm_campaign=academia_partners&utm_source=codecademy&utm_medium=referral) method removes all documents from a collection that match a given filter. This method uses the following syntax:

```
db.<collection>.deleteMany(<filter>, <options>);
```
Note in the syntax above that the `.deleteMany()` method takes two arguments:
- `filter`: A document that provides selection criteria for the documents to delete.
- `options`: A document where we can include optional fields to provide more specifications to our operation, such as a `writeConcern`.

> Warning: If no filter is provided to the `.deleteMany()` method, all documents from the collection will be deleted. 

Let's revisit the original `monsters` collection from the previous exercise. Consider a new monster with the name of `"Pat"` was recently added:

```js
{
  _id: ObjectId("629a1e8c2bf029cc101c92d4"),
  name: "Luca",
  age: 100,
  type: "Hydra"
},
{
  _id: ObjectId("629a2245b8bd9cad32a210fa"),
  name: "Lola",
  age: 95,
  type: "Hydra"
},
{
  _id: ObjectId("629a225119915a53df5b428c"),
  name: "Igor",
  age: 85,
  type: "Hydra"
},
{
  _id: ObjectId("629a226c8982a4dd04e093ff"),
  name: "Pat",
  age: 85,
  type: "Dragon"
}
```

We now want to get rid of all the monsters with a `type` field with the value of `"Hydra"`. We could run the `.deleteOne()` method and pass in the filter `{type: "Hydra"}`, but we would need to execute the method multiple times. This could quickly get very tedious. Instead, let's use `.deleteMany()`:

```js
db.monsters.deleteMany({ type: "Hydra" });
```

Once executed, the operation will successfully delete all documents where the `type` field has the value of `"Hydra"`. MongoDB will confirm if the operation was successful and let us know how many documents were deleted with the following output:

```js
{ acknowledged: true, deletedCount: 3 }
```

This would leave us with a single remaining document:

```js
{
  _id: ObjectId("629a226c8982a4dd04e093ff"),
  name: "Pat",
  age: 85,
  type: "Dragon"
} 
```

Now that we've gotten familiar with the `.deleteMany()` method, let's get some practice with it.