add documentation for group by directive

modules/ROOT/pages/directives/index.adoc

@@ -100,6 +100,9 @@ Particularly useful for types that are not correctly pluralized or are non-Engli
 | xref:/directives/schema-configuration/field-configuration.adoc#_filterable[`@filterable`]
 | Defines the filters generated for a field.
 
+| xref:/directives/schema-configuration/field-configuration.adoc#_groupBy[`@groupBy`]
+| Defines a field that can be used to group by in queries.
+
 |===
 
 == Indexes and constraints

modules/ROOT/pages/directives/schema-configuration/field-configuration.adoc

@@ -565,3 +565,110 @@ input ActorActedInNodeAggregationWhereInput {
 ----
 
 As shown by the previous inputs fields, the `actors` field is not available for filtering on both value and aggregation filters.
+
+
+== `@groupBy`
+
+This directive defines fields that can be used to group query results.
+
+=== Definition
+
+[source, graphql, indent=0]
+----
+"""Enables groupBy operations for this field."""
+directive @groupBy() on FIELD_DEFINITION
+----
+
+=== Usage
+
+Consider the following definition:
+
+[source, graphql, indent=0]
+----
+type Movie @node {
+    title: String!
+    year: Int! @groupBy
+}
+----
+
+It adds the field `groupBy` to the `movieConnection` operation.
+The field allows you to query movies grouped by the `year` field.
+
+
+The `groupBy` field has one argument `fields`, that defines the field to group by.
+In this case `year` is the only option.
+
+[source, graphql, indent=0]
+----
+query {
+  moviesConnection {
+    groupBy(fields: { year: true }) {
+      edges {
+        node {
+          title
+          year
+        }
+      }
+    }
+  }
+}
+----
+
+The `groupBy` field returns a list of results and each result contains a list of `edges`, with all results grouped by the `year` field.
+For example:
+
+[source, json, indent=0]
+----
+{
+    "moviesConnection": {
+        "groupBy": [
+            {
+                "edges": [
+                    {
+                        "node": {
+                            "title": "The Matrix",
+                            "year": 1999
+                        }
+                    },
+                    {
+                        "title": "Fight Club",
+                        "year": 1999
+                    }
+                ]
+            },
+            {
+                "edges": [
+                    {
+                        "node": {
+                            "title": "Gladiator",
+                            "year": 2000
+                        }
+                    }
+                ]
+            }
+        ]
+    }
+}
+----
+
+Note that the `year` field is repeated on every node of the `edges` from each `groupBy` result.
+
+Nodes can be grouped by multiple fields:
+
+[source, graphql, indent=0]
+----
+query {
+  moviesConnection {
+    groupBy(fields: { year: true, rating: true }) {
+      edges {
+        node {
+          title
+          year
+        }
+      }
+    }
+  }
+}
+----
+
+In this case, all movies with the same `year` and `rating` are grouped together in the same result.