Delete Documents
On this page
Overview
In this guide, you can learn how to remove documents from your MongoDB collections using delete operations.
This guide includes the following sections:
Sample Data for Examples presents the sample data that is used by the delete operation example
Delete Operations describes how to use the driver to execute delete operations
Additional Information provides links to resources and API documentation for types and methods mentioned in this guide
Sample Data for Examples
The example in this guide uses the following sample documents. Each document represents an item in a store's inventory and contains information about its categorization and unit price:
{ "item": "trowel", "category": "garden", "unit_price": 9.89 }, { "item": "placemat", "category": "kitchen", "unit_price": 3.19 }, { "item": "watering can", "category": "garden", "unit_price": 11.99 }
Delete Operations
The Rust driver provides the delete_one()
and delete_many()
methods to perform delete operations.
Parameters
The delete_one()
and delete_many()
methods take a query filter
as a parameter. A query filter consists of the fields and values that
form criteria for documents to match.
Options
You can modify the behavior of the delete operation methods by chaining
option builder methods to delete_one()
and delete_many()
. These option
methods set DeleteOptions
struct fields.
Note
Setting Options
You can set DeleteOptions
fields by chaining option builder methods directly
to the delete method call. If you're using an earlier version of the driver,
you must construct an DeleteOptions
instance by chaining option builder methods
to the builder()
method. Then, pass your options instance as a parameter to
delete_one()
or delete_many()
.
The following table describes the options available in DeleteOptions
:
Option | Description |
---|---|
collation | The collation to use when sorting results. To learn more about collations,
see the Collations guide. Type: Collation Default: None |
write_concern | The write concern for the operation. If you don't set this
option, the operation inherits the write concern set for
the collection. To learn more about write concerns, see
Write Concern in the
Server manual. Type: WriteConcern |
hint | The index to use for the operation. To learn more about
indexes, see Indexes in the Server
manual. This option is available only when connecting to
MongoDB Server versions 4.4 and later. Type: Hint Default: None |
let_vars | A map of parameters and values. These parameters can be accessed
as variables in aggregation expressions. This option is available
only when connecting to MongoDB Server versions 5.0 and later. Type: Document |
comment | An arbitrary Bson value tied to the operation to trace
it through the database profiler, currentOp , and
logs. This option is available only when connecting to
MongoDB Server versions 4.4 and later.Type: Bson Default: None |
The following code shows how to set the comment
field by chaining
the comment()
method to the delete_one()
method:
let res = my_coll .delete_one(filter) .comment(bson!("hello!")) .await?;
Return Value
The delete_one()
and delete_many()
methods return a
DeleteResult
type. This type contains the deleted_count
property,
which describes the number of documents deleted. If no documents match
the query filter you specified, the delete operation does
not remove any documents, and the value of deleted_count
is 0
.
delete_many() Example
This example performs the following actions:
Calls the
delete_many()
methodPasses a query filter to
delete_many()
that matches documents where the value ofcategory
is"garden"
Chains the
hint()
method todelete_many()
to use the_id_
index as the hint for the delete operation
let filter = doc! { "category": "garden" }; let hint = Hint::Name("_id_".to_string()); let res = my_coll .delete_many(filter) .hint(hint) .await?; println!("Deleted documents: {}", res.deleted_count);
Deleted documents: 2
Note
If you use the delete_one()
method instead of
delete_many()
in the preceding code example, the driver deletes
only the first of the two documents that match the query filter.
Additional Information
For runnable examples of the delete operations, see the following usage examples:
To learn more about the operations in this guide, see the following documentation:
Specify a Query guide
Collations guide
API Documentation
To learn more about the methods and types mentioned in this guide, see the following API documentation: