From 061935f6f951ddcb7eeae1777e10d9a23298ef79 Mon Sep 17 00:00:00 2001
From: shuangela <angela.shu@mongodb.com>
Date: Tue, 25 Mar 2025 11:20:45 -0400
Subject: [PATCH] DOCSP-47834 clarify batch size (#524)

* clarify batch size

* change find

* clarify no effect

* fix wrapping

* remove extra space

* review

(cherry picked from commit 9d38c02b6c2bdaea27677eae4238d531b605586a)
---
 .../crud/read-operations/change-streams.txt         | 13 ++++++++++---
 .../fundamentals/crud/read-operations/retrieve.txt  |  8 +++++++-
 2 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/source/fundamentals/crud/read-operations/change-streams.txt b/source/fundamentals/crud/read-operations/change-streams.txt
index d30f55a2..77231220 100644
--- a/source/fundamentals/crud/read-operations/change-streams.txt
+++ b/source/fundamentals/crud/read-operations/change-streams.txt
@@ -284,9 +284,16 @@ of ``Watch()`` and ``WatchAsync()``:
          include expanded events in a change stream, create the change stream
          cursor and set this parameter to ``True``.
 
-   * - ``BatchSize``
-     - | Specifies the maximum number of change events to return in each batch of the
-         response from the MongoDB cluster.
+   * - ``batchSize``
+     - | Specifies the maximum number of documents that a change
+         stream can return in each batch, which applies to ``Watch()`` or
+         ``WatchAsync()``. If the ``batchSize`` option is not set, watch functions have 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 result in batches
+         larger than 16 MiB, this option has no effect and ``Watch()``
+         or ``WatchAsync()`` uses the default batch size.
 
    * - ``Collation``
      - | Specifies the collation to use for the change stream cursor.
diff --git a/source/fundamentals/crud/read-operations/retrieve.txt b/source/fundamentals/crud/read-operations/retrieve.txt
index abd171f6..bce5fa11 100644
--- a/source/fundamentals/crud/read-operations/retrieve.txt
+++ b/source/fundamentals/crud/read-operations/retrieve.txt
@@ -205,7 +205,13 @@ You can configure the commonly used options with the following methods:
      - Description
 
    * - ``BatchSize`` 
-     - | Gets or sets the number of documents to hold in a cursor at a given time.
+     - | Gets or sets the maximum number of documents within each
+         batch returned in a query result. If ``batchSize`` is not set, the ``Find()``
+         method 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 and the
+         ``Find()`` method uses the default batch size.
 
    * - ``Collation`` 
      - | Sets the collation options.