DOCSP-47795 change batchsize descriptions #6292

shuangela · 2025-03-14T15:34:34Z

DESCRIPTION

Updates five pages in manual/reference to clarify how BatchSize works. No new sections were added, but descriptions of BatchSize were changed.

Wording taken from already updated PHP driver docs which was approved by a PHP engineer.

STAGING

https://deploy-preview-6292--mongodb-docs.netlify.app/reference/method/cursor.batchSize/
https://deploy-preview-6292--mongodb-docs.netlify.app/reference/command/getMore/
https://deploy-preview-6292--mongodb-docs.netlify.app/reference/command/find/
https://deploy-preview-6292--mongodb-docs.netlify.app/reference/method/db.collection.watch/
https://deploy-preview-6292--mongodb-docs.netlify.app/reference/operator/aggregation/queryStats/#output

JIRA

DOCSP-47795

SELF-REVIEW CHECKLIST

Does each file have 3-5 taxonomy facet tags?
See the taxonomy tagging instructions and this example PR
Is this free of any warnings or errors in the RST?
Is this free of spelling errors?
Is this free of grammatical errors?
Is this free of staging / rendering issues?
Are all the links working?

EXTERNAL REVIEW REQUIREMENTS

What's expected of an external reviewer?

netlify · 2025-03-14T15:34:55Z

✅ Deploy Preview for mongodb-docs ready!

Name	Link
🔨 Latest commit	`0617073`
🔍 Latest deploy log	https://app.netlify.com/sites/mongodb-docs/deploys/67ef0671b4cf3e00086b9bb9
😎 Deploy Preview	https://deploy-preview-6292--mongodb-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

jmd-mongo

Thanks for these updates, @shuangela! I've left a few questions and suggestions for your consideration.

Thanks!
Joe

jmd-mongo · 2025-03-14T18:59:00Z

source/reference/command/find.txt

