MongoDB聚合运算符：$replaceOne

$replaceOne聚合运算在输入的字符串中搜索目标字符串，并使用指定的字符串替换第一次找到的目标字符串。如果没有找到目标字符串，则返回输入字符串。 $replaceOne既区分大小写又区分变音符号，并且忽略集合中存在的任何排序规则。

语法

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

参数字段说明

• input：输入的字符串，可以是任何可被解析为字符串的表达式，如果表达式解析为null或引用的字段不存在，$replaceOne返回null。
• find：要搜索的字符串，可以是任何可被解析为字符串的表达式，如果表达式解析为null或引用的字段不存在，$replaceOne返回null。
• replacement：要替换的的字符串，可以是任何可被解析为字符串或null的表达式。

使用

如果在input中未找到 find，则 $replaceOne 计算结果为input字符串。

输入、查找和替换表达式的计算结果必须为字符串或 null，否则 $replaceOne 会失败并出现错误。

$replaceOne 与 Null

如果 input 或 find 引用的字段字段不存在，则返回 null。

如果 input、find 或 replacement 中的任何一个计算结果为 null，则整个 $replaceOne 表达式计算结果为 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( "myColl", { collation: { locale: "fr", strength: 1 } } )

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

接下来，插入三个示例文档：

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

以下 $replaceOne 操作尝试查找并替换name字段中"Cafe"的第一个实例：

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

由于 $replaceOne 忽略为此集合的排序规则，因此该操作仅匹配文档 2 中的"Cafe"实例：

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

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

$replaceOne 和 Unicode 规范化

$replaceOne 聚合表达式不执行任何 unicode 规范化。这意味着所有 $replaceOne 表达式的字符串匹配在尝试匹配时将考虑用于表示unicode中的字符代码点的数量。

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

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

将 $replaceOne 与查找字符串一起使用，其中字符 é 以带有一个代码点的 unicode 表示，将不会匹配在输入字符串中使用两个代码点的任何 é 实例。
下表显示了与其中 é 由一个或两个代码点表示的输入字符串相比，"café"的查找字符串是否发生匹配。本示例中的查找字符串使用一个代码点来表示 é 字符：

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

因为 $replaceOne 不执行任何 unicode 规范化，所以只有第一个字符串比较匹配，其中查找字符串和输入字符串都使用一个代码点来表示 é。

举例

使用下面的脚本创建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" },
])

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

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

操作返回下面的结果，请意，对于文档 3，仅替换第一个匹配的"bluepaint"实例。：

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