Put aggregates behind comment directive

Author: spitfire55

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.
 
 
@@ -269,7 +268,7 @@ Connections wrap a result set with some additional metadata.
 
 #### Aggregates
 
-Aggregate functions are available on the collection's `aggregate` field. These allow you to perform calculations on the collection of records that match your filter criteria.
+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:
 
@@ -434,6 +433,10 @@ The supported aggregate operations are:
     - 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
 
 ##### Keyset Pagination

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'
                                     )

src/graphql.rs

@@ -1745,21 +1745,26 @@ impl ___Type for ConnectionType {
             }
         }
 
-        let aggregate = __Field {
-            name_: "aggregate".to_string(),
-            type_: __Type::Aggregate(AggregateType {
-                table: Arc::clone(&self.table),
-                schema: self.schema.clone(),
-            }),
-            args: vec![],
-            description: Some(format!(
-                "Aggregate functions calculated on the collection of `{table_base_type_name}`"
-            )),
-            deprecation_reason: None,
-            sql_type: None,
-        };
+        // Conditionally add aggregate based on the directive
+        if let Some(aggregate_directive) = self.table.directives.aggregate.as_ref() {
+            if aggregate_directive.enabled {
+                let aggregate = __Field {
+                    name_: "aggregate".to_string(),
+                    type_: __Type::Aggregate(AggregateType {
+                        table: Arc::clone(&self.table),
+                        schema: self.schema.clone(),
+                    }),
+                    args: vec![],
+                    description: Some(format!(
+                        "Aggregate functions calculated on the collection of `{table_base_type_name}`"
+                    )),
+                    deprecation_reason: None,
+                    sql_type: None,
+                };
+                fields.push(aggregate);
+            }
+        }
 
-        fields.push(aggregate); // Add aggregate last
         Some(fields)
     }
 }
