GraphQL(Docs): Documentation for Aggregate Queries (#7104)

* Create aggregate.md

* Update aggregate.md

* Update aggregate.md

* Merge branch 'master' into aaroncarey/aggregate-GQL-890

* Address most of the feedback recieved so far

- repeated paragraphs/bullets refactored into a shorter repeated tip.
- Adjusted example descriptions and example query syntax to fix errors, per reviewer feedback

Not included: combining with the "Count Queries" content, or resolving a comment that I'm not sure how to address yet.

* Combining Count Queries and Aggregate Queries, editing "weight" metadata to have non-duplicate values across files in /query

* Minor edits

* Update aggregate.md

* Add example with filter

* Update wiki/content/graphql/queries/aggregate.md

Co-authored-by: Damián Parrino <bucanero@users.noreply.github.com>

* Update wiki/content/graphql/queries/aggregate.md

Co-authored-by: Damián Parrino <bucanero@users.noreply.github.com>

* Incorporate reviewer feedback

- Some rewording and linking added
- Added information on how queries against null data behave, per #7119  and reviewer feedback

* update example syntax

* Adding a corrected version of the first advanced aggregate query example, previously removed

* Update aggregate.md

wiki/content/graphql/queries/aggregate.md

@@ -0,0 +1,211 @@
++++
+title = "Aggregate Queries"
+weight = 3
+[menu.main]
+    parent = "graphql-queries"
+    name = "Aggregate Queries"
++++
+
+Dgraph automatically generates aggregate queries for GraphQL schemas.
+Aggregate queries fetch aggregate data, including the following:
+
+* *Count queries* that let you count fields
+satisfying certain criteria specified using a filter.
+* *Advanced aggregate queries* that let you calculate the maximum, minimum, sum
+and average of specified fields.
+
+Aggregate queries are compatible with the `@auth` directive and follow the same
+authorization rules as the `query` keyword. You can also use filters with
+aggregate queries, as shown in some of the examples provided below.
+
+### Count queries at root
+
+For every `type` defined in a GraphQL schema, Dgraph generates an aggregate query
+`aggregate<type name>`. This query includes a `count` field, as well as
+[advanced aggregate query fields](#advanced-aggregate-queries-at-root).
+
+#### Examples
+
+Example: Fetch the total number of `posts`.
+
+```graphql
+   query {
+     aggregatePost {
+       count
+     }
+   }
+```
+
+Example: Fetch the number of `posts` whose titles contain `GraphQL`.
+
+```graphql
+   query {
+     aggregatePost(filter: {
+       title: {
+         anyofterms: "GraphQL"
+         }
+       }) {
+       count
+     }
+   }
+```
+
+
+### Count queries for child nodes
+
+Dgraph also defines `<field name>Aggregate` fields for every field which
+is of type `List[Type/Interface]` inside `query<type name>` queries, allowing
+you to do a `count` on fields, or to use the [advanced aggregate queries](#advanced-aggregate-queries-for-child-nodes).
+
+#### Examples
+
+Example: Fetch the number of `posts` for all authors along with their `name`.
+
+```graphql
+   query {
+     queryAuthor {
+       name
+       postsAggregate {
+        count
+       }
+     }
+   }
+```
+
+Example: Fetch the number of `posts` with a `score` greater than `10` for all
+authors, along with their `name`
+
+```graphql
+   query {
+     queryAuthor {
+       name
+       postsAggregate(filter: {
+         score: {
+           gt: 10
+         }
+       }) {
+        count
+      }
+    }
+  }
+```
+
+### Advanced aggregate queries at root
+
+For every `type` defined in the GraphQL schema, Dgraph generates an aggregate
+query `aggregate<type name>` that includes advanced aggregate query
+fields, and also includes a `count` field (see [Count queries at root](#count-queries-at-root)). Dgraph generates one or more advanced aggregate
+query fields (`<field-name>Min`, `<field-name>Max`, `<field-name>Sum` and
+`<field-name>Avg`) for fields in the schema that are typed as `Int`, `Float`,
+`String` and `Datetime`.
+
+{{% notice "note" %}}
+Advanced aggregate query fields are generated according to a field's type.
+Fields typed as `Int` and `Float` get the following query fields:
+`<field name>Max`, `<field name>Min`, `<field name>Sum` and `<field name>Avg`.
+Fields typed as `String` and `Datetime` only get the `<field name>Max`,
+ `<field name>Min` query fields.
+{{% /notice %}}
+
+#### Examples
+
+Example: Fetch the average number of `posts` written by authors:
+
+```graphql
+   query {
+     aggregateAuthor {
+       numPostsAvg
+     }
+   }
+```
+
+Example: Fetch the total number of `posts` by all authors, and the maximum
+number of `posts` by any single `Author`:
+
+```graphql
+   query {
+     aggregateAuthor {
+       numPostsSum
+       numPostsMax
+     }
+   }
+```
+
+Example: Fetch the average number of `posts` for authors with more than 20
+`friends`:
+
+```graphql
+   query {
+     aggregateAuthor (filter: {
+       friends: {
+         gt: 20
+       }
+     }) {
+       numPostsAvg
+     }
+   }
+```
+
+
+### Advanced aggregate queries for child nodes
+
+Dgraph also defines aggregate `<field name>Aggregate` fields for child nodes
+within `query<type name>` queries. This is done for each field that is of type
+`List[Type/Interface]` inside `query<type name>` queries, letting you fetch
+minimums, maximums, averages and sums for those fields.
+
+{{% notice "note" %}}
+Aggregate query fields are generated according to a field's type. Fields typed
+as `Int` and `Float` get the following query fields:`<field name>Max`,
+`<field name>Min`, `<field name>Sum` and `<field name>Avg`. Fields typed as
+`String` and `Datetime` only get the `<field name>Max`, `<field name>Min` query
+fields.
+{{% /notice %}}
+
+#### Examples
+
+Example: Fetch the minimum, maximum and average `score` of the `posts` for each
+`Author`, along with each author's `name`.
+
+```graphql
+   query {
+     queryAuthor {
+       name
+       postsAggregate {
+         scoreMin
+         scoreMax
+         scoreAvg
+       }
+     }
+   }
+```
+
+Example: Fetch the date of the most recent post with a `score` greater than
+`10` for all authors, along with the author's `name`.
+
+```graphql
+   query {
+     queryAuthor {
+       name
+       postsAggregate(filter: {
+         score: {
+           gt: 10
+         }
+       }) {
+         datePublishedMax
+      }
+    }
+  }
+```
+
+### Aggregate queries on null data
+
+Aggregate queries against empty data return `null`. This is true for both the
+`<field name>Aggregate` fields and `aggregate<type name>` queries generated by
+Dgraph.
+
+So, in the examples above, the following is true:
+* If there are no nodes of type `Author`, the `aggregateAuthor` query will
+  return null.
+* If an `Author` has not written any posts, the field `postsAggregate` will be
+  null for that `Author`.

wiki/content/graphql/queries/and-or-not.md

@@ -1,6 +1,6 @@
 +++
 title = "And, Or and Not"
-weight = 4
+weight = 5
 [menu.main]
     parent = "graphql-queries"
     name = "And, Or and Not"
@@ -50,4 +50,4 @@ queryPost(filter: {
     title: { allofterms: "GraphQL"},
     or: { title: { allofterms: "Dgraph" }, tags: { eg: "GraphQL" } }
   } ) { ... }
-```
+```

wiki/content/graphql/queries/cached-results.md

@@ -1,6 +1,6 @@
 +++
 title = "Cached Results"
-weight = 4
+weight = 6
 [menu.main]
     parent = "graphql-queries"
 +++

wiki/content/graphql/queries/cascade.md

@@ -1,6 +1,6 @@
 +++
 title = "Cascade"
-weight = 5
+weight = 8
 [menu.main]
     parent = "graphql-queries"
     name = "Cascade"

wiki/content/graphql/queries/order-page.md

@@ -1,6 +1,6 @@
 +++
 title = "Order and Pagination"
-weight = 4
+weight = 7
 [menu.main]
     parent = "graphql-queries"
     name = "Order and Pagination"
@@ -27,4 +27,4 @@ date order the posts by number of likes.
 
 ```graphql
 queryPost(order: { desc: datePublished, then: { desc: numLikes } }, first: 5) { ... }
-```
+```

wiki/content/graphql/queries/persistent-queries.md

@@ -1,6 +1,6 @@
 +++
 title = "Persistent Queries"
-weight = 3
+weight = 4
 [menu.main]
     parent = "graphql-queries"
 +++
@@ -34,7 +34,7 @@ To create a Persistent Query, both `query` and `sha256` must be provided.
 
 Dgraph will verify the hash and perform a lookup. If the query doesn't exist, Dgraph will store the query, provided that the `sha256` of the query is correct. Finally, Dgraph will process the query and return the results.
 
-Example: 
+Example:
 
 ```sh
 curl -g 'http://localhost:8080/graphql/?query={sample_query}&extensions={"persistedQuery":{"sha256Hash":"b952c19b894e1aa89dc05b7d53e15ab34ee0b3a3f11cdf3486acef4f0fe85c52"}}'
@@ -44,7 +44,7 @@ curl -g 'http://localhost:8080/graphql/?query={sample_query}&extensions={"persis
 
 If only a `sha256` is provided, Dgraph will do a look-up, and process the query if found. Otherwise you'll get a `PersistedQueryNotFound` error.
 
-Example: 
+Example:
 
 ```sh
 curl -g 'http://localhost:8080/graphql/?extensions={"persistedQuery":{"sha256Hash":"b952c19b894e1aa89dc05b7d53e15ab34ee0b3a3f11cdf3486acef4f0fe85c52"}}'

wiki/content/graphql/queries/skip-include.md

@@ -1,6 +1,6 @@
 +++
 title = "Skip and Include"
-weight = 6
+weight = 9
 [menu.main]
     parent = "graphql-queries"
     name = "Skip and Include"
@@ -60,4 +60,4 @@ GraphQL variables
 {
     "includeAuthor": false
 }
-```
+```