Merge pull request #589 from spitfire55/master

Add support for aggregate functions

Author: imor

bin/installcheck

@@ -35,17 +35,16 @@ createdb contrib_regression
 # Tests #
 #########
 TESTDIR="test"
-PGXS=$(dirname `pg_config --pgxs`)
+PGXS=$(dirname $(pg_config --pgxs))
 REGRESS="${PGXS}/../test/regress/pg_regress"
 
 # Test names can be passed as parameters to this script.
 # If any test names are passed run only those tests.
 # Otherwise run all tests.
-if [ "$#" -ne 0 ]
-then
-    TESTS=$@
+if [ "$#" -ne 0 ]; then
+  TESTS=$@
 else
-    TESTS=$(ls ${TESTDIR}/sql | sed -e 's/\..*$//' | sort )
+  TESTS=$(ls ${TESTDIR}/sql | sed -e 's/\..*$//' | sort)
 fi
 
 # Execute the test fixtures

docs/api.md

@@ -1,4 +1,3 @@
-
 In our API, each SQL table is reflected as a set of GraphQL types. At a high level, tables become types and columns/foreign keys become fields on those types.
 
 
@@ -167,6 +166,9 @@ Connections wrap a result set with some additional metadata.
       # Result set
       edges: [BlogEdge!]!
 
+      # Aggregate functions
+      aggregate: BlogAggregate
+
     }
     ```
 
@@ -264,8 +266,176 @@ Connections wrap a result set with some additional metadata.
 
     The `totalCount` field is disabled by default because it can be expensive on large tables. To enable it use a [comment directive](configuration.md#totalcount)
 
+#### Aggregates
+
+Aggregate functions are available on the collection's `aggregate` field when enabled via [comment directive](configuration.md#aggregate). These allow you to perform calculations on the collection of records that match your filter criteria.
+
+The supported aggregate operations are:
+
+- **count**: Always available, returns the number of records matching the query
+- **sum**: Available for numeric fields, returns the sum of values
+- **avg**: Available for numeric fields, returns the average (mean) of values
+- **min**: Available for numeric, string, boolean, and date/time fields, returns the minimum value
+- **max**: Available for numeric, string, boolean, and date/time fields, returns the maximum value
+
+**Example**
+
+=== "Query"
+
+    ```graphql
+    {
+      blogCollection(
+        filter: { rating: { gt: 3 } }
+      ) {
+        aggregate {
+          count
+          sum {
+            rating
+            visits
+          }
+          avg {
+            rating
+          }
+          min {
+            createdAt
+            title
+          }
+          max {
+            rating
+            updatedAt
+          }
+        }
+      }
+    }
+    ```
+
+=== "Response"
+
+    ```json
+    {
+      "data": {
+        "blogCollection": {
+          "aggregate": {
+            "count": 5,
+            "sum": {
+              "rating": 23,
+              "visits": 1250
+            },
+            "avg": {
+              "rating": 4.6
+            },
+            "min": {
+              "createdAt": "2022-01-15T08:30:00Z",
+              "title": "A Blog Post"
+            },
+            "max": {
+              "rating": 5,
+              "updatedAt": "2023-04-22T14:15:30Z"
+            }
+          }
+        }
+      }
+    }
+    ```
+
+**GraphQL Types**
+=== "BlogAggregate"
+
+    ```graphql
+    """Aggregate results for `Blog`"""
+    type BlogAggregate {
+      """The number of records matching the query"""
+      count: Int!
+
+      """Summation aggregates for `Blog`"""
+      sum: BlogSumAggregateResult
+
+      """Average aggregates for `Blog`"""
+      avg: BlogAvgAggregateResult
+
+      """Minimum aggregates for comparable fields"""
+      min: BlogMinAggregateResult
+
+      """Maximum aggregates for comparable fields"""
+      max: BlogMaxAggregateResult
+    }
+    ```
+
+=== "BlogSumAggregateResult"
+
+    ```graphql
+    """Result of summation aggregation for `Blog`"""
+    type BlogSumAggregateResult {
+      """Sum of rating values"""
+      rating: BigFloat
+
+      """Sum of visits values"""
+      visits: BigInt
+
+      # Other numeric fields...
+    }
+    ```
+
+=== "BlogAvgAggregateResult"
+
+    ```graphql
+    """Result of average aggregation for `Blog`"""
+    type BlogAvgAggregateResult {
+      """Average of rating values"""
+      rating: BigFloat
+
+      """Average of visits values"""
+      visits: BigFloat
+
+      # Other numeric fields...
+    }
+    ```
+
+=== "BlogMinAggregateResult"
 
+    ```graphql
+    """Result of minimum aggregation for `Blog`"""
+    type BlogMinAggregateResult {
+      """Minimum rating value"""
+      rating: Float
+
+      """Minimum title value"""
+      title: String
+
+      """Minimum createdAt value"""
+      createdAt: Datetime
+
+      # Other comparable fields...
+    }
+    ```
+
+=== "BlogMaxAggregateResult"
+
+    ```graphql
+    """Result of maximum aggregation for `Blog`"""
+    type BlogMaxAggregateResult {
+      """Maximum rating value"""
+      rating: Float
+
+      """Maximum title value"""
+      title: String
+
+      """Maximum updatedAt value"""
+      updatedAt: Datetime
+
+      # Other comparable fields...
+    }
+    ```
+
+!!! note
+
+    - The return type for `sum` depends on the input type: integer fields return `BigInt`, while other numeric fields return `BigFloat`.
+    - The return type for `avg` is always `BigFloat`.
+    - The return types for `min` and `max` match the original field types.
+
+!!! note
 
+    The `aggregate` field is disabled by default because it can be expensive on large tables. To enable it use a [comment directive](configuration.md#Aggregate)
 
 #### Pagination
 

docs/changelog.md

@@ -95,3 +95,4 @@
 - bugfix: qualify schema refs
 
 ## master
+- feature: Add support for aggregate functions (count, sum, avg, min, max) on collection types

docs/configuration.md

@@ -95,6 +95,41 @@ create table "BlogPost"(
 comment on table "BlogPost" is e'@graphql({"totalCount": {"enabled": true}})';
 ```
 
