Skip to content

DOCSP-31907 Split Event #457

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Sep 28, 2023
Merged

DOCSP-31907 Split Event #457

Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
f7baab0
Add split event section
jordan-smith721 Sep 27, 2023
1a0e70c
format code block for less scrolling
jordan-smith721 Sep 27, 2023
6192acc
add note
jordan-smith721 Sep 27, 2023
89bdd3c
add cursor to code block
jordan-smith721 Sep 27, 2023
9ec21b0
Chris feedback
jordan-smith721 Sep 27, 2023
f52a0b2
move section
jordan-smith721 Sep 28, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions source/fundamentals/crud/read-operations/change-streams.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -288,3 +288,56 @@ output:

For a list of options, see the `FullDocument <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/changestream/FullDocument.html>`__
API documentation.

Split Large Change Stream Events
--------------------------------

Starting in MongoDB 7.0, you can use a ``$changeStreamSplitLargeEvent``
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion:
Use the specific article "the" since only one of them exists.

Suggested change
Starting in MongoDB 7.0, you can use a ``$changeStreamSplitLargeEvent``
Starting in MongoDB 7.0, you can use the ``$changeStreamSplitLargeEvent``

aggregation stage to split events that exceed 16 MB into smaller fragments.
``$changeStreamSplitLargeEvent`` returns the fragments sequentially using the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestions:

  • I think that the operator does not return anything, but the stage and pipeline do. Just for accuracy, I would specify what returns the fragments.
  • The style guide recommends "by using" instead of "using".
  • I think "using the change stream cursor" could be better in a separate phrase or sentence.

E.g.
"The $changeStreamSplitLargeEvent stage returns the fragments sequentially. The fragments can be accessed by using a change stream cursor."

change stream cursor. Each fragment includes a ``SplitEvent`` object containing
the following fields:

.. list-table::
:header-rows: 1
:widths: 35 65

* - Field
- Description

* - ``fragment``
- The index of the fragment, starting at 1
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion:
I think it could be good to indicate that "1" is a value by either using quotes or monospace.


* - ``of``
- The total number of fragments in the event
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion:

Partially because Vale picked this up, but since "in the event" could be interpreted as an idiom, I think it could be good to reword it, and provide additional detail. E.g.

"The total number of fragments that compose the split change event


Enable the ``$changeStreamSplitLargeEvent`` aggregation on your change stream as
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion:

I think "enable the ... aggregation" might not be an accurate term to describe setting up the change stream. I think the "modify change stream output" or "control change stream output" could work better as described in the Server manual docs

E.g.
The following example modifies your change stream to split large events:

shown in the following example:

.. code-block:: java

ChangeStreamIterable<Document> changeStream = collection.watch(
Arrays.asList(Document.parse("{ $changeStreamSplitLargeEvent: {} }")));

.. note::

You can have only one ``$changeStreamSplitLargeEvent`` stage in your
aggregation pipeline, and it must be the last stage in the pipeline.

You can access the ``SplitEvent`` by using your change stream cursor with the
``getSplitEvent()`` as follows:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion:
I think sentences are easier to understand when limiting them to one association. In this sentence there are two -- "by using" and "with" -- which can make the associations ambiguous.

Suggested change
You can access the ``SplitEvent`` by using your change stream cursor with the
``getSplitEvent()`` as follows:
You can call the getSplitEvent() method on your change stream cursor to access the SplitEvent as shown in the following example:


.. code-block:: java

MongoChangeStreamCursor<ChangeStreamDocument<Document>> cursor = changeStream.cursor();

// Application code that creates change stream events
// ...
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion:

I think these lines aren't relevant to the example and should be omitted. The other lines demonstrate the objective, and it's not required for the reader to use the same app that watches for change events to also generate them.


SplitEvent event = cursor.tryNext().getSplitEvent();

For more information about accessing data from a cursor, see :ref:`java-fundamentals-cursor`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion:

I think it might be useful to either qualify this information, given that it doesn't include specific information on change stream cursors, or omit it. To qualify the information, first it would be helpful to check what similarities the two different types of cursors have and then to include that.

Hypothetically, if MongoChangeStreamCursor extended MongoCursor, I would suggest something like the following:

The MongoChangeStreamCursor extends MongoCursor and shares the same methods to access data. To learn how to access data from a MongoCursor, see ...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed this line since it's a ChangeStreamCursor not a MongoCursor


For more information on the ``$changeStreamSplitLargeEvent`` aggregation stage,
see the :manual:`$changeStreamSplitLargeEvent
</reference/operator/aggregation/changeStreamSplitLargeEvent/>` server documentation.