DOCSP-46415: Group by aggregation methods

Author: norareidy

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->assertIsArray($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->assertIsArray($result);
+    }
+
     public function testOrderBy(): void
     {
         // begin query orderBy

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