Replace Documents

The _id Field

Each document in a MongoDB collection has a unique and immutable _id field. If you attempt to change the _id field through a replace operation, the driver raises a WriteError and performs no updates.

Parameters

The replace_one() method takes the following parameters:

• Query filter to match the document to replace

• Replacement documents that contains the fields and values that will replace an existing document

Replacement documents use the following format:

doc! { "<field>": <value>, "<field>": <value>, ... }

Return Value

The replace_one() method returns an UpdateResult type if the operation is successful. The UpdateResult type contains the following properties that describe the operation:

If multiple documents match the query filter you pass to replace_one(), the method selects and replaces the first matched document. If no documents match the query filter, the replace operation makes no changes.

Replace Example

The following document describes an employee of a company:

{
  "_id": ObjectId('4501'),
  "name": "Matt DeGuy",
  "role": "Consultant",
  "team_members": [ "Jill Gillison", "Susan Lee" ]
}

This example uses the replace_one() method to replace the preceding document with one that has the following fields:

• A name value of "Susan Lee"

• A role value of "Lead Consultant"

• A team_members value of [ "Jill Gillison" ]

let replace_doc = doc! {
    "name": "Susan Lee",
    "role": "Lead Consultant",
    "team_members": vec! [ "Jill Gillison" ]
};
let res = my_coll
    .replace_one(doc! { "name": "Matt DeGuy" }, replace_doc)
    .await?;
println!(
    "Matched documents: {}\nModified documents: {}",
    res.matched_count, res.modified_count
);

Matched documents: 1
Modified documents: 1

The replaced document contains the contents of the replacement document and the immutable _id field:

{
  "_id": ObjectId('4501'),
  "name": "Susan Lee",
  "role": "Lead Consultant",
  "team_members": [ "Jill Gillison" ]
}

Full File Example: Replace a Document

This example replaces a document in the restaurants collection of the sample_restaurants database. The replace_one() method replaces the first document in which the value of the name field is "Landmark Coffee Shop" with a new document.

You can access the documents in the restaurants collection as instances of the Document type or a custom data type. To specify which data type represents the collection's data, perform the following actions on the highlighted lines:

• To access collection documents as BSON documents, replace the <T> type parameter with <Document> and the <struct or doc> placeholder with replace_doc.

• To access collection documents as instances of the Restaurant struct, replace the <T> type parameter with <Restaurant> and the <struct or doc> placeholder with replace_struct. The Restaurant struct is defined at the top of the code file.

Select the Asynchronous or Synchronous tab to see the corresponding code for each runtime:

use std::env;
use mongodb::{ bson::doc, Client, Collection };
use serde::{ Deserialize, Serialize };
#[derive(Serialize, Deserialize, Debug)]
struct Restaurant {
    borough: String,
    cuisine: String,
    name: String,
}
#[tokio::main]
async fn main() -> mongodb::error::Result<()> {
    let uri = "<connection string>";
    let client = Client::with_uri_str(uri).await?;
    // Replace <T> with the <Document> or <Restaurant> type parameter
    let my_coll: Collection<T> = client
        .database("sample_restaurants")
        .collection("restaurants");
    let filter = doc! { "name": "Landmark Coffee Shop" };
    let replace_doc = doc! { 
        "borough": "Brooklyn",
        "cuisine": "Café/Coffee/Tea",
        "name": "Harvest Moon Café",
    };
    let replace_struct = Restaurant {
        borough: "Brooklyn".to_string(),
        cuisine: "Café/Coffee/Tea".to_string(),
        name: "Harvest Moon Café".to_string(),
    };
    // Replace <struct or doc> with the replace_struct or replace_doc variable
    let res = my_coll.replace_one(filter, <struct or doc>).await?;
    println!("Replaced documents: {}", res.modified_count);
    Ok(())
}

Replaced documents: 1

use std::env;
use mongodb::{ bson::doc, sync::{ Client, Collection } };
use serde::{ Deserialize, Serialize };
#[derive(Serialize, Deserialize, Debug)]
struct Restaurant {
    borough: String,
    cuisine: String,
    name: String,
}
fn main() -> mongodb::error::Result<()> {
    let uri = "<connection string>";
    let client = Client::with_uri_str(uri)?;
    // Replace <T> with the <Document> or <Restaurant> type parameter
    let my_coll: Collection<T> = client
        .database("sample_restaurants")
        .collection("restaurants");
    let filter = doc! { "name": "Landmark Coffee Shop" };
    let replace_doc = doc! { 
        "borough": "Brooklyn",
        "cuisine": "Café/Coffee/Tea",
        "name": "Harvest Moon Café",
    };
    let replace_struct = Restaurant {
        borough: "Brooklyn".to_string(),
        cuisine: "Café/Coffee/Tea".to_string(),
        name: "Harvest Moon Café".to_string(),
    };
    // Replace <struct or doc> with the replace_struct or replace_doc variable 
    let res = my_coll.replace_one(filter, <struct or doc>).run()?;
    println!("Replaced documents: {}", res.modified_count);
    Ok(())
}

Replaced documents: 1

API Documentation

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

• replace_one()

• UpdateResult

• ReplaceOptions

• WriteError