+       limit than 16 MiB, but not a larger one. If you set ``batchSize`` to a limit that results 
+       in batches larger than 16 MiB, this option has no effect.
+`
+       A batchSize of 0 means that the cursor will be established, but no documents 


[tense suggestion]

Consider updating this to use the present tense. Spitballing:

A ``batchsize`` of ``0`` means that the cursor is established, but no documents are returned in the first batch.

Thanks!

jmd-mongo · 2025-03-14T18:59:55Z

source/reference/command/getMore.txt

-       If ``batchSize`` is not set, ``getMore`` returns up to 16
-       mebibytes of data. If ``batchSize`` is set, ``getMore`` returns
-       the smaller of 16 mebibytes of data or ``batchSize`` documents.
+       If batchSize is not set, getMore returns up to ``101`` documents in the first batch 


[style suggestion]

Consider wrapping "batchSize" and "getMore" in backticks here on line 77.

jmd-mongo · 2025-03-14T19:05:46Z

source/reference/command/find.txt

+       By default, the ``find`` command has an initial batch size of ``101`` documents and a maximum 
+       size of 16 mebibytes (MiB) for each subsequent batch. This option can enforce a smaller
+       limit than 16 MiB, but not a larger one. If you set ``batchSize`` to a limit that results 
+       in batches larger than 16 MiB, this option has no effect.


[behavior question]

Can we clarify what we mean by "no effect" here? I take it that means it uses the default. Thanks!

Yes, it means it will use the default, will clarify!

jmd-mongo · 2025-03-14T19:07:01Z

source/reference/method/cursor.batchSize.txt

+   limit than 16 MiB, but not a larger one. If you set ``batchSize`` to a limit that results 
+   in batches larger than 16 MiB, this option has no effect.
+
+   A batchSize of 0 means that the cursor will be established, but no documents 


[tense suggestion]

Consider updating this to use the present tense. Spitballing:

A ``batchsize`` of ``0`` means that the cursor is established, but no documents are returned in the first batch.

jmd-mongo · 2025-03-14T19:08:05Z

source/reference/method/db.collection.watch.txt

+          By default, :method:`~db.collection.watch()` has an initial batch size of ``101`` documents and a maximum size 
+          of 16 mebibytes (MiB) for each subsequent batch. This option can enforce a smaller 
+          limit than 16 MiB, but not a larger one. If you set ``batchSize`` to a limit that
+          results in batches larger than 16 MiB, this option has no effect.


[behavior question]

Can we clarify what we mean by "no effect" here? I take it that means it uses the default.

shuangela · 2025-03-14T19:49:23Z

Thanks for the review, @jmd-mongo! Addressed your feedback and applied it to other pages as well, back to you!

jmd-mongo

Thanks for these updates, @shuangela! Would you mind wrapping some of these lines to a shorter width? After that, this one LGTM.

Thanks!
Joe

jmd-mongo · 2025-03-14T20:29:41Z

source/reference/command/find.txt

-     - Optional. The number of documents to return in the first batch.
-       Defaults to 101. A batchSize of 0 means that the cursor will be
-       established, but no documents will be returned in the first batch.
+     - Optional. The maximum number of documents within each batch returned in a 


Would you mind wrapping these lines? Thank you! This applies throughout.

shuangela · 2025-03-18T14:48:16Z

@ChrisHarris2012 Thank you for offering to review!

ChrisHarris2012

Why are there different wordings/approaches in the various places? I thought part of the feedback in the Slack thread was that we'd like to be more consistent in our presentation of the information regardless of where it is being presented/consumed?

ChrisHarris2012 · 2025-04-03T19:24:41Z

source/reference/command/getMore.txt

+       If ``batchSize`` is not set, ``getMore`` returns up to ``101`` documents
+       in the first batch and up to 16 mebibytes (MiB) of data in all 


When a user issues a query (either a find or an aggregate) it first is received by the server as an instance of that particular command (eg find). If the full result set is not returned by the server in that initial response (eg the "initial batch") then the server opens up a cursor and tells the client about that as well when responding with the initial results. If the client wants to read more results from that cursor then that is when it issues a getMore command.

All this to say that the text here about "101 results in the initial batch of a getmore" is not correct/relevant

ChrisHarris2012 · 2025-04-03T19:28:37Z

source/reference/command/find.txt

-       established, but no documents will be returned in the first batch.
+     - Optional. The maximum number of documents within each batch returned
+       in a query result. By default, the ``find`` command has an initial 
+       batch size of ``101`` documents and a maximum size of 16 mebibytes (MiB)


The 16MiB (Eng should confirm if MB or MiB, I can't recall) applies to all batches. In other words, by default (assuming more than 1 batch):

The initial batch is the lesser of 101 docs or 16MiB worth of docs

Subsequent batches are 16MiB worth of docs

Good catch, thanks!

shuangela · 2025-04-03T22:12:48Z

Why are there different wordings/approaches in the various places? I thought part of the feedback in the Slack thread was that we'd like to be more consistent in our presentation of the information regardless of where it is being presented/consumed?

@ChrisHarris2012 Back to you with the changes! I've tried to make the wording more consistent, however it is not 100% the same across each page because I tried to keep as much of the original content on each doc page as possible, such as keeping the note on the cursor.batchSize page or referring to specific methods depending on the page.

change batchsize descriptions

8deeac6

Empty-Commit

be213a1

shuangela mentioned this pull request Mar 14, 2025

[DOCSP-47795] Change batchsize description mongodb/docs-mongodb-shell#392

Open

5 tasks

remove file

33ca30a

jmd-mongo requested changes Mar 14, 2025

View reviewed changes

shuangela added 4 commits March 14, 2025 15:20

address feedback

d5b3d92

fix wording error

cf8c2a4

style change

bc536e2

extra quotation

035d691

shuangela requested a review from jmd-mongo March 14, 2025 19:49

jmd-mongo approved these changes Mar 14, 2025

View reviewed changes

wrap

faf17d1

ChrisHarris2012 suggested changes Apr 3, 2025

View reviewed changes

shuangela added 4 commits April 3, 2025 17:37

ch feedback

63c684f

style

e660f33

fix spacing

caa5e22

change size desc

0617073

shuangela requested a review from ChrisHarris2012 April 3, 2025 22:12

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOCSP-47795 change batchsize descriptions #6292

DOCSP-47795 change batchsize descriptions #6292

shuangela commented Mar 14, 2025 •

edited

Loading

netlify bot commented Mar 14, 2025 •

edited

Loading

jmd-mongo left a comment

jmd-mongo Mar 14, 2025

jmd-mongo Mar 14, 2025

jmd-mongo Mar 14, 2025

shuangela Mar 14, 2025

jmd-mongo Mar 14, 2025

jmd-mongo Mar 14, 2025

shuangela commented Mar 14, 2025

jmd-mongo left a comment

jmd-mongo Mar 14, 2025

shuangela commented Mar 18, 2025

ChrisHarris2012 left a comment

ChrisHarris2012 Apr 3, 2025

ChrisHarris2012 Apr 3, 2025

shuangela Apr 3, 2025

shuangela commented Apr 3, 2025

		If ``batchSize`` is not set, ``getMore`` returns up to ``101`` documents
		in the first batch and up to 16 mebibytes (MiB) of data in all

DOCSP-47795 change batchsize descriptions #6292

Are you sure you want to change the base?

DOCSP-47795 change batchsize descriptions #6292

Conversation

shuangela commented Mar 14, 2025 • edited Loading

DESCRIPTION

STAGING

JIRA

SELF-REVIEW CHECKLIST

EXTERNAL REVIEW REQUIREMENTS

netlify bot commented Mar 14, 2025 • edited Loading

✅ Deploy Preview for mongodb-docs ready!

jmd-mongo 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

shuangela commented Mar 14, 2025

jmd-mongo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shuangela commented Mar 18, 2025

ChrisHarris2012 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

shuangela commented Apr 3, 2025

shuangela commented Mar 14, 2025 •

edited

Loading

netlify bot commented Mar 14, 2025 •

edited

Loading