Merge branch '7.x' into restructuring-the-reference

Author: rsill-neo4j

modules/ROOT/pages/directives/index.adoc

@@ -94,6 +94,9 @@ Particularly useful for types that are not correctly pluralized or are non-Engli
 | xref:/directives/schema-configuration/field-configuration.adoc#_settable[`@settable`]
 | Sets the availability of fields on the `create` and `update` inputs.
 
+| xref:/directives/schema-configuration/field-configuration.adoc#_sortable[`@sortable`]
+| Sets the availability of sorting inputs for that field.
+
 | xref:/directives/schema-configuration/field-configuration.adoc#_filterable[`@filterable`]
 | Defines the filters generated for a field.
 

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

@@ -398,6 +398,71 @@ input ActorUpdateInput {
 
 This means `actedIn` can be updated on an update, but it is no longer available on `create` operations.
 
+
+== `@sortable`
+
+This directive sets the availability of the input fields for sorting.
+It has a single argument:
+
+* **byValue**: Defaults to true. If disabled, this field is not available for sorting.
+
+=== Definition
+
+[source, graphql, indent=0]
+----
+"""Instructs @neo4j/graphql to generate sorting inputs for this field."""
+directive @sortable(byValue: Boolean! = true) on FIELD_DEFINITION
+----
+
+=== Usage
+
+With this definition:
+
+[source, graphql, indent=0]
+----
+type Movie @node {
+    title: String!
+    description: String! @sortable(byValue: false)
+}
+----
+
+The following input type is generated for Movies:
+
+[source, graphql, indent=0]
+----
+"""
+Fields to sort Movies by. The order in which sorts are applied is not guaranteed when specifying many fields in one MovieSort object.
+"""
+input MovieSort {
+  title: SortDirection
+}
+----
+
+Movies can be sorted by the title, but not by description:
+
+This is valid:
+[source, graphql, indent=0]
+----
+query {
+  movies(sort: {title: DESC}) {
+    title
+  }
+}
+----
+
+This is not valid:
+[source, graphql, indent=0]
+----
+query {
+  movies(sort: {description: DESC}) {
+    title
+  }
+}
+----
+
+
+If no fields are sortable, the type `MovieSort` is not generated, and the `sort` input isn't available.
+
 == `@filterable`
 
 This directive defines the filters generated for the field to which this directive is applied.

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

@@ -20,7 +20,7 @@ type Actor @node {
     name: String 
     movies: [Movie!]! @relationship(type: "ACTED_IN", direction: OUT) 
 }
-extend schema @query(read: true, aggregate: false)
+extend schema @query(read: true, connection: true, aggregate: false)
 ----
 
 This configuration disables all top-level aggregation operations for the `Movie` and `Actor` types, while still allowing read operations.
@@ -59,7 +59,7 @@ type Movie @node {
     actors: [Actor!]! @relationship(type: "ACTED_IN", direction: IN) 
 } 
 
-type Actor @node @query(read: false, aggregate: true) { 
+type Actor @node @query(read: false, connection: false, aggregate: true) { 
     name: String 
     movies: [Movie!]! @relationship(type: "ACTED_IN", direction: OUT) 
 }

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

@@ -51,9 +51,11 @@ This directive is used to limit the availability of query operations in the libr
 
 [source, graphql, indent=0]
 ----
-directive @query(read: Boolean! = true, aggregate: Boolean! = false) on OBJECT | SCHEMA | INTERFACE | UNION
+directive @query(read: Boolean! = true, connection: Boolean, aggregate: Boolean! = false) on OBJECT | SCHEMA | INTERFACE | UNION
 ----
 
+Where the value of the `connection` argument defaults to the value of the `read` argument.
+
 === Usage
 
 .Disable query _movies_ and _moviesConnection_ edges field
@@ -68,7 +70,25 @@ type Movie @node @query(read: false, aggregate: true) {
 .Disable _moviesConnection_ aggregate field
 [source, graphql, indent=0]
 ----
-type Movie @node @query(read: true, aggregate: false)  { 
+type Movie @node @query(read: true, aggregate: false)  { # aggregate can be omitted as it defaults to false
+    title: String 
+    length: Int
+}
+----
+
+.Disable _moviesConnection_ completely
+[source, graphql, indent=0]
+----
+type Movie @node @query(read: true, connection: false, aggregate: false)  { # aggregate can be omitted as it defaults to false
+    title: String 
+    length: Int
+}
+----
+
+.Disable all reads
+[source, graphql, indent=0]
+----
+type Movie @node @query(read: false, aggregate: false)  { # aggregate can be omitted as it defaults to false
     title: String 
     length: Int
 }

modules/ROOT/pages/queries-aggregations/aggregations.adoc

@@ -49,8 +49,10 @@ Aggregations on a type are provided in the field `aggregate` inside Connection:
 query {
     usersConnection {
         aggregate {
-            name {
-                longest
+            node {
+                name {
+                    longest
+                }
             }
         }
     }
@@ -94,8 +96,10 @@ a|
 query {
     postsConnection {
         aggregate {
-            createdAt {
-                min
+            node {
+                createdAt {
+                    min
+                }
             }
         }
     }
@@ -220,3 +224,40 @@ query {
 }
 ----
 
+
+== Aggregations and pagination
+
+Since aggregations are done within the `Connection` type, the optional arguments `first` and `after` are available for pagination.
+However, pagination **does not** apply to aggregations.
+
+For example:
+
+[source, graphql, indent=0]
+----
+query {
+    usersConnection(first: 10) {
+        aggregate {
+            count {
+                nodes
+            }
+        }
+    }
+}
+----
+
+The result returns the count of all the nodes:
+
+[source, json, indent=0]
+----
+{
+    "usersConnection": {
+        "aggregate": {
+            "count": {
+                "nodes": 38
+            }
+        }
+    }
+}
+----
+
+