From 27fb8da1bea4365397df1a322dce7f01477c7e1d Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Mon, 10 Mar 2025 10:05:57 -0400 Subject: [PATCH] DOCSP-47217: pipeline param (#217) * DOCSP-47217: pipeline param * JT tech review comment (cherry picked from commit b2877518afe769aa2e96ace6920b60a64a13b6dc) --- source/aggregation.txt | 10 +++++----- source/aggregation/atlas-search.txt | 6 +++--- source/aggregation/vector-search.txt | 6 +++--- source/includes/aggregation/aggregation.php | 12 ++++++------ source/includes/aggregation/atlas-search.php | 9 +++++---- source/includes/aggregation/vector-search.php | 9 +++++---- source/read/cursor.txt | 8 +++++--- .../reference/method/MongoDBCollection-aggregate.txt | 8 +++++--- .../reference/method/MongoDBDatabase-aggregate.txt | 8 +++++--- source/whats-new.txt | 6 ++++++ 10 files changed, 48 insertions(+), 34 deletions(-) diff --git a/source/aggregation.txt b/source/aggregation.txt index 7fb5c52f..04506307 100644 --- a/source/aggregation.txt +++ b/source/aggregation.txt @@ -111,7 +111,7 @@ shown in the following code: $pipeline = [ ['' => ], ['' => ], - ... + // ... ]; $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::( ), Stage::( ), - ... - ]; + // ... + ); $cursor = $collection->aggregate($pipeline); diff --git a/source/aggregation/atlas-search.txt b/source/aggregation/atlas-search.txt index 8846459f..fad61e39 100644 --- a/source/aggregation/atlas-search.txt +++ b/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 --------------------------- diff --git a/source/aggregation/vector-search.txt b/source/aggregation/vector-search.txt index c1396ac7..f1bb534e 100644 --- a/source/aggregation/vector-search.txt +++ b/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: '', path: '', ...*/ ), - ]; + ); You must pass the following parameters to the ``vectorSearch()`` method: diff --git a/source/includes/aggregation/aggregation.php b/source/includes/aggregation/aggregation.php index 5aa56684..f8573ac4 100644 --- a/source/includes/aggregation/aggregation.php +++ b/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); diff --git a/source/includes/aggregation/atlas-search.php b/source/includes/aggregation/atlas-search.php index 80f165f2..9ace0445 100644 --- a/source/includes/aggregation/atlas-search.php +++ b/source/includes/aggregation/atlas-search.php @@ -1,6 +1,7 @@ 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); diff --git a/source/includes/aggregation/vector-search.php b/source/includes/aggregation/vector-search.php index c8e0c924..1509f9f5 100644 --- a/source/includes/aggregation/vector-search.php +++ b/source/includes/aggregation/vector-search.php @@ -1,6 +1,7 @@ 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); diff --git a/source/read/cursor.txt b/source/read/cursor.txt index 2ecee070..7f2f76f9 100644 --- a/source/read/cursor.txt +++ b/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() `: Call + on a ``MongoDB\Driver\Cursor`` object +- :php:`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()`. \ No newline at end of file +:phpmethod:`MongoDB\Collection::find()`. diff --git a/source/reference/method/MongoDBCollection-aggregate.txt b/source/reference/method/MongoDBCollection-aggregate.txt index ddbabe00..7f459acb 100644 --- a/source/reference/method/MongoDBCollection-aggregate.txt +++ b/source/reference/method/MongoDBCollection-aggregate.txt @@ -20,16 +20,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 ` - 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. @@ -186,6 +187,7 @@ group, and sorts the results by name. See Also -------- +- :ref:`php-aggregation` - :phpmethod:`MongoDB\Database::aggregate()` - :manual:`aggregate ` command reference in the MongoDB manual diff --git a/source/reference/method/MongoDBDatabase-aggregate.txt b/source/reference/method/MongoDBDatabase-aggregate.txt index 077f4e3a..fbe16304 100644 --- a/source/reference/method/MongoDBDatabase-aggregate.txt +++ b/source/reference/method/MongoDBDatabase-aggregate.txt @@ -24,16 +24,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 ` - 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. @@ -169,6 +170,7 @@ running command operations. See Also -------- +- :ref:`php-aggregation` - :phpmethod:`MongoDB\Collection::aggregate()` - :manual:`aggregate ` command reference in the MongoDB manual diff --git a/source/whats-new.txt b/source/whats-new.txt index dc2b4359..3965921a 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -64,6 +64,12 @@ and removals: replaced by these new methods in a future driver release, so consider changing the usages in your application. +- Modifies the :phpmethod:`MongoDB\Database::aggregate()` and + :phpmethod:`MongoDB\Collection::aggregate()` methods so they can + accept a ``Pipeline`` instance as the ``$pipeline`` parameter. To view + examples that use this construction, see the + :ref:`php-aggregation-builder-api` section of the Aggregation guide. + - Removes deprecated fields in GridFS types. - The library does not calculate the ``md5`` field when a file is