update 事件

文档前期图像和期后图像

从 MongoDB 6.0 开始，如果执行以下步骤，您会看到 fullDocumentBeforeChange 文档，其中包含更改（或删除）文档之前的字段：

1. 使用 db.createCollection()、create 或 collMod 为集合启用新的 changeStreamPreAndPostImages 字段。

2. 在 db.collection.watch() 中将 fullDocumentBeforeChange 设置为 "required" 或 "whenAvailable"。

变更流输出中的示例 fullDocumentBeforeChange 文档：

"fullDocumentBeforeChange" : {
   "_id" : ObjectId("599af247bb69cd89961c986d"),
   "userName" : "alice123",
   "name" : "Alice Smith"
}

有关变更流输出的完整示例，请参阅使用文档前像和后像的变更流。

如果图像属于以下情况，则前像和后像不可用于变更流事件：

• 在文档更新或删除操作时未对集合启用。

• 在 expireAfterSeconds 中设置的前像和后像保留时间后之后被删除。

  • 以下示例将整个集群上的 expireAfterSeconds 设置为 100 秒：

    use admin
    db.runCommand( {
       setClusterParameter:
          { changeStreamOptions: {
             preAndPostImages: { expireAfterSeconds: 100 }
          } }
    } )

    注意

    MongoDB Atlas集群不支持 setClusterParameter 命令。有关Atlas支持所有命令的信息，请参阅Atlas集群中不支持的命令。

  • 以下示例返回当前的 changeStreamOptions 设置，包括 expireAfterSeconds：

    db.adminCommand( { getClusterParameter: "changeStreamOptions" } )

  • 将 expireAfterSeconds 设置为 off 可使用默认保留策略：将保留前像和后像，直到从 oplog 中删除对应的变更流事件。

  • 如果变更流事件从 oplog 中删除，则无论 expireAfterSeconds 前映像和后映像保留时间如何，相应的前映像和后映像也会被删除。

其他考量：

• 启用前像和后像会占用存储空间并增加处理时间。仅在需要时启用前像和后像。

• 将变更流事件大小限制为小于 16 MiB。要限制事件大小，您可以：

  • 将文档大小限制为 8 MB。如果其他 change stream 事件字段（例如 updateDescription）不是很大，则可以在 change stream 输出中同时请求更新前的文档和更新后的文档。

  • 如果其他变更流事件字段（例如 updateDescription）并不大，则仅请求变更流输出中最多 16 MiB 的文档的后像。

  • 在以下情况下，仅请求变更流输出中最多 16 MiB 的文档的前像：

    • 文档更新仅影响文档结构或内容的一小部分，且

    • 不会引起 replace 变更事件。replace 事件始终包含后像。

• 要请求前图像，请在db.collection.watch()中将fullDocumentBeforeChange设置为required或whenAvailable。要请求后图像，您可以使用相同的方法设置fullDocument。

• 前像被写入 config.system.preimages 集合。

  • config.system.preimages 集合可能会变大。要限制集合大小，可如前文所示为前映像设置 expireAfterSeconds 时间。

  • 要监控 config.system.preimages 的大小，请连接到分片集群上的分片节点或副本集上的 mongod 节点。然后，运行以下命令：

    use config
    db.system.preimages.totalSize()
    db.system.preimages.stats()

    注意

    您必须对 config.system.preimages 集合拥有 collStats 权限操作才能运行这些命令。

    要在 MongoDB Atlas 部署上运行这些命令，您必须具有 atlasAdmin 角色。

  • 前像由后台进程异步删除。

路径消歧

updateDescription 字段记录操作对文档特定字段所做的变更。这些字段描述符使用点 (.) 作为路径分隔符，使用数字作为数组索引，因此当包含使用点或数字的字段名时，会导致一些歧义。

当 update 事件报告涉及歧义字段的变更时，disambiguatedPaths 文档会为路径键提供数组，列出每个路径组件。

例如，一个列出了人员及其居住城镇的文档：

{
   "name": "Anthony Trollope",
   "home.town": "Oxford",
   "residences": [
      {"0": "Oxford"},
      {"1": "Sunbury"}
   ]
}

• 当更新将 home.town 字段从 Oxford 修改为 London 时，将生成如下所示的更新说明：

  "updateDescription": {
     "updatedFields": {
        "home.town": "London"
     },
     "disambiguatedPaths": {
        "home.town": [ "home.town" ]
     }
  }

  由于字段 home.town 包含一个句点，因此 disambiguatedPaths 字段显示一个只有一个值的数组，以指示 town 不是 home 的子字段。

