/ /

$replaceOne（表达式操作符）

定义

$replaceOne

用替换string替换input string中搜索string或正则表达式模式的第一个实例。

If no occurrences are found, $replaceOne evaluates to the input string.

$replaceOne 区分大小写，区分变音符号，忽略集合上存在的任何排序规则。

语法

The $replaceOne operator has the following operator expression syntax:

{ $replaceOne: { input: <expression>, find: <expression>, replacement: <expression> } }

Operator 徽标

字段	说明
输入	The string on which you wish to apply the find. Can be any valid expression that resolves to a string or a `null`. If `input` refers to a field that is missing, `$replaceOne` returns `null`.
find	The string to search for within the given input. Can be any valid expression that resolves to a string, a regex, or a `null`. If `find` refers to a missing field, `$replaceOne` returns `null`.
替换	The string to use to replace the first matched instance of find in input. Can be any valid expression that resolves to a string or a `null`.

行为

If no occurrences of find are found in input, $replaceOne evaluates to the input string.

The input, find, and replacement expressions must evaluate to one of the following output types:

字符串
null
A regex for find operations

Otherwise, $replaceOne fails with an error.

`$replaceOne` 和空值

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: { input: null, find: "abc", replacement: "ABC" } }`	`null`
`{ $replaceOne: { input: "abc", find: null, replacement: "ABC" } }`	`null`
`{ $replaceOne: { input: "abc", find: "abc", replacement: null } }`	`null`

$replaceOne 和排序规则

$replaceOne 表达式的字符串匹配始终区分大小写和变音符号。使用 $replaceOne 执行字符串比较时，配置的任何排序规则都将被忽略。

例如，创建一个排序规则强度为 1 的样本集合：

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

排序规则强度 1 仅比较基本字符并忽略其他差异，例如大小写和变音符号。

接下来，插入示例文档：

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.

由于该集合的排序规则强度为 1，因此遵循排序规则的操作符（例如 $match）在与“Cafe”执行字符串比较时会匹配所有三个文档。

`$replaceOne` 与 Unicode 规范化

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.

例如，字符é可以使用一个或两个代码点以 unicode 表示：

Unicode	显示为	代码点
`\xe9`	`é`	1 ( `\xe9` )
`e\u0301`	`é`	2 ( `e` + `\u0301` )

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:

例子	匹配
`{ $replaceOne: { input: "caf\xe9", find: "café", replacement: "CAFE" } }`	是
`{ $replaceOne: { input: "cafe\u0301", find: "café", replacement: "CAFE" } }`	no

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 é.

示例

使用以下文档创建 inventory 集合：

db.inventory.insertMany( [
   { _id: 1, item: "blue paint" },
   { _id: 2, item: "blue and green paint" },
   { _id: 3, item: "blue paint with blue paintbrush" },
   { _id: 4, item: "blue paint with green paintbrush" },
] )

Replace Using a string

以下示例将 item 字段中“blue paint”的第一个实例替换为“red paint”：

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

操作返回以下结果：

{ _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" }

请注意，对于文档 3 ，仅替换第一个匹配的“bluepaint”实例。

使用正则表达式替换

以下示例将 item字段中整个单词“blue”的第一个实例替换为“navy”：

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

操作返回以下结果：

{ _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" }

请注意，对于document 3，仅替换“blue”的第一个匹配实例。