Skip to content

DOCSP-47835 Clarify batchsize behavior #215

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 17 commits into from
Mar 11, 2025
Merged

DOCSP-47835 Clarify batchsize behavior #215

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
4d29070
change batchsize wording
shuangela Mar 5, 2025
bf79b9e
remove brackets
shuangela Mar 6, 2025
b02a39a
remove brackets
shuangela Mar 6, 2025
248115f
fix typo
shuangela Mar 6, 2025
6f46523
change formatting
shuangela Mar 6, 2025
a7bd71c
clarify wording based on rr feedback
shuangela Mar 6, 2025
269819f
change based on feedback
shuangela Mar 7, 2025
76d9bd5
clarify wording from jm feedback
shuangela Mar 7, 2025
69d3ed4
fix format
shuangela Mar 7, 2025
c18ef44
fix typo
shuangela Mar 7, 2025
e9aab32
rr feedback
shuangela Mar 10, 2025
6183d86
rr and jm feedback
shuangela Mar 10, 2025
89b304c
typo
shuangela Mar 10, 2025
635e787
style guide
shuangela Mar 10, 2025
debcfe1
fix typos
shuangela Mar 10, 2025
380a16e
fix rr
shuangela Mar 10, 2025
892f7ea
jm review
shuangela Mar 10, 2025
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
10 changes: 6 additions & 4 deletions source/includes/extracts-watch-option.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
ref: watch-option-batchSize
content: |
Specifies the batch size for the cursor, which will apply to both the initial
``aggregate`` command and any subsequent ``getMore`` commands. This determines
the maximum number of change events to return in each response from the
server.

Specifies the batch size for the cursor, which will apply to both the
initial ``aggregate`` command and any subsequent ``getMore`` commands.
If batchSize is set, ``aggregate`` and any subsequent ``getMore`` commands returns the smaller of 16 megabytes of data
or batchSize documents. Operations of type ``find``, ``aggregate``, ``listIndexes``, and ``listCollections`` return a maximum of ``16`` megabytes per batch.
Copy link
Contributor

Choose a reason for hiding this comment

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

S: these middle sentences dont communicate the information effectively.

Mu understanding is that this description should explain the following points:

  • Specifies the batch size for the cursor
  • Applies to the initial command and requests for more batches
  • Cannot increase the batch limit beyond 16mb and can only decrease/limit the batch size
  • If you set the batch size to a # that exceeds the sum of 16 MB in the batch, the option has no effect.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Question: to my knowledge, the default size that applies to the initial command (101 documents) and the default size (up to 16 mb) for requests for more batches is different. Should I clarify that as well? I was a little confused on the sections about batchsize in the find() and aggregate() function pages especially, because those to my knowledge are only initial commands (as getmore is the request for more batches). So in the find() and aggregate() pages, do you think it makes sense to only talk about the initial command and not the requests for more batches?

Copy link
Contributor

Choose a reason for hiding this comment

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

I think it works like this -

  • default setting - 101 documents for first batch, 16 mb limit for subsequent
  • custom setting (lets say 60) - 60 documents in first batch, 60 documents in subsequent batches as long as the total data size does not exceed 16 mb

When using the driver, users do not need to manually run a getMore command. The driver takes care of this internally. Thus, even though it is under the hood, the batch size would still apply to both the first and subsequent batches AFAIK. @jmikola do you have any insight into this clarification?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Oh, interesting, so getMore is not applicable at all in drivers contexts? Good to know.

Also, by total data size, do you mean added up the total size of all of the batches, or that the size of each individual batch has to be under 16 mb but the total size of batches combined can be > 16 mb? I interpreted it as each individual batch has to be under 16 mb but the total size doesn't matter.

I also thought that if we had a custom setting it would apply only to documents after the first batch, given this line from the engineer discussing issues in the batchSize docs in the slack thread linked in the ticket: "batchSize is about setting a ceiling for all batches after the first (which is 101)". However, would love clarification from Jeremy as well.

Copy link
Member

Choose a reason for hiding this comment

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

Also, by total data size, do you mean added up the total size of all of the batches, or that the size of each individual batch has to be under 16 mb but the total size of batches combined can be > 16 mb? I interpreted it as each individual batch has to be under 16 mb but the total size doesn't matter.

AFAIK, there is no documented restriction on the total size of all batches. The 16 MiB limit applies to each batch, and is discussed in the batchSize docs for the getMore command.

I can confirm that applications do not manually run getMore commands. Drivers take care of that when iterating a cursor.

@rustagir's understanding about the default and custom setting in this comment is correct.

Relevant docs within drivers for this would batchSize within the AggregateOptions and FindOptions sections of our CRUD spec, which talk about inheriting the option for subsequent getMore commands.

Additionally, our find/getMore/killCursors spec goes into more detail about how batchSize interacts with limit and skip. For example, when a limit is specified drivers may use a calculated value for batchSize to ensure we don't return more documents than necessary and guarantee that the server closes the cursor. This isn't something we need to rehash in driver docs, though, since it's handled internally. Furthermore, the server docs don't seem to talk about that either (in cursor.limit() and cursor.batchSize()).

Copy link
Contributor Author

@shuangela shuangela Mar 7, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Thanks Jeremy! Followup about MiB vs MB: is that difference salient in the docs? The internal engineering slack convo/docs refer to MiB rather than MB, but the php driver docs all refer to MB (16 MB vs 16 MiB). In your knowledge, would that difference be important to engineers using the batchsize command?

Copy link
Member

Choose a reason for hiding this comment

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

