Merge pull request mongodb#215 from shuangela/DOCSP-47835-clarify-batchsize

DOCSP-47835 Clarify batchsize behavior

Author: shuangela

source/includes/extracts-watch-option.yaml

@@ -1,9 +1,10 @@
 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.
+  The maximum number of documents within each batch returned in a change stream, which applies 
+  to the ``aggregate`` command. By default, the ``aggregate`` 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.
 
   Irrespective of the ``batchSize`` option, the initial ``aggregate`` command
   response for a change stream generally does not include any documents

source/read/retrieve.txt

@@ -180,7 +180,12 @@ you can set in the array:
      - Description
 
    * - ``batchSize`` 
-     - | The number of documents to return per batch. The default value is ``101``.
+     - | 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) 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.
        | **Type**: ``integer``
 
    * - ``collation`` 

source/reference/method/MongoDBCollection-find.txt

@@ -54,9 +54,14 @@ 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
-         established, but no documents will be returned in the first batch.
+       - 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)
+         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.
+
+         A batchSize of ``0`` means that the cursor will be established, but no documents 
+         will be returned in the first batch.
 
          Unlike the previous wire protocol version, a batchSize of ``1`` for the
          :dbcommand:`find` command does not close the cursor.

source/reference/method/MongoDBCollection-listSearchIndexes.txt

@@ -41,16 +41,12 @@ Parameters
 
      * - batchSize
        - 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.
-
-         A batchSize of ``0`` is special in that and will only apply to the
-         initial ``aggregate`` command; subsequent ``getMore`` commands will use
-         the server's default batch size. This may be useful for quickly
-         returning a cursor or failure from ``aggregate`` without doing
-         significant server-side work.
+       - The maximum number of documents within each batch returned in the indexes list, which applies 
+         to the ``aggregate`` command. By default, the ``aggregate`` 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.
 
      * - codec
        - MongoDB\\Codec\\DocumentCodec

source/reference/method/MongoDBDatabase-aggregate.txt

@@ -55,16 +55,16 @@ Parameters
 
      * - batchSize
        - 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.
-
-         A batchSize of ``0`` is special in that and will only apply to the
-         initial ``aggregate`` command; subsequent ``getMore`` commands will use
-         the server's default batch size. This may be useful for quickly
-         returning a cursor or failure from ``aggregate`` without doing
-         significant server-side work.
+       - The maximum number of documents within each batch returned in a query result.
+         By default, the ``aggregate`` 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.
+
+         A batchSize of ``0`` means that the cursor will be established, but no documents 
+         will be returned in the first batch. This may be useful for quickly returning a cursor
+         or failure from ``aggregate`` without doing significant server-side work.
 
      * - bypassDocumentValidation
        - boolean