DOCSP-31907 Split Event #457

jordan-smith721 · 2023-09-27T17:31:23Z

Pull Request Info

JIRA - https://jira.mongodb.org/browse/DOCSP-31907
Staging - https://docs-mongodbcom-staging.corp.mongodb.com/java/docsworker-xlarge/DOCSP-31907-split-event/fundamentals/crud/read-operations/change-streams/#split-large-change-stream-events

Self-Review Checklist

Is this free of any warnings or errors in the RST?
Did you run a spell-check?
Did you run a grammar-check?
Are all the links working?

ccho-mongodb

Looks pretty good! Just a few suggestions. Approving, but can take another look post-changes if you want.

Additional suggestion: I think this section might belong as a subheading in the "Apply Aggregation Operators to your Change Stream." What do you think?

ccho-mongodb · 2023-09-27T18:00:57Z

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

+Split Large Change Stream Events
+--------------------------------
+
+Starting in MongoDB 7.0, you can use a ``$changeStreamSplitLargeEvent``


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``

ccho-mongodb · 2023-09-27T18:02:45Z

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

+
+Starting in MongoDB 7.0, you can use a ``$changeStreamSplitLargeEvent``
+aggregation stage to split events that exceed 16 MB into smaller fragments.
+``$changeStreamSplitLargeEvent`` returns the fragments sequentially using the


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."

ccho-mongodb · 2023-09-27T18:16:21Z

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

+     - The index of the fragment, starting at 1
+
+   * - ``of``
+     - The total number of fragments in the event


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

ccho-mongodb · 2023-09-27T18:16:45Z

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

+     - Description
+
+   * - ``fragment``
+     - The index of the fragment, starting at 1


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

ccho-mongodb · 2023-09-27T18:18:53Z

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

+   * - ``of``
+     - The total number of fragments in the event
+
+Enable the ``$changeStreamSplitLargeEvent`` aggregation on your change stream as


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:

ccho-mongodb · 2023-09-27T18:28:04Z

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

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


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:

ccho-mongodb · 2023-09-27T18:31:47Z

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

+   // Application code that creates change stream events
+   // ...


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.

ccho-mongodb · 2023-09-27T18:39:55Z

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

+
+   SplitEvent event = cursor.tryNext().getSplitEvent();
+
+For more information about accessing data from a cursor, see :ref:`java-fundamentals-cursor`.


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 ...

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

jordan-smith721 · 2023-09-27T20:52:25Z

Additional suggestion: I think this section might belong as a subheading in the "Apply Aggregation Operators to your Change Stream." What do you think?

@ccho-mongodb I was debating on putting this under that subheading or giving it its own section. Ultimately I decided on giving it its own section because it goes a bit deeper than just describing the aggregation operator (describing a SplitEvent object and accessing the event in the cursor). I also feel like the "Apply Aggregation Operators to your Change Stream" section is more about how to apply the stage, rather than what stages are available. Happy to discuss more if needed!

katcharov · 2023-10-03T14:51:22Z

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

+--------------------------------
+
+Starting in MongoDB 7.0, you can use the ``$changeStreamSplitLargeEvent``
+aggregation stage to split events that exceed 16 MB into smaller fragments.


It might be worth repeating the "should only use when strictly necessary" warning from the server docs.

Added in a separate PR: #460

* DOCSP-32942: Deprecated Methods * review feedback * DOCSP-33241: fix extended JSON example id field (#447) * DOCSP-33241: fix extended JSON example id field * DOCSP-31694: SOCKS5 proxy support (#439) * DOCSP-31694: SOCKS5 proxy support * DOCSP-33300: Fix aggregation operator links to the manual (#448) * DOCSP-32300 Adds compatibility info to landing page (#449) * DOCSP-31907 Split Event (#457) * tech review feedback * format * CC feedback * CC feedback pt 2 * DOCSP-31907 - Add paragraph from server docs (#460) * DOCSP-32942: Deprecated Methods * review feedback * tech review feedback * format * CC feedback * CC feedback pt 2 * build

jordan-smith721 added 4 commits September 27, 2023 09:57

Add split event section

f7baab0

format code block for less scrolling

1a0e70c

add note

6192acc

add cursor to code block

89bdd3c

ccho-mongodb approved these changes Sep 27, 2023

View reviewed changes

Chris feedback

9ec21b0

move section

f52a0b2

jordan-smith721 merged commit 1769d63 into mongodb:master Sep 28, 2023
2 checks passed

jordan-smith721 requested review from a team and katcharov and removed request for a team September 28, 2023 19:34

katcharov reviewed Oct 3, 2023

View reviewed changes

jordan-smith721 mentioned this pull request Oct 3, 2023

DOCSP-31907 - Add paragraph from server docs #460

Merged

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOCSP-31907 Split Event #457

DOCSP-31907 Split Event #457

jordan-smith721 commented Sep 27, 2023

ccho-mongodb left a comment

ccho-mongodb Sep 27, 2023

ccho-mongodb Sep 27, 2023

ccho-mongodb Sep 27, 2023

ccho-mongodb Sep 27, 2023

ccho-mongodb Sep 27, 2023

ccho-mongodb Sep 27, 2023

ccho-mongodb Sep 27, 2023

ccho-mongodb Sep 27, 2023

jordan-smith721 Sep 27, 2023

jordan-smith721 commented Sep 27, 2023

katcharov Oct 3, 2023

jordan-smith721 Oct 3, 2023

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

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

	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:


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

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

DOCSP-31907 Split Event #457

DOCSP-31907 Split Event #457

Conversation

jordan-smith721 commented Sep 27, 2023

Pull Request Info

Self-Review Checklist

ccho-mongodb left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jordan-smith721 commented Sep 27, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment