文档菜单
文档首页
/
MongoDB 手册
/ /

更新 事件

本页内容

  • 摘要
  • 描述
  • 行为
  • 文档预/后图片
  • 路径消除歧义
  • 示例
update

当操作更新集合中的文档时,会触发一个 update 事件。

注意

消除歧义

要了解更多关于修改集合选项时发生的事件,请参阅modify 事件。

字段
类型
描述
_id
文档

一个作为更改流事件标识符的 BSON 对象。此值用作在恢复更改流时 resumeAfter 参数的 resumeToken_id 对象具有以下形式

{
"_data" : <BinData|hex string>
}

_data 类型取决于 MongoDB 版本,在某些情况下取决于更改流打开或恢复时的 功能兼容性版本 (fCV)。有关 _data 类型的完整列表,请参阅 恢复令牌

有关通过 resumeToken 恢复更改流的示例,请参阅 恢复更改流

clusterTime
时间戳

clusterTime 是与事件关联的 oplog 条目的时间戳。

由于 oplog 大小限制多文档事务可能会创建多个 oplog 条目。在一个事务中,在特定 oplog 条目中排练的改变流事件共享相同的 clusterTime

具有相同 clusterTime 的事件可能并不都与同一个事务相关。一些事件根本不与事务相关。从 MongoDB 8.0 开始,这可能是任何部署上的事件。在之前版本中,这种行为仅适用于分片集群上的事件。

要识别单个事务的事件,您可以在改变流事件文档中使用 lsidtxnNumber 的组合。

已更改在版本8.0.

collectionUUID
UUID

UUID 标识发生更改的集合。

新增在版本6.0.

documentKey
document

包含通过 CRUD 操作创建或修改的文档的 _id 值的文档。

对于分片集合,此字段还显示文档的完整分片键。如果 _id 字段已经是分片键的一部分,则不会重复。

fullDocument
document

通过 CRUD 操作创建或修改的文档。

此字段仅在您将改变流配置为将 fullDocument 设置为 updateLookup 时出现。当您将改变流配置为 updateLookup 时,该字段表示更新操作修改的文档的当前多数提交版本。文档可能不同于在updateDescription 中描述的更改,如果在此原始更新操作和完整文档查找之间有其他多数提交操作已修改该文档。

有关更多信息,请参阅 更新操作的完整文档查找。

已更改在版本6.0.

从 MongoDB 6.0 开始,如果您使用 db.createCollection()createcollMod 设置 changeStreamPreAndPostImages 选项,则 fullDocument 字段显示插入、替换或更新后的文档(后像)。对于 insert 事件,始终包括 fullDocument

fullDocumentBeforeChange
document

在操作应用更改之前应用的文档。即前像。

当您使用 db.createCollection() 方法或 createcollMod 命令为集合启用 changeStreamPreAndPostImages 字段时,此字段可用。

新增在版本6.0.

lsid
document

事务关联会话的标识符。

仅在操作是 多文档事务 的一部分时存在。

ns
document

受事件影响的数据库名称或集合。

ns.coll
字符串

事件发生的集合名称。

ns.db
字符串

事件发生的数据库名称。

operationType
字符串

更改通知报告的操作类型。

对于这些更改事件返回值 update

updateDescription
document

一个文档,描述了由更新操作更新或删除的字段。

updateDescription.
disambiguatedPaths
document

一个文档,提供了对 updateDescription 中模糊字段描述的澄清。

update 更改事件描述了字段中的更改,其中路径包含点 (.) 或路径包括非数组数值子字段时,disambiguatedPath 字段提供了一个文档,其中包含一个数组,列出了修改字段的路径中的每个条目。

需要将 showExpandedEvents 选项设置为 true

新增在版本6.1.

updateDescription.
removedFields
数组

一个数组,表示由更新操作删除的字段。

updateDescription.
truncatedArrays
数组

一个文档数组,记录使用基于管道的更新执行数组截断的操作,使用以下阶段之一或多个:

如果整个数组被替换,截断将报告在 updateDescription.updatedFields. 下。

updateDescription.
truncatedArrays.
field
字符串

截断字段的名称。

updateDescription.
truncatedArrays.
newSize
整数

截断数组中的元素数量。

updateDescription.
updatedFields
document

一个文档,其键对应于由更新操作修改的字段。每个字段的值对应于这些字段的新的值,而不是产生新值的结果。

txnNumber
NumberLong

lsid 一起,这是一个帮助唯一标识事务的数字。

仅在操作是 多文档事务 的一部分时存在。

wallTime

数据库操作的数据库服务器日期和时间。与 clusterTime 不同,clusterTime 是从与数据库操作事件关联的操作日志条目中获取的时间戳。