+### Aggregate
+
+The `aggregate` field is an opt-in field that extends a table's Connection type. It provides various aggregate functions like count, sum, avg, min, and max that operate on the collection of records that match the query's filters.
+
+```graphql
+type BlogPostConnection {
+  edges: [BlogPostEdge!]!
+  pageInfo: PageInfo!
+
+  """Aggregate functions calculated on the collection of `BlogPost`"""
+  aggregate: BlogPostAggregate # this field
+}
+```
+
+To enable the `aggregate` field for a table, use the directive:
+
+```sql
+comment on table "BlogPost" is e'@graphql({"aggregate": {"enabled": true}})';
+```
+
+For example:
+```sql
+create table "BlogPost"(
+    id serial primary key,
+    title varchar(255) not null,
+    rating int not null
+);
+comment on table "BlogPost" is e'@graphql({"aggregate": {"enabled": true}})';
+```
+
+You can combine both totalCount and aggregate directives:
+
+```sql
+comment on table "BlogPost" is e'@graphql({"totalCount": {"enabled": true}, "aggregate": {"enabled": true}})';
+```
 
 ### Renaming
 

sql/load_sql_context.sql

@@ -256,6 +256,14 @@ select
                                                 false
                                             )
                                         ),
+                                        'aggregate', jsonb_build_object(
+                                            'enabled', coalesce(
+                                                (
+                                                    d.directive -> 'aggregate' ->> 'enabled' = 'true'
+                                                ),
+                                                false
+                                            )
+                                        ),
                                         'primary_key_columns', d.directive -> 'primary_key_columns',
                                         'foreign_keys', d.directive -> 'foreign_keys'
                                     )