From 67f3b4f9de3631b036317aef084b822157dbd3ae Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 5 Jul 2024 13:25:52 -0400 Subject: [PATCH 1/4] DOCSP-38380: array reads --- docs/fundamentals/read-operations.txt | 63 +++++++++++++++++-- .../read-operations/ReadOperationsTest.php | 32 ++++++++++ 2 files changed, 89 insertions(+), 6 deletions(-) diff --git a/docs/fundamentals/read-operations.txt b/docs/fundamentals/read-operations.txt index 8025f0087..a08d4ad18 100644 --- a/docs/fundamentals/read-operations.txt +++ b/docs/fundamentals/read-operations.txt @@ -57,16 +57,13 @@ You can use Laravel's Eloquent object-relational mapper (ORM) to create models that represent MongoDB collections and chain methods on them to specify query criteria. -To retrieve documents that match a set of criteria, pass a query filter to the -``where()`` method. +To retrieve documents that match a set of criteria, call the ``where()`` +method on the collection's corresponding Eloquent modelm then pass a query +filter. A query filter specifies field value requirements and instructs the find operation to return only documents that meet these requirements. -You can use Laravel's Eloquent object-relational mapper (ORM) to create models -that represent MongoDB collections. To retrieve documents from a collection, -call the ``where()`` method on the collection's corresponding Eloquent model. - You can use one of the following ``where()`` method calls to build a query: - ``where('', )`` builds a query that matches documents in @@ -150,6 +147,60 @@ retrieve documents that meet the following criteria: To learn how to query by using the Laravel query builder instead of the Eloquent ORM, see the :ref:`laravel-query-builder` page. +Match Array Field Elements +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can specify a query filter to match array field elements when +retrieving documents. If your documents contain an array field, you can +match documents based on if the value contains all or some specified +array elements. + +You can use one of the following ``where()`` method calls to build a +query on an array field: + +- ``where('', )`` builds a query that matches documents in + which the array field value is exactly the specified array + +- ``where('', 'in', )`` builds a query + that matches documents in which the array field value contains one or + more of the specified array elements + +After building your query with the ``where()`` method, chain the ``get()`` +method to retrieve the query results. + +Select from the following :guilabel:`Exact Array Match` and +:guilabel:`Element Match` tabs to view the query syntax for each pattern: + +.. tabs:: + + .. tab:: Exact Array Match + :tabid: exact-array + + This example retrieves documents in which the ``countries`` array is + exactly ``['Indonesia', 'Canada']``: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-exact-array + :end-before: end-exact-array + + .. tab:: Element Match + :tabid: element-match + + This example retrieves documents in which the ``countries`` array + contains one of the values in the array ``['Canada', 'Egypt']``: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-elem-match + :end-before: end-elem-match + +To learn how to query array fields by using the Laravel query builder instead of the +Eloquent ORM, see the :ref:`laravel-query-builder-elemMatch` section in +the Query Builder guide. + .. _laravel-retrieve-all: Retrieve All Documents in a Collection diff --git a/docs/includes/fundamentals/read-operations/ReadOperationsTest.php b/docs/includes/fundamentals/read-operations/ReadOperationsTest.php index a2080ec8f..75a1f20ee 100644 --- a/docs/includes/fundamentals/read-operations/ReadOperationsTest.php +++ b/docs/includes/fundamentals/read-operations/ReadOperationsTest.php @@ -33,6 +33,7 @@ protected function setUp(): void ['title' => 'movie_a', 'plot' => 'this is a love story'], ['title' => 'movie_b', 'plot' => 'love is a long story'], ['title' => 'movie_c', 'plot' => 'went on a trip'], + ['title' => 'movie_c', 'plot' => 'went on a trip'], ]); } @@ -133,4 +134,35 @@ public function testTextRelevance(): void $this->assertCount(1, $movies); $this->assertEquals('this is a love story', $movies[0]->plot); } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function exactArrayMatch(): void + { + // start-exact-array + $movies = Movie::where('countries', ['Indonesia', 'Canada']) + ->get(); + // end-exact-array + + $this->assertNotNull($movies); + $this->assertCount(1, $movies); + $this->assertEquals('Title 1', $movies[0]->title); + } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function arrayElemMatch(): void + { + // start-elem-match + $movies = Movie::where('countries', 'in', ['Canada', 'Egypt']) + ->get(); + // end-elem-match + + $this->assertNotNull($movies); + $this->assertCount(2, $movies); + } } From 5861f44edb883ce4f1f583d286093ff57ae39c09 Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 5 Jul 2024 13:27:06 -0400 Subject: [PATCH 2/4] fix --- docs/fundamentals/read-operations.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/fundamentals/read-operations.txt b/docs/fundamentals/read-operations.txt index a08d4ad18..bbc3eba3f 100644 --- a/docs/fundamentals/read-operations.txt +++ b/docs/fundamentals/read-operations.txt @@ -58,8 +58,8 @@ that represent MongoDB collections and chain methods on them to specify query criteria. To retrieve documents that match a set of criteria, call the ``where()`` -method on the collection's corresponding Eloquent modelm then pass a query -filter. +method on the collection's corresponding Eloquent model, then pass a query +filter to the method. A query filter specifies field value requirements and instructs the find operation to return only documents that meet these requirements. From a7105931f9701de045f3dfc583d64c6748f331fa Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 5 Jul 2024 16:35:34 -0400 Subject: [PATCH 3/4] NR PR fixes 1 --- docs/fundamentals/read-operations.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/fundamentals/read-operations.txt b/docs/fundamentals/read-operations.txt index bbc3eba3f..29437aa59 100644 --- a/docs/fundamentals/read-operations.txt +++ b/docs/fundamentals/read-operations.txt @@ -76,7 +76,7 @@ You can use one of the following ``where()`` method calls to build a query: To apply multiple sets of criteria to the find operation, you can chain a series of ``where()`` methods together. -After building your query with the ``where()`` method, chain the ``get()`` +After building your query by using the ``where()`` method, chain the ``get()`` method to retrieve the query results. This example calls two ``where()`` methods on the ``Movie`` Eloquent model to @@ -165,7 +165,7 @@ query on an array field: that matches documents in which the array field value contains one or more of the specified array elements -After building your query with the ``where()`` method, chain the ``get()`` +After building your query by using the ``where()`` method, chain the ``get()`` method to retrieve the query results. Select from the following :guilabel:`Exact Array Match` and @@ -251,7 +251,7 @@ by the ``$search`` field in your query filter that you pass to the ``where()`` method. The ``$text`` operator performs a text search on the text-indexed fields. The ``$search`` field specifies the text to search for. -After building your query with the ``where()`` method, chain the ``get()`` +After building your query by using the ``where()`` method, chain the ``get()`` method to retrieve the query results. This example calls the ``where()`` method on the ``Movie`` Eloquent model to From 8c2c713e1184d1971991a3810fcac29d6be7cc70 Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 8 Jul 2024 11:36:46 -0400 Subject: [PATCH 4/4] remove extra doc in test --- .../includes/fundamentals/read-operations/ReadOperationsTest.php | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/includes/fundamentals/read-operations/ReadOperationsTest.php b/docs/includes/fundamentals/read-operations/ReadOperationsTest.php index 75a1f20ee..c27680fb5 100644 --- a/docs/includes/fundamentals/read-operations/ReadOperationsTest.php +++ b/docs/includes/fundamentals/read-operations/ReadOperationsTest.php @@ -33,7 +33,6 @@ protected function setUp(): void ['title' => 'movie_a', 'plot' => 'this is a love story'], ['title' => 'movie_b', 'plot' => 'love is a long story'], ['title' => 'movie_c', 'plot' => 'went on a trip'], - ['title' => 'movie_c', 'plot' => 'went on a trip'], ]); }