Docs Menu
Docs Home
/ / /
Rust Driver
/ /

Compound Operations

On this page

  • Overview
  • Sample Data for Examples
  • Find and Delete a Document
  • Modify Find and Delete Behavior
  • Find and Delete Example
  • Find and Update a Document
  • Modify Find and Update Behavior
  • Find and Update Example
  • Find and Replace a Document
  • Modify Find and Replace Behavior
  • Find and Replace Example
  • Additional Information
  • API Documentation

In this guide, you can learn how to use the Rust driver to perform compound operations.

Compound operations combine the functionality of read and write operations into one atomic action. If you perform a read operation and a write operation in sequence, someone might change your target document between the operations, leading to unexpected results. When you perform a compound operation, MongoDB prevents intermediate data changes by placing a write lock on the document you are modifying until the operation completes.

You can perform the following compound operations with the driver:

  • Find and delete one document

  • Find and update one document

  • Find and replace one document

This guide includes the following sections:

Tip

To learn how to perform atomic read and write operations on more than one document at a time, see the Transactions guide.

The examples in this guide use the following sample documents. Each document represents a student and contains information about their age and the school that they attend:

{ "name": "Alex Johnson", "age": 8, "school": "Lakeside Elementary" },
{ "name": "Samara Khan", "age": 11, "school": "Rolling Hills Middle School" },
{ "name": "Ben Joseph", "age": 16, "school": "Aurora High School" },
{ "name": "Deanna Porowski", "age": 10, "school": "Lakeside Elementary" }

The find_one_and_delete() method finds and deletes the first document that matches the specified query filter. If a document matches the filter criteria, the method returns a Some type. If no documents match, it returns a None type.

Note

If you want to perform other operations between finding and deleting a document, you can call the find_one() method followed by the delete_one() method.

You can optionally modify the behavior of the find_one_and_delete() method by passing a FineOneAndDeleteOptions instance as a parameter. To use default values for each setting, specify the value None for the options parameter.

The following table describes the options available in FineOneAndDeleteOptions:

Option
Description
max_time
The maximum amount of time in milliseconds that the query can run.

Type: Duration
projection
The projection to use when returning results.

Type: Document
Default: None
sort
The sorting order to use when returning results. By default, the driver returns documents in their natural order, or as they appear in the database. To learn more, see natural order in the Server manual glossary.

Type: Document
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
collation
The collation to use when sorting results. To learn more about collations, see the Collations guide.

Type: Collation
Default: None
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. You can access these parameters 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 Rust driver implements the Builder design pattern for the creation of a FindOneAndDeleteOptions instance. You can use the type's builder() method to construct an options instance by chaining option builder functions one at a time.

The following code shows how to construct a FindOneAndDeleteOptions instance and pass it to the find_one_and_delete() method:

let opts = FindOneAndDeleteOptions::builder().comment(bson!("hello")).build();
let res = my_coll.find_one_and_delete(filter, opts).await?;

The following example uses the find_one_and_delete() method to match and delete the first document where the value of the age field is less than or equal to 10:

let filter = doc! { "age": doc! { "$lte": 10 } };
let res = my_coll.find_one_and_delete(filter, None).await?;
println!("Deleted document:\n{:?}", res);

The find_one_and_update() method finds and updates the first document that matches the specified query filter. The operation updates the document based on the specifications you provide in an update document. If a document matches the filter criteria, the method returns a Some type. If no documents match, it returns a None type.

Note

If you want to perform other operations between finding and updating a document, you can call the find_one() method followed by the update_one() method.

You can optionally modify the behavior of the find_one_and_update() method by passing a FindOneAndUpdateOptions instance as a parameter. To use default values for each setting, specify the value None for the options parameter.

The following table describes the options available in FineOneAndDeleteOptions:

Option
Description
array_filters
The set of filters specifying the array elements to which the update applies.

Type: Vec<Document>
bypass_document_validation
If true, allows the driver to perform a write that violates document-level validation. To learn more about validation, see Schema Validation in the Server manual.

Type: bool
Default: false
max_time
The maximum amount of time in milliseconds that the query can run.

Type: Duration
projection
The projection to use when returning results.

Type: Document
Default: None
return_document
If Before, the operation returns the document before the update. If After, the operation returns the updated document.