新增在版本6.0.

从MongoDB 6.0开始,如果您执行以下步骤,将看到在更改(或删除)文档之前字段的 fullDocumentBeforeChange 文档

  1. 使用 db.createCollection()createcollMod 为集合启用新的 changeStreamPreAndPostImages 字段。

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

更改流输出中的 fullDocumentBeforeChange 文档示例

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

有关更改流输出的完整示例,请参阅 带有文档前后图像的更改流。

如果图像在文档更新或删除操作时未被启用,则更改流事件中不可用前后图像

  • 未在集合上启用。

  • expireAfterSeconds 中设置的保留时间之后已删除。

    • 以下示例在集群上设置了 expireAfterSeconds100

      use admin
      db.runCommand( {
      setClusterParameter:
      { changeStreamOptions: {
      preAndPostImages: { expireAfterSeconds: 100 }
      } }
      } )
    • 以下示例返回当前的 changeStreamOptions 设置,包括 expireAfterSeconds

      db.adminCommand( { getClusterParameter: "changeStreamOptions" } )
    • expireAfterSeconds 设置为 off 使用默认的保留策略:保留前后图像,直到相应的更改流事件从 操作日志 中删除。

    • 如果更改流事件从oplog中删除,则相应的预图像和后图像也会被删除,无论expireAfterSeconds预图像和后图像保留时间是多少。

其他注意事项

  • 启用预图像和后图像会消耗存储空间并增加处理时间。只有当您需要它们时才启用预图像和后图像。

  • 将更改流事件的大小限制在小于16兆字节。要限制事件大小,您可以

    • 将文档大小限制在8兆字节。如果其他更改流事件字段(如updateDescription)不是很大,您可以在更改流输出中同时请求预图像和后图像。

    • 如果其他更改流事件字段(如updateDescription)不是很大,则仅请求16兆字节以内文档的后图像。

    • 如果仅请求16兆字节以内文档的预图像,则

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

      • 不会引起replace更改事件。一个replace事件始终包括后图像。

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

  • 预图像被写入到config.system.preimages集合。

    • config.system.preimages集合可能会变得很大。要限制集合大小,您可以像前面所示为预图像设置expireAfterSeconds时间。

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

重要

向后不兼容的功能

从MongoDB 6.0开始,如果您正在使用文档预图像和后图像进行更改流,则必须在降级到早期MongoDB版本之前,使用changeStreamPreAndPostImages禁用每个集合的collMod命令。

提示

另请参阅

新增在版本6.1.

《updateDescription》字段记录了对文档中特定字段进行的更改。这些字段描述符使用点(.)作为路径分隔符,使用数字作为数组索引,当它包含使用点或数字的字段名称时,这会导致一些歧义。

当一个update事件报告涉及模糊字段的更改时,disambiguatedPaths文档提供了一个路径键,该键包含一个列出每个路径组件的数组。

注意

disambiguatedPaths字段仅在以showExpandedEvents选项启动的更改流中可用

例如,考虑一个列出人们和他们居住的城镇的文档

{
"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事件

{
"_id": { <Resume Token> },
"operationType": "update",
"clusterTime": <Timestamp>,
"wallTime": <ISODate>,
"ns": {
"db": "engineering",
"coll": "users"
},
"documentKey": {
"_id": ObjectId("58a4eb4a30c75625e00d2820")
},
"updateDescription": {
"updatedFields": {
"email": "alice@10gen.com"
},
"removedFields": ["phoneNumber"],
"truncatedArrays": [ {
"field" : "vacation_time",
"newSize" : 36
} ]
}
}

以下示例说明了使用fullDocument : updateLookup选项打开的更改流中的update事件

{
"_id": { <Resume Token> },
"operationType": "update",
"clusterTime": <Timestamp>,
"wallTime": <ISODate>,
"ns": {
"db": "engineering",
"coll": "users"
},
"documentKey": {
"_id": ObjectId("58a4eb4a30c75625e00d2820")
},
"updateDescription": {
"updatedFields": {
"email": "alice@10gen.com"
},
"removedFields": ["phoneNumber"],
"truncatedArrays": [ {
"field" : "vacation_time",
"newSize" : 36
} ],
"disambiguatedPaths": { }
},
"fullDocument": {
"_id": ObjectId("58a4eb4a30c75625e00d2820"),
"name": "Alice",
"userName": "alice123",
"email": "alice@10gen.com",
"team": "replication"
}
}

fullDocument》文档表示更新文档的最新多数提交版本。《fullDocument》文档可能因更新操作与文档查找之间发生的交错多数提交操作的数量而与更新操作时的文档不同。

返回

分片集合

© . All rights reserved.