@@ -4222,43 +4227,48 @@ impl __Schema {
 
             // Add Aggregate types if the table is selectable
             if self.graphql_table_select_types_are_valid(table) {
-                types_.push(__Type::Aggregate(AggregateType {
-                    table: Arc::clone(table),
-                    schema: Arc::clone(&schema_rc),
-                }));
-                // Check if there are any columns aggregatable by sum/avg
-                if table
-                    .columns
-                    .iter()
-                    .any(|c| is_aggregatable(c, &AggregateOperation::Sum))
-                {
-                    types_.push(__Type::AggregateNumeric(AggregateNumericType {
-                        table: Arc::clone(table),
-                        schema: Arc::clone(&schema_rc),
-                        aggregate_op: AggregateOperation::Sum,
-                    }));
-                    types_.push(__Type::AggregateNumeric(AggregateNumericType {
-                        table: Arc::clone(table),
-                        schema: Arc::clone(&schema_rc),
-                        aggregate_op: AggregateOperation::Avg,
-                    }));
-                }
-                // Check if there are any columns aggregatable by min/max
-                if table
-                    .columns
-                    .iter()
-                    .any(|c| is_aggregatable(c, &AggregateOperation::Min))
-                {
-                    types_.push(__Type::AggregateNumeric(AggregateNumericType {
-                        table: Arc::clone(table),
-                        schema: Arc::clone(&schema_rc),
-                        aggregate_op: AggregateOperation::Min,
-                    }));
-                    types_.push(__Type::AggregateNumeric(AggregateNumericType {
-                        table: Arc::clone(table),
-                        schema: Arc::clone(&schema_rc),
-                        aggregate_op: AggregateOperation::Max,
-                    }));
+                // Only add aggregate types if the directive is enabled
+                if let Some(aggregate_directive) = table.directives.aggregate.as_ref() {
+                    if aggregate_directive.enabled {
+                        types_.push(__Type::Aggregate(AggregateType {
+                            table: Arc::clone(table),
+                            schema: Arc::clone(&schema_rc),
+                        }));
+                        // Check if there are any columns aggregatable by sum/avg
+                        if table
+                            .columns
+                            .iter()
+                            .any(|c| is_aggregatable(c, &AggregateOperation::Sum))
+                        {
+                            types_.push(__Type::AggregateNumeric(AggregateNumericType {
+                                table: Arc::clone(table),
+                                schema: Arc::clone(&schema_rc),
+                                aggregate_op: AggregateOperation::Sum,
+                            }));
+                            types_.push(__Type::AggregateNumeric(AggregateNumericType {
+                                table: Arc::clone(table),
+                                schema: Arc::clone(&schema_rc),
+                                aggregate_op: AggregateOperation::Avg,
+                            }));
+                        }
+                        // Check if there are any columns aggregatable by min/max
+                        if table
+                            .columns
+                            .iter()
+                            .any(|c| is_aggregatable(c, &AggregateOperation::Min))
+                        {
+                            types_.push(__Type::AggregateNumeric(AggregateNumericType {
+                                table: Arc::clone(table),
+                                schema: Arc::clone(&schema_rc),
+                                aggregate_op: AggregateOperation::Min,
+                            }));
+                            types_.push(__Type::AggregateNumeric(AggregateNumericType {
+                                table: Arc::clone(table),
+                                schema: Arc::clone(&schema_rc),
+                                aggregate_op: AggregateOperation::Max,
+                            }));
+                        }
+                    }
                 }
             }
         }

src/sql_types.rs

@@ -447,6 +447,11 @@ pub struct TableDirectiveTotalCount {
     pub enabled: bool,
 }
 
+#[derive(Deserialize, Clone, Debug, Eq, PartialEq, Hash)]
+pub struct TableDirectiveAggregate {
+    pub enabled: bool,
+}
+
 #[derive(Deserialize, Clone, Debug, Eq, PartialEq, Hash)]
 pub struct TableDirectiveForeignKey {
     // Equivalent to ForeignKeyDirectives.local_name
@@ -471,6 +476,9 @@ pub struct TableDirectives {
     // @graphql({"totalCount": { "enabled": true } })
     pub total_count: Option<TableDirectiveTotalCount>,
 
+    // @graphql({"aggregate": { "enabled": true } })
+    pub aggregate: Option<TableDirectiveAggregate>,
+
     // @graphql({"primary_key_columns": ["id"]})
     pub primary_key_columns: Option<Vec<String>>,
 

test/expected/aggregate_directive.out

@@ -0,0 +1,64 @@
+begin;
+
+-- Create a simple table without any directives
+create table product(
+    id serial primary key,
+    name text not null,
+    price numeric not null,
+    stock int not null
+);
+
+insert into product(name, price, stock)
+values
+    ('Widget', 9.99, 100),
+    ('Gadget', 19.99, 50),
+    ('Gizmo', 29.99, 25);
+
+-- Try to query aggregate without enabling the directive - should fail
+select graphql.resolve($$
+{
+  productCollection {
+    aggregate {
+      count
+    }
+  }
+}
+$$);
+                                resolve                                 
+------------------------------------------------------------------------
+ {"data": null, "errors": [{"message": "unknown field in connection"}]}
+(1 row)
+
+-- Enable aggregates
+comment on table product is e'@graphql({"aggregate": {"enabled": true}})';
+
+-- Now aggregates should be available - should succeed
+select graphql.resolve($$
+{
+  productCollection {
+    aggregate {
+      count
+      sum {
+        price
+        stock
+      }
+      avg {
+        price
+      }
+      max {
+        price
+        name
+      }
+      min {
+        stock
+      }
+    }
+  }
+}
+$$);
+                                                                           resolve                                                                            
+--------------------------------------------------------------------------------------------------------------------------------------------------------------
+ {"data": {"productCollection": {"aggregate": {"avg": {"price": 19.99}, "count": 3, "max": {"name": "Widget", "price": 29.99}, "min": {"stock": 25}, "sum": {"price": 59.97, "stock": 175}}}}}
+(1 row)
+
+rollback; 

test/sql/aggregate_directive.sql

@@ -0,0 +1,56 @@
+begin;
+
+-- Create a simple table without any directives
+create table product(
+    id serial primary key,
+    name text not null,
+    price numeric not null,
+    stock int not null
+);
+
+insert into product(name, price, stock)
+values
+    ('Widget', 9.99, 100),
+    ('Gadget', 19.99, 50),
+    ('Gizmo', 29.99, 25);
+
+-- Try to query aggregate without enabling the directive - should fail
+select graphql.resolve($$
+{
+  productCollection {
+    aggregate {
+      count
+    }
+  }
+}
+$$);
+
+-- Enable aggregates
+comment on table product is e'@graphql({"aggregate": {"enabled": true}})';
+
+-- Now aggregates should be available - should succeed
+select graphql.resolve($$
+{
+  productCollection {
+    aggregate {
+      count
+      sum {
+        price
+        stock
+      }
+      avg {
+        price
+      }
+      max {
+        price
+        name
+      }
+      min {
+        stock
+      }
+    }
+  }
+}
+$$);
+
+rollback;