I expect the references to "MB" in the existing PHP docs are just old, and could pre-date when the server manual started using "MiB" consistently. There is no reason these can't all be changed to "MiB", although that needn't be done in this PR.

Anything relevant to this PR should use "MiB", though, so we stop introducing more instances of "MB".

batchSize can enforce a smaller limit than ``16`` megabytes, but not a larger one.

Irrespective of the ``batchSize`` option, the initial ``aggregate`` command
response for a change stream generally does not include any documents
Expand Down
4 changes: 3 additions & 1 deletion source/read/retrieve.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,7 +180,9 @@ you can set in the array:
- Description

* - ``batchSize``
- | The number of documents to return per batch. The default value is ``101``.
- | The limit for each batch returned in a query result. The ``find`` method has an initial batch size of ``101`` documents by default and returns a maximum of 16
megabytes per batch. Subsequent ``getMore`` operations issued against the resulting cursor have no default batch size,
so they are limited only by the ``16`` megabyte message size. batchSize can enforce a smaller limit than ``16`` megabytes, but not a larger one.
Copy link
Contributor

Choose a reason for hiding this comment

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

S: this revision seems to address the issue most clearly. Please also install the VS code extension for line wrapping

Suggested change
- | The limit for each batch returned in a query result. The ``find`` method has an initial batch size of ``101`` documents by default and returns a maximum of 16
megabytes per batch. Subsequent ``getMore`` operations issued against the resulting cursor have no default batch size,
so they are limited only by the ``16`` megabyte message size. batchSize can enforce a smaller limit than ``16`` megabytes, but not a larger one.
- | The size limit for the batches returned in a query result. By default,
the ``find()`` method has an initial batch size of ``101`` documents
and a maximum of 16 megabytes for each subsequent batch. This
option can enforce a smaller limit than 16 megabytes, but not a larger
one. If you set ``batchSize`` to a limit that results in batches larger than
16 MB, this option has no effect.

| **Type**: ``integer``

* - ``collation``
Expand Down
4 changes: 2 additions & 2 deletions source/reference/method/MongoDBCollection-find.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,8 +52,8 @@ Parameters

* - batchSize
- integer
- The number of documents to return in the first batch. Defaults to
``101``. A batchSize of ``0`` means that the cursor will be
- Sets the number of documents to return in the first batch if the number of documents to return is over ``101``.
Defaults to ``101``. A batchSize of ``0`` means that the cursor will be
established, but no documents will be returned in the first batch.
Copy link
Member

Choose a reason for hiding this comment

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

The special behavior of batchSize: 0 is notable, and also discussed in the find command docs. Particularly with aggregate operations, there is a legitimate use case for wanting to start the aggregation on the server without waiting for the first result to become available. Allowing a cursor to be created immediately and iterated later (via batchSize: 0 satisfies that).


Unlike the previous wire protocol version, a batchSize of ``1`` for the
Expand Down
9 changes: 6 additions & 3 deletions source/reference/method/MongoDBCollection-listSearchIndexes.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,10 +40,13 @@ Parameters

* - batchSize
- integer
- Specifies the batch size for the cursor, which will apply to both the
- Specifies the batch size for the cursor, which will apply to both thex
initial ``aggregate`` command and any subsequent ``getMore`` commands.
This determines the maximum number of documents to return in each
response from the server.
If batchSize is set, ``aggregate`` and any subsequent ``getMore`` commands returns the smaller of ``16`` megabytes of data
or batchSize documents. Operations of type ``find``, ``aggregate``, ``listIndexes``, and ``listCollections`` return a maximum of ``16`` megabytes per batch.
batchSize can enforce a smaller limit than ``16`` megabytes, but not a larger one.

If batchSize is not set, ``aggregate`` and ``getMore`` commands return up to ``16`` megabytes of data.

A batchSize of ``0`` is special in that and will only apply to the
initial ``aggregate`` command; subsequent ``getMore`` commands will use
Expand Down
12 changes: 10 additions & 2 deletions source/reference/method/MongoDBDatabase-aggregate.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,8 +56,16 @@ Parameters
- integer
- Specifies the batch size for the cursor, which will apply to both the
initial ``aggregate`` command and any subsequent ``getMore`` commands.
This determines the maximum number of documents to return in each
response from the server.
Copy link
Member

@jmikola jmikola Mar 7, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

I think we can discuss batchSize: 0 here as we do for the find() option, since there is a legitimate use case for doing so. I'm OK with keeping this in the API reference and out of the prose docs (e.g. read/retrieve.txt), since it's more technical.

There is also a special directive in the CRUD spec for drivers to intentionally omit batchSize for pipelines that include $out or $merge, since it might prevent the pipeline from executing (and writing output). I don't think we need to mention that, though, as it is enforced internally (see: Aggregate.php).


The ``aggregate`` command has an initial batch size of 101 documents by default.
Subsequent ``getMore`` operations issued against the resulting cursor have no default batch size,
so they are limited only by the ``16`` megabyte message size.

If batchSize is set, ``aggregate`` and any subsequent ``getMore`` commands returns the smaller of 16 megabytes of data
or batchSize documents. Operations of type ``aggregate`` return a maximum of ``16`` megabytes per batch.
batchSize can enforce a smaller limit than ``16`` megabytes, but not a larger one.

If batchSize is not set, ``aggregate`` and ``getMore`` commands return up to ``16`` megabytes of data.

A batchSize of ``0`` is special in that and will only apply to the
initial ``aggregate`` command; subsequent ``getMore`` commands will use
Expand Down
Loading