• 当一项更新修改 residences 数组中的值以进行该变更时，将生成如下所示的更新说明：

  "updateDescription": {
     "updatedFields": {
        "residences.0.0": "London"
     },
     "disambiguatedPaths": { "residences.0.0": [ "residences", 0, "0" ] }
  }

  消除歧义的路径包括整数 0 和字符串 "0"，前者表示数组索引，后者表示嵌套文档中的字段名。

{在两种情况下，disambiguatedPath 不包括数字字段：

• 当路径中的第一个字段是数字字符串时（即 0.name）。这并无歧义，因为第一个字段不能是数组索引。

• 当数字字符串字段带有前导零时（即 0001）。这并无歧义，因为整数不能有前导零。

更新操作

update 命令可以根据它对集合所做的实际更改生成不同的更改事件（而不仅仅是 update）。

标准更新和管道更新的比较

在某些情况下，标准更新和管道更新会为同一逻辑更改生成不同的更改事件。如果在标准更新语法和管道更新语法之间切换，则可能会在应用程序中观察到意外的更改事件。

以下示例展示了从嵌入式文档中删除子字段时，不同的更新语法如何产生不同的更改事件。这只是变更事件因所使用的更新语法而异的众多场景之一。

• 标准更新：删除嵌入式对象的子字段时，删除的路径始终位于 removedFields数组中。

• 管道更新：删除嵌入式对象的子字段时，生成的变更事件会显示最简洁的更新说明。示例：

  • 如果删除了少量子字段（示例，删除 3 个子字段中的 1），则更改会显示在 removedFields数组中。

  • 如果删除了大多数子字段（示例，删除 3 个子字段中的 2），则更改会显示在 updatedFields数组中，并且父对象会反映新状态。

以下示例脚本显示了标准更新和删除对象字段的管道更新生成的不同变更事件：

// 1. Setup collection and insert documents for test cases
let contactMethods = {
   email: "user@example.com",
   phone: "555-0100",
   mobile: "555-0101"
};
db.cstest.drop();
db.cstest.insertMany([
   // Case 1: Remove 1 of 3 subfields
   { _id: "standard_remove_1_of_3", contactMethods: contactMethods },
   { _id: "pipeline_remove_1_of_3", contactMethods: contactMethods },
   // Case 2: Remove 2 of 3 subfields
   { _id: "standard_remove_2_of_3", contactMethods: contactMethods },
   { _id: "pipeline_remove_2_of_3", contactMethods: contactMethods }
]);
// 2. Open a Change Stream
const csCursor = db.cstest.watch();
// --- CASE 1: Remove 1 out of 3 subfields ---
db.cstest.updateOne({ _id: "standard_remove_1_of_3" }, { $unset: { "contactMethods.email": "" } });
db.cstest.updateOne({ _id: "pipeline_remove_1_of_3" }, [{ $unset: "contactMethods.email" }]);
// --- CASE 2: Remove 2 out of 3 subfields ---
db.cstest.updateOne({ _id: "standard_remove_2_of_3" }, { $unset: { "contactMethods.email": "", "contactMethods.phone": "" } });
db.cstest.updateOne({ _id: "pipeline_remove_2_of_3" }, [{ $unset: ["contactMethods.email", "contactMethods.phone"] }]);
// 3. Print the change stream updateDescriptions
print("\n--- Change Stream Results ---");
for (let i = 0; i < 4; i++) {
   if (csCursor.hasNext()) {
      let event = csCursor.next();
      print(`\nOperation: ${event.documentKey._id}`);
      print(JSON.stringify(event.updateDescription));
   }
}
csCursor.close();

--- Change Stream Results ---
Operation: standard_remove_1_of_3
{"updatedFields":{},"removedFields":["contactMethods.email"],"truncatedArrays":[]}
Operation: pipeline_remove_1_of_3
{"updatedFields":{},"removedFields":["contactMethods.email"],"truncatedArrays":[]}
Operation: standard_remove_2_of_3
{"updatedFields":{},"removedFields":["contactMethods.email","contactMethods.phone"],"truncatedArrays":[]}
Operation: pipeline_remove_2_of_3
{"updatedFields":{"contactMethods":{"mobile":"555-0101"}},"removedFields":[],"truncatedArrays":[]}

Array Updates

对数组的更新会产生 update 更改事件，但 updateDescription.updateFields 可能会显示不同的值。

示例，考虑以下文档和更新：

db.students.insertOne( { student_id: 1, scores: [ ] } )
db.students.updateOne(
   { student_id: 1 },
   { $push: { scores: 0.85 } }
)
db.students.updateOne(
   { student_id: 1 },
   { $push: { scores: 0.94 } }
)
db.students.updateOne(
   { student_id: 1 },
   { $pull: { scores: 0.94 } }
)

第一次更新对空大量进行操作。在这里，$push 会生成 update 更改事件，其中字段被具有给定值的单条目大量替换：

{
   _id: { _data: '82642AD66B000000012B022C0100296E5A10045DC4B11BEA5F4319A8E7CAF46816ED71461E5F6964002B060004' },
   operationType: 'update',
   clusterTime: Timestamp({ t: 1680529003, i: 1 }),
   ns: { db: 'communication_chat', coll: 'students' },
   documentKey: { student_id: 1 },
   updateDescription: {
      updatedFields: { scores: [ 0.85 ] },
      removedFields: [],
      truncatedArrays: []
   }
}

在第二次更新操作中，大量现在包含值。$push在大量中添加一个新条目。然后，update 更改事件将其显示为对大量中新位置（即 scores.1）的更改：

{
  _id: { _data: '82642AD673000000012B022C0100296E5A10045DC4B11BEA5F4319A8E7CAF46816ED71461E5F6964002B060004' },
  operationType: 'update',
  clusterTime: Timestamp({ t: 1680529011, i: 1 }),
  ns: { db: 'communication_chat', coll: 'students' },
  documentKey: { student_id: 1 },
  updateDescription: {
    updatedFields: { 'scores.1': 0.94 },
    removedFields: [],
    truncatedArrays: []
  }
}

如果您再次运行更新操作以将第三个分数添加到学生的记录中，则会产生修改 scores.2 的 update 更改事件。

使用 $pull 操作符删除大量项会产生一个显示新大量的变更事件：

{
  _id: { _data: '82642AD673000000012B022C0100296E5A10045DC4B11BEA5F4319A8E7CAF46816ED71461E5F6964002B060004' },
  operationType: 'update',
  clusterTime: Timestamp({ t: 1680529011, i: 1 }),
  ns: { db: 'communication_chat', coll: 'students' },
  documentKey: { student_id: 1 },
  updateDescription: {
    updatedFields: { scores: [ 0.85 ] },
    removedFields: [],
    truncatedArrays: []
  }
}

数组截断

通过管道更新减少数组中元素数量的更新操作（例如使用$addFields或$set聚合阶段）会在truncatedArrays字段中显示更新后的大量和新大小。

db.students.insertOne( { student_id: 2, scores: [ 0.85, 0.94, 0.78 ] } )
db.students.updateOne(
   { student_id: 2 },
   [ { $addFields: { scores: [ 0.85, 0.94 ] } } ]
)
db.students.updateOne(
   { student_id: 2 },
   [ { $addFields: { scores: [ 0.85, 0.94, 0.78 ] } } ]
)

第一次更新的变更事件（使用$addFields阶段从 scores字段中删除一个值）会在 truncatedArrays字段中显示更改：

{
  _id: { _data: '82642AD673000000012B022C0100296E5A10045DC4B11BEA5F4319A8E7CAF46816ED71461E5F6964002B060004' },
  operationType: 'update',
  clusterTime: Timestamp({ t: 1680529011, i: 1 }),
  ns: { db: 'communication_chat', coll: 'students' },
  documentKey: { student_id: 2 },
  updateDescription: {
    updatedFields: {},
    removedFields: [],
    truncatedArrays: [ { fields: "scores", newSize: 2 } ]
  }
}

第二次更新的变更事件使用$addFields阶段将值重新添加到 scores字段，并在 updatedFields字段中显示更新：

{
  _id: { _data: '82642AD673000000012B022C0100296E5A10045DC4B11BEA5F4319A8E7CAF46816ED71461E5F6964002B060004' },
  operationType: 'update',
  clusterTime: Timestamp({ t: 1680529011, i: 1 }),
  ns: { db: 'communication_chat', coll: 'students' },
  documentKey: { student_id: 2 },
  updateDescription: {
    updatedFields: { scores.2: 0.78 },
    removedFields: [],
    truncatedArrays: []
  }
}