8000 DOCSP-22297: change streams, pre and post images (#309) · nickldp/docs-kotlin@70b1578 · GitHub
[go: up one dir, main page]
Skip to content

Commit 70b1578

Browse files
author
Chris Cho
authored
DOCSP-22297: change streams, pre and post images (#309)
* DOCSP-22297: change streams - pre and post images
1 parent 757e26d commit 70b1578

File tree

5 files changed

+442
-78
lines changed

5 files changed

+442
-78
lines changed

‎source/fundamentals/crud/read-operations.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ Read Operations
66

77
- :doc:`/fundamentals/crud/read-operations/retrieve`
88
- :doc:`/fundamentals/crud/read-operations/cursor`
9+
- :doc:`/fundamentals/crud/read-operations/change-streams`
910
- :doc:`/fundamentals/crud/read-operations/sort`
1011
- :doc:`/fundamentals/crud/read-operations/skip`
1112
- :doc:`/fundamentals/crud/read-operations/limit`
@@ -18,6 +19,7 @@ Read Operations
1819

1920
/fundamentals/crud/read-operations/retrieve
2021
/fundamentals/crud/read-operations/cursor
22+
/fundamentals/crud/read-operations/change-streams
2123
/fundamentals/crud/read-operations/sort
2224
/fundamentals/crud/read-operations/skip
2325
/fundamentals/crud/read-operations/limit

‎source/fundamentals/crud/read-operations/change-streams.txt

Lines changed: 269 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,269 @@
1+
.. _java-fundamentals-change-streams:
2+
.. _retrieve-watch:
3+
4+
===================
5+
Open Change Streams
6+
===================
7+
8+
.. default-domain:: mongodb
9+
10+
.. contents:: On this page
11+
:local:
12+
:backlinks: none
13+
:depth: 1
14+
:class: singlecol
15+
16+
Overview
17+
--------
18+
19+
In this guide, you can learn how to use a **change stream** to monitor
20+
real-time changes to your database. A change stream is a {+mdb-server+}
21+
feature that allows your application to subscribe to data changes on a single
22+
collection, database, or deployment. You can specify a set of aggregation
23+
operators to filter and transform the data your application receives. When
24+
connecting to a MongoDB deployment v6.0 or later, you can configure the
25+
events to include the document data before and after the change.
26+
27+
Learn how to open and configure your change streams in the following
28+
sections:
29+
30+
- :ref:`<java-change-stream-open>`
31+
- :ref:`<java-change-stream-aggregation>`
32+
- :ref:`<java-change-stream-configure-pre-post>`
33+
34+
.. _java-change-stream-open:
35+
36+
Open a Change Stream
37+
--------------------
38+
39+
You can open a change stream to subscribe to specific types of data changes
40+
and produce change events in your application.
41+
42+
To open a change stream, call the ``watch()`` method on an instance of a
43+
``MongoCollection``, ``MongoDatabase``, or ``MongoClient``.
44+
45+
.. important::
46+
47+
Standalone MongoDB deployments don't support change streams because
48+
the feature requires a replica set oplog. To learn more about the oplog,
49+
see the :ref:`<replica-set-oplog>` server manual page.
50+
51+
The object on which you call the ``watch()`` method on determines the scope of
52+
events that the change stream listens for.
53+
54+
If you call ``watch()`` on a ``MongoCollection``, the change stream monitors
55+
a collection.
56+
57+
If you call ``watch()`` on a ``MongoDatabase``, the change stream monitors all
58+
collections in that database.
59+
60+
If you call ``watch()`` on a ``MongoClient``, the change stream monitors all
61+
changes in the connected MongoDB deployment.
62+
63+
Example
64+
~~~~~~~
65+
66+
The following code example shows how to open a change stream and print
67+
change stream events whenever the data in the collection changes:
68+
69+
.. literalinclude:: /includes/fundamentals/code-snippets/change-streams/ChangeStreams.java
70+
:language: java
71+
:dedent:
72+
:start-after: begin openChangeStreamExample
73+
:end-before: end openChangeStreamExample
74+
75+
An insert operation on the collection should produce output similar to the
76+
following text:
77+
78+
.. code-block::
79+
:copyable: false
80+
81+
Received a change: ChangeStreamDocument{
82+
operationType='insert',
83+
resumeToken={"_data": "825EC..."},
84+
namespace=myDb.myChangeStreamCollection,
85+
...
86+
}
87+
88+
For a runnable example, see the :ref:`<java-usage-watch>` usage example page.
89+
90+
To learn more about the ``watch()`` method, see the following API
91+
documentation:
92+
93+
- `MongoCollection.watch() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#watch()>`__
94+
- `MongoDatabase.watch() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoDatabase.html#watch()>`__
95+
- `MongoClient.watch() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html#watch()>`__
96+
97+
.. _java-change-stream-aggregation:
98+
99+
Apply Aggregation Operators to your Change Stream
100+
-------------------------------------------------
101+
102+
You can pass an aggregation pipeline as a parameter to the ``watch()`` method
103+
to specify which change events the change stream receives.
104+
105+
To learn which aggregation operators your {+mdb-server+} version supports, see
106+
:ref:`<change-stream-modify-output>`.
107+
108+
109+
Example
110+
~~~~~~~
111+
112+
The following code example shows how you can apply an aggregation pipeline to
113+
configure your change stream to receive change events for only insert and
114+
update operations:
115+
116+
.. literalinclude:: /includes/fundamentals/code-snippets/change-streams/ChangeStreams.java
117+
:language: java
118+
:dedent:
119+
:start-after: begin aggregationExample
120+
:end-before: end aggregationExample
121+
122+
When the change stream receives an update change event, the preceding code
123+
example outputs the following text:
124+
125+
.. code-block:: text
126+
:copyable: false
127+
128+
Received a change to the collection: ChangeStreamDocument{
129+
operationType=update, resumeToken={...},
130+
...
131+
132+
.. _java-change-stream-configure-pre-post:
133+
134+
Include Pre-images and Post-images
135+
----------------------------------
136+
137+
You can configure the change event to contain or omit the following data:
138+
139+
- The **pre-image** which is a document that represents the version of the
140+
document before the operation if it exists
141+
- The **post-image** which is a document that represents the version of the
142+
document after the operation if it exists
143+
144+
To receive change stream events that include a pre-image or post-image, you
145+
must connect to a MongoDB v6.0 or later deployment and set up the following:
146+
147+
- Enable pre-images and post-images for the collection on your MongoDB
148+
deployment.
149+
150+
.. tip::
151+
152+
To learn how to enable these on your deployment, see the
153+
:manual:`Change Streams with Document Pre- and Post-Images </changeStreams/#change-streams-with-document-pre--and-post-images>`
154+
MongoDB server manual page.
155+
156+
To learn how to instruct the driver to create a collection with pre-images
157+
and post-images enabled, see the :ref:`<java-change-stream-pre-post-collection>`
158+
section.
159+
160+
- Configure your change stream to retrieve either or both the pre-images and
161+
post-images.
162+
163+
.. tip::
164+
165+
To configure your change stream to include the pre-image, see
166+
the :ref:`<java-pre-image-example>`.
167+
168+
To configure your change stream to include the post-image, see the
169+
:ref:`<java-post-image-example>`.
170+
171+
.. _java-change-stream-pre-post-collection:
172+
173+
Create a Collection with Pre-Image and Post-Images Enabled
174+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
175+
176+
To create a collection with the pre-image and post-image option using the
177+
driver, specify an instance of ``ChangeStreamPreAndPostImagesOptions``
178+
and call the ``createCollection()`` method as shown in the following example:
179+
180+
.. literalinclude:: /includes/fundamentals/code-snippets/change-streams/ChangeStreams.java
181+
:language: java
182+
:dedent:
183+
:start-after: begin createCollection
184+
:end-before: end createCollection
185+
186+
You can change the pre-image and post-image option in an existing collection
187+
by running the ``collMod`` command from the MongoDB Shell. To learn how to
188+
perform this operation, see the :manual:`collMod </reference/command/collMod#change-streams-with-document-pre--and-post-images>`
189+
server manual documentation.
190+
191+
.. warning::
192+
193+
When you modify this option on a collection, any change streams open on
194+
that collection in your application may fail if configured to require
195+
receiving the pre-image or post-image.
196+
197+
.. _java-pre-image-example:
198+
199+
Pre-image Configuration Example
200+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
201+
202+
The following code example shows how you can configure a change stream to
203+
include the pre-image and output the results:
204+
205+
.. literalinclude:: /includes/fundamentals/code-snippets/change-streams/ChangeStreams.java
206+
:language: java
207+
:dedent:
208+
:start-after: begin fullDocumentBeforeChangeExample
209+
:end-before: end fullDocumentBeforeChangeExample
210+
211+
The preceding example configures the change stream to use the
212+
``FullDocumentBeforeChange.REQUIRED`` option. This configures the change
213+
stream to return pre-images for replace, update, and delete change events and
214+
for the server to raise an error if the pre-image is unavailable.
215+
216+
Suppose an application updated the ``latestVersion`` field of a document in a
217+
collection of software library dependencies from the value of ``2.0.0`` to
218+
``2.1.0``. The corresponding change event output by the preceding code example
219+
should resemble the following text:
220+
221+
.. code-block:: text
222+
:emphasize-lines: 3
223+
:copyable: false
224+
225+
Received a change: ChangeStreamDocument{ operationType=update, resumeToken={...}
226+
namespace=software.libraries, destinationNamespace=null, fullDocument=null,
227+
fullDocumentBeforeChange=Document{{_id=6388..., latestVersion=2.0.0, ...}},
228+
...
229+
230+
For a list of options, see the `FullDocumentBeforeChange <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/changestream/FullDocumentBeforeChange.html>`__
231+
API documentation.
232+
233+
.. _java-post-image-example:
234+
235+
Post-image Configuration Example
236+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
237+
238+
The following code example shows how you can configure a change stream to
239+
include the post-image and output the results:
240+
241+
.. literalinclude:: /includes/fundamentals/code-snippets/change-streams/ChangeStreams.java
242+
:language: java
243+
:dedent:
244+
:start-after: begin fullDocumentExample
245+
:end-before: end fullDocumentExample
246+
247+
The preceding example configures the change stream to use the
248+
``FullDocument.UPDATE_LOOKUP`` option. This configures the change
249+
stream to return both the deltas between the original and changed document
250+
and a copy of the document at some point in time after the change occurred.
251+
252+
Suppose an application updated the ``population`` field of a document from
253+
the value of ``800`` to ``950`` in a collection of city census data. The
254+
corresponding change event output by the preceding code example should
255+
resemble the following text:
256+
257+
.. code-block:: text
258+
:emphasize-lines: 3
259+
:copyable: false
260+
261+
Received a change: ChangeStreamDocument{ operationType=update, resumeToken={...},
262+
namespace=censusData.cities, destinationNamespace=null,
263+
fullDocument=Document{{_id=6388..., city=Springfield, population=950, ...}},
264+
updatedFields={"population": 950}, ...
265+
...
266+
267+
For a list of options, see the `FullDocument <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/changestream/FullDocument.html>`__
268+
API documentation.
269+

0 commit comments

Comments
 (0)
0