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

DOCSP-47835 Clarify batchsize behavior

Author: shuangela

snooty.toml

@@ -21,7 +21,6 @@ toc_landing_pages = [
     "/reference/class/MongoDBModelCollectionInfo",
     "/reference/class/MongoDBModelDatabaseInfo",
     "/reference/class/MongoDBModelIndexInfo",
-    "/get-started",
     "/connect",
     "/read",
     "/databases-collections",

source/aggregation.txt

@@ -111,7 +111,7 @@ shown in the following code:
    $pipeline = [
        ['<stage>' => <parameters>],
        ['<stage>' => <parameters>],
-       ...
+       // ...
    ];
 
    $cursor = $collection->aggregate($pipeline);
@@ -196,7 +196,7 @@ Aggregation Builder
 To create an aggregation pipeline by using the Aggregation Builder,
 perform the following actions:
 
-1. Create an array to store the pipeline stages.
+1. Create a ``MongoDB\Builder\Pipeline`` instance to store the pipeline stages.
 
 #. For each stage, call the a factory method from the
    ``Stage`` that shares the same name as your desired aggregation
@@ -212,15 +212,15 @@ aggregation pipelines:
 
 .. code-block:: php
 
-   $pipeline = [
+   $pipeline = new Pipeline(
        Stage::<factory method>(
            <stage specification>
        ),
        Stage::<factory method>(
            <stage specification>
        ),
-       ...
-   ];
+       // ...
+   );
 
    $cursor = $collection->aggregate($pipeline);
 

source/aggregation/atlas-search.txt

@@ -65,7 +65,7 @@ Search queries by using the Aggregation Builder:
 To create a ``$search`` stage in your aggregation pipeline, perform the
 following actions:
 
-1. Create an array to store the pipeline stages.
+1. Create a ``Pipeline`` instance to store the pipeline stages.
 
 #. Call the ``Stage::search()`` method to create the Atlas Search stage.
 
@@ -77,12 +77,12 @@ queries:
 
 .. code-block:: php
 
-   $pipeline = [
+   $pipeline = new Pipeline(
        Stage::search(
            /* Atlas Search query specifications
            Search::compound(...) */
        ),
-   ];
+   );
 
 Atlas Search Query Examples
 ---------------------------

source/aggregation/vector-search.txt

@@ -66,7 +66,7 @@ Search queries by using the Aggregation Builder:
 To create a ``$vectorSearch`` stage in your aggregation pipeline, perform the
 following actions:
 
-1. Create an array to store the pipeline stages.
+1. Create a ``Pipeline`` instance to store the pipeline stages.
 
 #. Call the ``Stage::vectorSearch()`` method to create the Atlas Vector
    Search stage.
@@ -79,13 +79,13 @@ queries:
 
 .. code-block:: php
 
-   $pipeline = [
+   $pipeline = new Pipeline(
        Stage::vectorSearch(
            /* Atlas Vector Search query specifications
            index: '<index name>',
            path: '<path to embeddings>', ...*/
        ),
-   ];
+   );
 
 You must pass the following parameters to the ``vectorSearch()`` method:
 

source/includes/aggregation/aggregation.php

@@ -40,7 +40,7 @@
 // end-array-explain
 
 // start-builder-match-group
-$pipeline = [
+$pipeline = new MongoDB\Builder\Pipeline(
     MongoDB\Builder\Stage::match(
         date: [
             MongoDB\Builder\Query::gte(new MongoDB\BSON\UTCDateTime(new DateTimeImmutable('2014-01-01'))),
@@ -63,7 +63,7 @@
     MongoDB\Builder\Stage::sort(
         totalSaleAmount: MongoDB\Builder\Type\Sort::Desc,
     ),
-];
+);
 
 $cursor = $collection->aggregate($pipeline);
 
@@ -73,7 +73,7 @@
 // end-builder-match-group
 
 // start-builder-unwind
-$pipeline = [
+$pipeline = new MongoDB\Builder\Pipeline(
     MongoDB\Builder\Stage::unwind(MongoDB\Builder\Expression::arrayFieldPath('items')),
     MongoDB\Builder\Stage::unwind(MongoDB\Builder\Expression::arrayFieldPath('items.tags')),
     MongoDB\Builder\Stage::group(
@@ -85,7 +85,7 @@
             ),
         ),
     ),
-];
+);
 
 $cursor = $collection->aggregate($pipeline);
 
@@ -97,14 +97,14 @@
 $collection = $client->db->orders;
 
 // start-builder-lookup
-$pipeline = [
+$pipeline = new MongoDB\Builder\Pipeline(
     MongoDB\Builder\Stage::lookup(
         from: 'inventory',
         localField: 'item',
         foreignField: 'sku',
         as: 'inventory_docs',
     ),
-];
+);
 
 /* Performs the aggregation on the orders collection */
 $cursor = $collection->aggregate($pipeline);

source/includes/aggregation/atlas-search.php

@@ -1,6 +1,7 @@
 <?php
 
 // start-imports
+use MongoDB\Builder\Pipeline;
 use MongoDB\Builder\Search;
 use MongoDB\Builder\Stage;
 // end-imports
@@ -34,7 +35,7 @@
 echo "\n";
 
 // start-compound-search-query
-$pipeline = [
+$pipeline = new Pipeline(
     Stage::search(
         Search::compound(
             must: [
@@ -63,7 +64,7 @@
         name: 1
     ),
     Stage::limit(3)
-];
+);
 
 $cursor = $collection->aggregate($pipeline);
 
@@ -109,7 +110,7 @@
 echo "\n";
 
 // start-autocomplete-search-query
-$pipeline = [
+$pipeline = new Pipeline(
     Stage::search(
         Search::autocomplete(
             query: 'Lucy',
@@ -118,7 +119,7 @@
     ),
     Stage::limit(3),
     Stage::project(_id: 0, name: 1),
-];
+);
 
 $cursor = $collection->aggregate($pipeline);
 

source/includes/aggregation/vector-search.php

@@ -1,6 +1,7 @@
 <?php
 
 // start-imports
+use MongoDB\Builder\Pipeline;
 use MongoDB\Builder\Stage;
 // end-imports
 
@@ -42,7 +43,7 @@
 echo "\n";
 
 // start-basic-query
-$pipeline = [
+$pipeline = new Pipeline(
     Stage::vectorSearch(
         index: 'vector',
         path: 'plot_embedding',
@@ -54,7 +55,7 @@
         _id: 0,
         title: 1,
     ),
-];
+);
 
 $cursor = $collection->aggregate($pipeline);
 
@@ -64,7 +65,7 @@
 // end-basic-query
 
 // start-score-query
-$pipeline = [
+$pipeline = new Pipeline(
     Stage::vectorSearch(
         index: 'vector',
         path: 'plot_embedding',
@@ -77,7 +78,7 @@
         title: 1,
         score: ['$meta' => 'vectorSearchScore'],
     ),
-];
+);
 
 $cursor = $collection->aggregate($pipeline);
 

source/includes/get-started/troubleshoot.rst

@@ -1,6 +1,6 @@
 .. note::
 
-   If you run into issues on this step, ask for help in the
+   If you run into issues in this tutorial, ask for help in the
    :community-forum:`MongoDB Community Forums <tag/php/>`
    or submit feedback by using the :guilabel:`Rate this page`
    tab on the right or bottom right side of this page.

source/read/cursor.txt

@@ -115,8 +115,10 @@ Retrieve All Documents
 To retrieve all documents from a cursor, convert the cursor into an array by using
 either of the following methods:
 
-- ``MongoDB\\Driver\\Cursor::toArray()``: Call on a ``MongoDB\Driver\Cursor`` object
-- ``iterator_to_array()``: Pass a ``MongoDB\Driver\Cursor`` object as a parameter
+- :php:`MongoDB\Driver\Cursor::toArray() <mongodb-driver-cursor.toarray>`: Call
+  on a ``MongoDB\Driver\Cursor`` object
+- :php:`iterator_to_array() <function.iterator-to-array>`: Pass a
+  ``MongoDB\Driver\Cursor`` object as a parameter
 
 The following example calls the ``toArray()`` method on a cursor to store its results
 in an array:
@@ -187,4 +189,4 @@ API Documentation
 ~~~~~~~~~~~~~~~~~
 
 To learn more about the ``find()`` method, see the API documentation for
-:phpmethod:`MongoDB\Collection::find()`.
+:phpmethod:`MongoDB\Collection::find()`.

source/reference/method/MongoDBCollection-aggregate.txt

@@ -21,16 +21,17 @@ Definition
    .. code-block:: php
 
       function aggregate(
-          array $pipeline,
+          array|Pipeline $pipeline,
           array $options = []
       ): Traversable
 
 Parameters
 ----------
 
-``$pipeline`` : array
+``$pipeline`` : array|Pipeline
   Specifies an :manual:`aggregation pipeline </core/aggregation-pipeline>`
-  operation.
+  operation. You can include aggregation stages in a
+  ``MongoDB\Builder\Pipeline`` instance or in an array.
 
 ``$options`` : array
   An array specifying the desired options.
@@ -187,6 +188,7 @@ group, and sorts the results by name.
 See Also
 --------
 
+- :ref:`php-aggregation`
 - :phpmethod:`MongoDB\Database::aggregate()`
 - :manual:`aggregate </reference/command/aggregate>` command reference in the
   MongoDB manual

source/reference/method/MongoDBDatabase-aggregate.txt

@@ -25,16 +25,17 @@ Definition
    .. code-block:: php
 
       function aggregate(
-          array $pipeline,
+          array|Pipeline $pipeline,
           array $options = []
       ): Traversable
 
 Parameters
 ----------
 
-``$pipeline`` : array
+``$pipeline`` : array|Pipeline
   Specifies an :manual:`aggregation pipeline </core/aggregation-pipeline>`
-  operation.
+  operation. You can include aggregation stages in a
+  ``MongoDB\Builder\Pipeline`` instance or in an array.
 
 ``$options`` : array
   An array specifying the desired options.
@@ -170,6 +171,7 @@ running command operations.
 See Also
 --------
 
+- :ref:`php-aggregation`
 - :phpmethod:`MongoDB\Collection::aggregate()`
 - :manual:`aggregate </reference/command/aggregate>` command reference in the
   MongoDB manual