db.watch()

Definition定义

db.watch( pipeline, options )

For replica sets and sharded clusters only仅适用于副本集和分片群集

New in version 4.0.在版本4.0中新增。 Requires featureCompatibilityVersion (fCV) set to "4.0" or greater. 需要将featureCompatibilityVersion(fCV)设置为"4.0"或更高。For more information on fCV, see setFeatureCompatibilityVersion.有关fCV的更多信息，请参阅setFeatureCompatibilityVersion。

Opens a change stream cursor for a database to report on all its non-system collections.打开数据库的更改流游标以报告其所有非系统集合。

Parameter参数	Type类型	Description描述
pipeline	array	Optional. 可选。An Aggregation Pipeline consisting of one or more of the following aggregation stages:由以下一个或多个聚合阶段组成的聚合管道： $addFields $match $project $replaceRoot $replaceWith (Available starting in MongoDB 4.2)（从MongoDB 4.2开始提供） $redact $set (Available starting in MongoDB 4.2)（从MongoDB 4.2开始提供） $unset (Available starting in MongoDB 4.2)（从MongoDB 4.2开始提供） Specify a pipeline to filter/modify the change events output.指定管道以筛选/修改更改事件输出。 Starting in MongoDB 4.2, change streams will throw an exception if the change stream aggregation pipeline modifies an event's _id field.从MongoDB 4.2开始，如果更改流聚合管道修改了事件的_id字段，则更改流将引发异常。
options	document	Optional. 可选。Additional options that modify the behavior of db.watch().修改db.watch()行为的其他选项。

The options document can contain the following fields and values:options文档可以包含以下字段和值：

Field字段	Type类型	Description描述
resumeAfter	document	Optional. 可选。Directs db.watch() to attempt resuming notifications starting after the operation specified in the resume token.指示db.watch()尝试在恢复令牌中指定的操作之后开始恢复通知。 Each change stream event document includes a resume token as the _id field. 每个变更流事件文档都包含一个恢复令牌作为_id字段。Pass the entire _id field of the change event document that represents the operation you want to resume after.传递更改事件文档的整个_id字段，该字段表示要在之后恢复的操作。 resumeAfter is mutually exclusive with startAfter and startAtOperationTime.resumeAfter与startAfter和startAtOperationTime相互排斥。
startAfter	document	Optional. 可选。Directs db.watch() to attempt starting a new change stream after the operation specified in the resume token. 指示db.watch()在恢复令牌中指定的操作之后尝试启动新的更改流。Allows notifications to resume after an invalidate event.允许通知在无效事件后恢复。 Each change stream event document includes a resume token as the _id field. 每个变更流事件文档都包含一个恢复令牌作为_id字段。Pass the entire _id field of the change event document that represents the operation you want to resume after.传递更改事件文档的整个_id字段，该字段表示要在之后恢复的操作。 startAfter is mutually exclusive with resumeAfter and startAtOperationTime.startAfter与resumeAfter和startAtOperationTime互斥。 New in version 4.2.在版本4.2中新增。
fullDocument	string	Optional. 可选。By default, db.watch() returns the delta of those fields modified by an update operation, instead of the entire updated document.默认情况下，db.watch()返回更新操作修改的字段的增量，而不是整个更新的文档。 Set fullDocument to "updateLookup" to direct db.watch() to look up the most current majority-committed version of the updated document. 将fullDocument设置为"updateLookup"以指示db.watch()查找更新文档的最新多数提交版本。db.watch() returns a fullDocument field with the document lookup in addition to the updateDescription delta.除了updateDescription delta之外，还返回一个包含文档查找的fullDocument字段。
batchSize	int	Optional. 可选。Specifies the maximum number of change events to return in each batch of the response from the MongoDB cluster.指定在MongoDB集群的每个批响应中返回的最大更改事件数。 Has the same functionality as cursor.batchSize().具有与cursor.batchSize()相同的功能。
maxAwaitTimeMS	int	Optional. 可选。The maximum amount of time in milliseconds the server waits for new data changes to report to the change stream cursor before returning an empty batch.服务器在返回空批之前等待新数据更改报告给更改流游标的最长时间（毫秒）。 Defaults to 1000 milliseconds.默认为1000毫秒。
collation	document	Optional. 可选。Pass a collation document to specify a collation for the change stream cursor.传递排序规则文档以指定更改流游标的排序规则。 If omitted, defaults to simple binary comparison.如果省略，则默认为simple二进制比较。
startAtOperationTime	Timestamp	Optional. 可选。The starting point for the change stream. 变更流的起点。If the specified starting point is in the past, it must be in the time range of the oplog. 如果指定的起点在过去，则必须在oplog的时间范围内。To check the time range of the oplog, see rs.printReplicationInfo().要检查oplog的时间范围，请参阅rs.printReplicationInfo()。 startAtOperationTime is mutually exclusive with resumeAfter and startAfter.startAtOperationTime与resumeAfter和startAfter相互排斥。

