diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index d99796fb2..f09f8db0e 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -281,6 +281,30 @@ public function testAggWithFilter(): void $this->assertIsFloat($result); } + public function testCountByGroup(): void + { + // begin count by group + $result = DB::table('movies') + ->groupBy('imdb.rating') + ->orderBy('imdb.rating') + ->countByGroup(); + // end count by group + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + + public function testSumByGroup(): void + { + // begin sum by group + $result = DB::table('movies') + ->groupBy('year') + ->orderBy('year') + ->sumByGroup('awards.wins'); + // end sum by group + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + public function testOrderBy(): void { // begin query orderBy diff --git a/docs/query-builder.txt b/docs/query-builder.txt index b3c89b0ae..23311831a 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -658,6 +658,56 @@ value of ``imdb.rating`` of those matches by using the :start-after: begin aggregation with filter :end-before: end aggregation with filter +Aggregate By Group Examples +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can perform an aggregation operation on a group +of documents by using the following query builder +methods, which return a single aggregated value for +each group: + +- ``countByGroup()``: Retrieves a count of the given field's + distinct values for each group + +- ``minByGroup()``: Retrieves the minimum value of the + given field for each group + +- ``maxByGroup()``: Retrieves the maximum value of the + given field for each group + +- ``sumByGroup()``: Retrieves the sum of a given field's + values for each group + +- ``avgByGroup()``: Retrieves the average of a given field's + values for each group + +countByGroup() Example +^^^^^^^^^^^^^^^^^^^^^^ + +The following example groups documents in the ``movies`` +collection by their ``imdb.rating`` values and returns +the number of documents that have each distinct +``imdb.rating`` value: + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin count by group + :end-before: end count by group + +sumByGroup() Example +^^^^^^^^^^^^^^^^^^^^ + +The following example groups documents in the ``movies`` +collection by their ``year`` values and returns +a sum of ``awards.wins`` values for each year: + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin sum by group + :end-before: end sum by group + .. _laravel-options-query-builder: Set Query-Level Options