Docs 菜单

Docs 主页 → 开发应用程序 → MongoDB Manual

$replaceOne（聚合）

在此页面上

  • 定义
  • 语法
  • 行为
  • 例子

定义

$replaceOne

用替换字符串替换输入字符串中搜索字符串的第一个实例。

如果未找到匹配项，则 $replaceOne的计算结果为输入字符串。

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

语法

$replaceOne操作符具有以下操作符表达式语法：

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

Operator 徽标

字段
说明
输入

要应用find的字符串。可以是解析为字符串或null的任何有效表达式。如果input引用缺失的字段，则$replaceOne返回null 。

find

要在给定输入中搜索的字符串。可以是解析为字符串或null的任何有效表达式。如果find引用缺失的字段，则$replaceOne返回null 。

替换

用于替换 input 中 find 的第一个匹配实例的字符串。可以是解析为字符串或 的任何有效 表达式 null。

行为

如果在 input 中未找到匹配的 find$replaceOne 项，则 的计算结果为输入字符串。

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

$replaceOne 和空值

如果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" } }
      }
   }
])

操作返回以下结果：

{ "_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”实例。

← $regexMatch（聚合）
$replaceAll（聚合） →

在此页面上