Returns:返回：	A cursor over the change event documents. 游标在更改事件文档上。See Change Events for examples of change event documents.有关更改事件文档的示例，请参阅更改事件。

Tip提示

See also: 参阅：

db.collection.watch() and 和Mongo.watch()

Availability可用性

Behavior行为

• You cannot run db.watch() on the admin, local, or config database.不能在admin、local或config数据库上运行db.watch()。
• db.watch() only notifies on data changes that have persisted to a majority of data-bearing members.仅通知已持续到大多数数据承载成员的数据更改。
• The change stream cursor remains open until one of the following occurs:更改流游标将保持打开状态，直到出现以下情况之一：
  • The cursor is explicitly closed.游标已明确关闭。
  • An invalidate event occurs; for example, a collection drop or rename.发生无效事件；例如集合删除或重命名。
  • The connection to the MongoDB deployment is closed.与MongoDB部署的连接已关闭。
  • If the deployment is a sharded cluster, a shard removal may cause an open change stream cursor to close, and the closed change stream cursor may not be fully resumable.如果部署是分片集群，分片移除可能会导致打开的变更流游标关闭，而关闭的变更流游标可能无法完全恢复。
• You can run db.watch() for a database that does not exist. 您可以为不存在的数据库运行db.watch()。However, once the database is created and you drop the database, the change stream cursor closes.但是，一旦创建了数据库并删除了数据库，变更流游标就会关闭。

snippet install resumetoken
decodeResumeToken('<RESUME TOKEN>')

npx mongodb-resumetoken-decoder <RESUME TOKEN>

Access Control访问控制

When running with access control, the user must have the find and changeStream privilege actions on the database resource. 使用访问控制运行时，用户必须对数据库资源具有find和changeStream权限操作。That is, a user must have a role that grants the following privilege:也就是说，用户必须具有授予以下权限的角色：

{ resource: { db: <dbname>, collection: "" }, actions: [ "find", "changeStream"] }

The built-in read role provides the appropriate privileges.内置read角色提供了适当的权限。

Example示例

The following operation in mongosh opens a change stream cursor on the hr database. mongosh中的以下操作将在hr数据库上打开一个变更流游标。The returned cursor reports on data changes to all the non-system collections in that database.返回的游标报告该数据库中所有非系统集合的数据更改。

watchCursor = db.getSiblingDB("hr").watch()

Iterate the cursor to check for new events. 循环游标以检查新事件。Use the cursor.isExhausted() method to ensure the loop only exits if the change stream cursor is closed and there are no objects remaining in the latest batch:使用cursor.isExhausted()方法确保循环仅在更改流游标关闭且最新批处理中没有剩余对象时退出：

while (!watchCursor.isExhausted()){
   if (watchCursor.hasNext()){
      printjson(watchCursor.next());
   }
}

For complete documentation on change stream output, see Change Events.有关变更流输出的完整文档，请参阅变更事件。