监控数据变化

在此页面上

Overview

样本数据
打开变更流
修改变更流输出
修改 watch()行为
包含前像和后像
更多信息
API 文档

Overview

在本指南中，您可以了解如何使用变更流来监控数据库的实时更改。变更流是 MongoDB Server 的一项功能，允许应用程序订阅集合、数据库或部署上的数据更改。

样本数据

本指南中的示例使用 Atlas示例数据集中的 sample_restaurants.restaurants集合。要学习；了解如何创建免费的MongoDB Atlas 群集并加载示例数据集，请参阅 PyMongo入门。

打开变更流

要打开变更流，请调用watch()方法。您调用watch()方法的实例决定了变更流侦听的事件范围。您可以对以下类调用watch()方法：

MongoClient：监控 MongoDB 部署中的所有更改
Database：监控数据库中所有集合的变更
Collection：监控集合中的更改

以下示例在restaurants集合上打开变更流，并在发生变更时输出变更：

database = client["sample_restaurants"]
collection = database["restaurants"]
with collection.watch() as stream:
    for change in stream:
        print(change)

要开始监视更改，请运行该应用程序。然后，在单独的应用程序或 shell 中，修改restaurants集合。以下示例更新name字段值为Blarney Castle的文档：

database = client["sample_restaurants"]
collection = database["restaurants"]
query_filter = { "name": "Blarney Castle" }
update_operation = { '$set' : 
    { "cuisine": "Irish" }
}
result = collection.update_one(query_filter, update_operation)

更新集合时，变更流应用程序会在发生变更时打印变更。打印的变更事件类似于以下内容：

{'_id': {'_data': '...'}, 'operationType': 'update', 'clusterTime': Timestamp(...), 'wallTime': datetime.datetime(...),
'ns': {'db': 'sample_restaurants', 'coll': 'restaurants'}, 'documentKey': {'_id': ObjectId('...')},
'updateDescription': {'updatedFields': {'cuisine': 'Irish'}, 'removedFields': [], 'truncatedArrays': []}}

修改变更流输出

您可以将pipeline参数传递给watch()方法，以修改变更流输出。此参数允许您仅监视指定的变更事件。将参数格式设置为对象列表，每个对象代表一个聚合阶段。

您可以在pipeline参数中指定以下阶段：

$addFields
$match
$project
$replaceRoot
$replaceWith
$redact
$set
$unset

以下示例使用pipeline参数打开仅记录更新操作的变更流：

change_pipeline = { "$match": { "operationType": "update" }},
with collection.watch(pipeline=change_pipeline) as stream:
    for change in stream:
        print(change)

要了解有关修改变更流输出的更多信息，请参阅 MongoDB Server 手册中的修改变更流输出部分。

修改`watch()` 行为

watch()方法接受可选参数，这些参数表示可用于配置操作的选项。如果不指定任何选项，驱动程序不会自定义操作。

下表描述了可用于自定义watch()行为的选项：

属性	说明
`pipeline`	A list of aggregation pipeline stages that modify the output of the change stream.
`full_document`	Specifies whether to show the full document after the change, rather than showing only the changes made to the document. To learn more about this option, see Include Pre-Images and Post-Images.
`full_document_before_change`	Specifies whether to show the full document as it was before the change, rather than showing only the changes made to the document. To learn more about this option, see Include Pre-Images and Post-Images.
`resume_after`	Directs `watch()` to resume returning changes after the operation specified in the resume token. Each change stream event document includes a resume token as the `_id` field. Pass the entire `_id` field of the change event document that represents the operation you want to resume after. `resume_after` is mutually exclusive with `start_after` and `start_at_operation_time`.
`start_after`	Directs `watch()` to start a new change stream after the operation specified in the resume token. Allows notifications to resume after an invalidate event. Each change stream event document includes a resume token as the `_id` field. Pass the entire `_id` field of the change event document that represents the operation you want to resume after. `start_after` is mutually exclusive with `resume_after` and `start_at_operation_time`.
`start_at_operation_time`	Directs `watch()` to return only events that occur after the specified timestamp. `start_at_operation_time` is mutually exclusive with `resume_after` and `start_after`.
`max_await_time_ms`	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.
`show_expanded_events`	Starting in MongoDB Server v6.0, change streams support change notifications for Data Definition Language (DDL) events, such as the `createIndexes` and `dropIndexes` events. To include expanded events in a change stream, create the change stream cursor and set this parameter to `True`.
`batch_size`	The maximum number of change events to return in each batch of the response from the MongoDB cluster.
`collation`	The collation to use for the change stream cursor.
`session`	An instance of `ClientSession`.
`comment`	A comment to attach to the operation.

包含前像和后像

重要

仅当您的部署使用 MongoDB v 6.0或更高版本时，才能对集合启用前图像和后图像。

默认情况下，当您对集合执行操作时，相应的变更事件仅包括该操作修改的字段的增量。要查看更改之前或之后的完整文档，请在watch()方法中指定full_document_before_change或full_document参数。

前像是文档在更改之前的完整版本。要在变更流事件中包含前像，请将full_document_before_change参数设置为以下值之一：

whenAvailable：仅当预像可用时，变更事件才包含变更事件的已修改文档的前像。
required：变更事件包括变更事件的已修改文档的前像。如果前像不可用，则驱动程序会引发错误。

后像是文档更改后的完整版本。要将后图像包含在变更流事件中，请将full_document参数设置为以下值之一：

updateLookup：更改事件包括更改后某个时间点的整个已更改文档的副本。
whenAvailable：仅当后图像可用时，更改事件才包含更改事件的已修改文档的后图像。
required：变更事件包括变更事件的已修改文档的后像。如果后图像不可用，驱动程序会引发错误。

以下示例对集合调用watch()方法，并通过指定fullDocument参数来包含更新文档的后像：

database = client["sample_restaurants"]
collection = database["restaurants"]
with collection.watch(full_document='updateLookup') as stream:
    for change in stream:
        print(change)

在变更流应用程序运行的情况下，使用前面的更新示例更新restaurants集合中的文档会打印类似于以下内容的变更事件：

{'_id': {'_data': '...'}, 'operationType': 'update', 'clusterTime': Timestamp(...), 'wallTime': datetime.datetime(...),
 'fullDocument': {'_id': ObjectId('...'), 'address': {...}, 'borough': 'Queens',
 'cuisine': 'Irish', 'grades': [...], 'name': 'Blarney Castle', 'restaurant_id': '40366356'},
 'ns': {'db': 'sample_restaurants', 'coll': 'restaurants'}, 'documentKey': {'_id': ObjectId('...')},
 'updateDescription': {'updatedFields': {'cuisine': 'Irish'}, 'removedFields': [], 'truncatedArrays': []}}

要了解有关前图像和后图像的更多信息，请参阅Change Streams MongoDB Server手册中的具有文档前图像和后图像的。

Overview

样本数据

打开变更流

修改变更流输出

修改watch() 行为

包含前像和后像

重要

更多信息

API 文档

修改`watch()` 行为