Type: ReturnDocument
Default: ReturnDocument::Before
sort
The sorting order to use when returning results. By default, the driver returns documents in their natural order, or as they appear in the database. To learn more, see natural order in the Server manual glossary.

Type: Document
Default: None
upsert
If true, the operation inserts a document if no documents match the query filter.

Type: bool
Default: false
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
collation
The collation to use when sorting results. To learn more about collations, see the Collations guide.

Type: Collation
Default: None
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. You can access these parameters 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 Rust driver implements the Builder design pattern for the creation of a FindOneAndUpdateOptions instance. You can use the type's builder() method to construct an options instance by chaining option builder methods one at a time.

The following code shows how to construct a FindOneAndUpdateOptions instance and pass it to the find_one_and_update() method:

let opts = FindOneAndUpdateOptions::builder().comment(bson!("hello")).build();
let res = my_coll.find_one_and_update(filter, update, opts).await?;

This example shows how to call the find_one_and_update() method with the following parameters:

  • A query filter that matches a document where the value of school is "Aurora High School"

  • An update document that sets the school field to "Durango High School" and increments the age field by 1

  • A FindOneAndUpdateOptions instance that returns the document after the update

let filter = doc! { "school": "Aurora High School" };
let update =
doc! { "$set": doc! { "school": "Durango High School" },
"$inc": doc! { "age": 1 } };
let opts = FindOneAndUpdateOptions::builder()
.return_document(Some(ReturnDocument::After))
.build();
let res = my_coll.find_one_and_update(filter, update, opts).await?;
println!("Updated document:\n{:?}", res);

The find_one_and_replace() method finds and replaces the first document that matches the specified query filter. The operation replaces all the fields of the document except the _id field with fields and values that you provide. If a document matches the filter criteria, the method returns a Some type. If no documents match, it returns a None type.

Note

If you want to perform other operations between finding and replacing a document, you can call the find_one() method followed by the replace_one() method.

You can optionally modify the behavior of the find_one_and_replace() method by passing a FindOneAndReplaceOptions instance as a parameter. To use default values for each setting, specify the value None for the options parameter.

The following table describes the options available in FindOneAndReplaceOptions:

Option
Description
bypass_document_validation
If true, allows the driver to perform a write that violates document-level validation. To learn more about validation, see Schema Validation in the Server manual.

Type: bool
Default: false
max_time
The maximum amount of time in milliseconds that the query can run.

Type: Duration
projection
The projection to use when returning results.

Type: Document
Default: None
return_document
If Before, the operation returns the document before the update. If After, the operation returns the updated document.

Type: ReturnDocument
Default: ReturnDocument::Before
sort
The sorting order to use when returning results. By default, the driver returns documents in their natural order, or as they appear in the database. To learn more, see natural order in the Server manual glossary.

Type: Document
Default: None
upsert
If true, the operation inserts a document if no documents match the query filter.

Type: bool
Default: false
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
collation
The collation to use when sorting results. To learn more about collations, see the Collations guide.

Type: Collation
Default: None
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. You can access these parameters 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 Rust driver implements the Builder design pattern for the creation of a FindOneAndReplaceOptions instance. You can use the type's builder() method to construct an options instance by chaining option builder functions one at a time.

The following code shows how to construct a FindOneAndReplaceOptions instance and pass it to the find_one_and_replace() method:

let opts = FindOneAndReplaceOptions::builder().comment(bson!("hello")).build();
let res = my_coll.find_one_and_replace(filter, replacement, opts).await?;

This example shows how to call the find_one_and_replace() method with the following parameters:

  • A query filter that matches a document where the value of name includes the string "Johnson"

  • A replacement document that describes a new student

  • A FindOneAndReplaceOptions instance that returns the document after replacement and projects only the name and school fields in the output

let filter = doc! { "name": doc! { "$regex": "Johnson" } };
let replacement =
doc! { "name": "Toby Fletcher",
"age": 14,
"school": "Durango High School" };
let opts = FindOneAndReplaceOptions::builder()
.return_document(Some(ReturnDocument::After))
.projection(doc! { "name": 1, "school": 1, "_id": 0 })
.build();
let res = my_coll.find_one_and_replace(filter, replacement, opts).await?;
println!("Document after replacement:\n{:?}", res);

To learn more about the operations in this guide, see the following documentation:

To learn more about the methods and types mentioned in this guide, see the following API documentation:

← Delete Documents