$replaceOne (aggregation)

Operator Fields

$replaceOne and Null Values

If input or find refer to a field that is missing, they return null.

If any one of input, find, or replacement evaluates to a null, the entire $replaceOne expression evaluates to null:

$replaceOne and Collation

String matching for $replaceOne expressions is always case-sensitive and diacritic-sensitive. Any collation configured is ignored when performing string comparisons with $replaceOne.

For example, create a sample collection with collation strength 1:

db.createCollection( "restaurants", { collation: { locale: "fr", strength: 1 } } )

A collation strength of 1 compares base character only and ignores other differences such as case and diacritics.

Next, insert example documents:

db.restaurants.insertMany( [
   { _id: 1, name: "cafe" },
   { _id: 2, name: "Cafe" },
   { _id: 3, name: "café" }
] )

The following $replaceOne operation tries to find and replace the first instance of "Cafe" in the name field:

db.restaurants.aggregate( [
{
   $addFields:
      {
         resultObject: {
            $replaceOne: {
               input: "$name",
               find: "Cafe",
               replacement: "CAFE"
            }
         }
      }
}
] )

{ "_id" : 1, "name" : "cafe", "resultObject" : "cafe" }
{ "_id" : 2, "name" : "Cafe", "resultObject" : "CAFE" }
{ "_id" : 3, "name" : "café", "resultObject" : "café" }

Because $replaceOne ignores the collation configured for this collection, the operation only matches the instance of "Cafe" in document 2.

Operators that respect collation, such as $match, would match all three documents when performing a string comparison against "Cafe" due to this collection's collation strength of 1.

$replaceOne and Unicode Normalization

The $replaceOne aggregation expression does not perform any unicode normalization. This means that string matching for all $replaceOne expressions will consider the number of code points used to represent a character in unicode when attempting a match.

For example, the character é can be represented in unicode using either one code point or two:

Using $replaceOne with a find string where the character é is represented in unicode with one code point will not match any instance of é that uses two code points in the input string.

The following table shows whether a match occurs for a find string of "café" when compared to input strings where é is represented by either one code point or two. The find string in this example uses one code point to represent the é character:

Because $replaceOne does not perform any unicode normalization, only the first string comparison matches, where both the find and input strings use one code point to represent é.

Replace Using a String

The following example replaces the first instance of "blue paint" in the item field with "red paint":

db.inventory.aggregate([
   {
     $project:
      {
         item: { $replaceOne: { input: "$item", find: "blue paint", replacement: "red paint" } }
      }
   }
])

The operation returns the following results:

{ _id: 1, item: "red paint" }
{ _id: 2, item: "blue and green paint" }
{ _id: 3, item: "red paint with blue paintbrush" }
{ _id: 4, item: "red paint with green paintbrush" }

Replace Using Regex

The following example replaces the first instance of "blue" as a whole word in the item field with "navy":

db.inventory.aggregate([
   {
     $project:
      {
         item: { $replaceOne: { input: "$item", find: \\bblue\\b, replacement: "navy" } }
      }
   }
]);

The operation returns the following results:

{ _id: 1, item: "navy paint" }
{ _id: 2, item: "navy and green paint" }
{ _id: 3, item: "navy paint with blue paintbrush" }
{ _id: 4, item: "navy paint with green paintbrush" }