diff --git a/docs/reference/api/query.md b/docs/reference/api/query.md
index 6a60658c7f..2d2254d0d1 100644
--- a/docs/reference/api/query.md
+++ b/docs/reference/api/query.md
@@ -20,9 +20,12 @@ pageClass: page-reference
- [Sort](#sort)
- [Limit](#limit)
- [Offset](#offset) / [Page](#page)
-- [Group](#group)
-- [Aggregate](#aggregate) (sum/avg/min/max/count)
+- [Aggregate and Grouping](#aggregate-and-grouping)
- [Deep](#deep)
+- [Aliases](#aliases)
+- [Metadata](#metadata)
+ - [Total Count](#total-count)
+ - [Filter Count](#filter-count)
- [Export](#export)
@@ -443,12 +446,58 @@ query {
---
-## Group
+## Aggregate and Grouping
-Group allows you to group the output items based on (a) shared value(s).
+The aggegate functions all the transformation of fields. Supported functions are avg, avg_distinct, count,
+count_distinct, min, max, sum, sum_distinct.
+
+A group by option can be added to the arguments which groups the return by a specified field.
+
+Aggregated functions can be accessed with the syntax `collection_aggregated`.
+
+
+
+
+
+
+
+### Examples
+
+Return of an aggregated sum of the revenue field.
+
+```json
+{
+ "articles_aggregated": {
+ "sum": {
+ "revenue": 598
+ }
+ }
+}
+```
+
+Return of an aggregate sum of the revenue field with a group by on `author`
+
+```json
+{
+ "articles_aggregated": [
+ {
+ "group": "John",
+ "sum": {
+ "revenue": 475
+ }
+ },
+ {
+ "group": "Smith",
+ "sum": {
+ "revenue": 123
+ }
+ }
+ ]
+}
+```
@@ -456,47 +505,21 @@ Group allows you to group the output items based on (a) shared value(s).
### REST API
```
-?group=year
-?group=year,status
+?aggregate[sum]=revenue&groupBy=author
```
### GraphQL
-TBD
-
-
-
-
-
-Aggregate allows you to retrieve the output of several functions in your items. In the syntax listed to the right,
-`
` is one of `avg`, `sum`, `min`, `max`, or `count`, `` is the column you'd like to run the function on,
-and `` is how the result should be returned.
-
-
-
-
-### REST API
-
+```graphql
+query {
+ articles_aggregated(groupBy: "author") {
+ group
+ sum {
+ revenue
+ }
+ }
+}
```
-?aggregate[
][]=
-```
-
-##### Example
-
-```
-?aggregate[avg][price]=average_sale
-&aggregate[sum][price]=revenue
-```
-
-### GraphQL
-
-TBD
+
+
+Aliases allow you to make multiple queries to the same collection under different names. For example an alias of
+`translations` could be `all_translations` and they could both be used in the same query.
+
+### Examples
+
+Return both a filtered translations field and an unfiltered `translations` as `all_translations`
+
+```json
+{
+ "articles: [
+ {
+ "translations": [],
+ "all_translations": [
+ {
+ "id": "2"
+ }
+ ]
+ },
+ {
+ "translations": [
+ {
+ "id": "4"
+ }
+ ],
+ "all_translations": [
+ {
+ "id": "4"
+ }
+ ]
+ }
+ ]
+}
+```
+
+
+
+
+### REST API
+
+```
+?translations[filter][id][_eq]=4&alias[all_translations]=translations
+```
+
+### GraphQL
+
+_Natively supported in GraphQL:_
+
+```graphql
+query {
+ articles {
+ translations(filter: { id: { _eq: 4 } }) {
+ id
+ }
+ all_translations: translations {
+ id
+ }
+ }
+}
+```
+
+
+
+
+
+Metadata allows you to retrieve some additional information about the items in the collection you're fetching. `*` can
+be used as a wildcard to retrieve all metadata.
+
+
+
+
+
+### Total Count
+
+Returns the total item count of the collection you're querying.
+
+### Filter Count
+
+Returns the item count of the collection you're querying, taking the current filter/search parameters into account.
+
+
+
+
+### REST API
+
+```
+?meta=total_count
+
+?meta=filter_count
+
+?meta=*
+```
+
+### GraphQL
+
+n/a
+
+
+