From 201bb62db1e9fff5433ee243fe39020868bf6290 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?= <112686610+JPryce-Aklundh@users.noreply.github.com> Date: Wed, 27 Sep 2023 12:00:22 +0200 Subject: [PATCH 1/5] add KB note and remove duplicate grouping key content --- modules/ROOT/pages/functions/aggregating.adoc | 36 +++---------------- 1 file changed, 5 insertions(+), 31 deletions(-) diff --git a/modules/ROOT/pages/functions/aggregating.adoc b/modules/ROOT/pages/functions/aggregating.adoc index a6352ad13..34d542aa8 100644 --- a/modules/ROOT/pages/functions/aggregating.adoc +++ b/modules/ROOT/pages/functions/aggregating.adoc @@ -3,39 +3,13 @@ [[query-functions-aggregating]] = Aggregating functions -== Introduction - Aggregating functions take a set of values and calculate an aggregated value over them. -Aggregation can be computed over all the matching paths, or it can be further divided by introducing grouping keys. -Grouping keys are non-aggregating expressions that are used to group the values going into the aggregating functions. - -For example, given the following query containing two return expressions, `n` and `+count(*)+`: - -[source, cypher, role=test-skip] ----- -RETURN n, count(*) ----- - -The first, `n` is not an aggregating function, so it will be the grouping key. -The latter, `count(*)` is an aggregating function. -The matching paths will be divided into different buckets, depending on the grouping key. -The aggregating function will then be run on these buckets, calculating an aggregate value per bucket. - -The input expression of an aggregating function can contain any expression, including expressions that are not grouping keys. -However, not all expressions can be composed with aggregating functions. -The example below will throw an error since `n.x`, which is not a grouping key, is combined with the aggregating function `count(*)`. -For more information, see xref:functions/aggregating.adoc#grouping-keys[Grouping keys]. +Aggregation can be computed over all the matching paths, or it can be further divided by introducing xref:functions/aggregating.adoc#[grouping keys]. -[source, cypher, role=test-skip] ----- -RETURN n.x + count(*) ----- - -To sort the result set using aggregating functions, the aggregation must be included in the `ORDER BY` sub-clause following the `RETURN` clause. - -The `DISTINCT` operator works in conjunction with aggregation. -It is used to make all values unique before running them through an aggregating function. -More information about `DISTINCT` can be found in xref::syntax/operators.adoc#query-operators-aggregation[Syntax -> Aggregation operators]. +[TIP] +==== +To learn more about how Cypher handles aggregations performed on zero rows, refer to link:https://neo4j.com/developer/kb/understanding-aggregations-on-zero-rows//[Neo4j Knowledge Base -> Understanding aggregations on zero rows]. +==== == Example graph From c3efe08f4d7a87644519907bf6de7ffb0e02d8d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?= <112686610+JPryce-Aklundh@users.noreply.github.com> Date: Wed, 27 Sep 2023 13:42:06 +0200 Subject: [PATCH 2/5] restructure grouping keys --- modules/ROOT/pages/functions/aggregating.adoc | 46 ++++++++++++++----- 1 file changed, 35 insertions(+), 11 deletions(-) diff --git a/modules/ROOT/pages/functions/aggregating.adoc b/modules/ROOT/pages/functions/aggregating.adoc index 34d542aa8..90fa1518c 100644 --- a/modules/ROOT/pages/functions/aggregating.adoc +++ b/modules/ROOT/pages/functions/aggregating.adoc @@ -1035,7 +1035,7 @@ The sum of the two supplied Durations is returned: [[grouping-keys]] -== Grouping keys +== Aggregating expressions and grouping keys Aggregating expressions are expressions which contain one or more aggregating functions. A simple aggregating expression consists of a single aggregating function. @@ -1044,20 +1044,32 @@ Aggregating expressions are also allowed to be more complex, where the result of For instance, `0.1 * (sum(x.a) / count(x.b))` is an aggregating expression that contains two aggregating functions, `sum( )` with `x.a` as its argument and `count( )` with `x.b` as its argument. Both are input arguments to the division expression. +Grouping keys are non-aggregating expressions that are used to group the values going into the aggregating functions. +For example, given the following query containing two return expressions, `n` and `+count(*)+`: -For aggregating expressions to be correctly computable for the buckets formed by the grouping key(s), they have to fulfill some requirements. -Specifically, each sub-expression in an aggregating expression has to be either: +[source, cypher, role=test-skip] +---- +RETURN n, count(*) +---- -* an aggregating function, e.g. `sum(x.a)`, -* a constant, e.g. `0.1`, -* a parameter, e.g. `$param`, -* a grouping key, e.g. the `a` in `RETURN a, count(*)` -* a local variable, e.g. the `x` in `count(*) + size([ x IN range(1, 10) | x ])`, or -* a sub-expression, all operands of which have to be allowed in an aggregating expression. +The first, `n` is not an aggregating function, so it will be the grouping key. +The latter, `count(*)` is an aggregating function. +The matching paths will be divided into different buckets, depending on the grouping key. +The aggregating function will then be run on these buckets, calculating an aggregate value per bucket. + +The input expression of an aggregating function can contain any expression, including expressions that are not grouping keys. +However, not all expressions can be composed with aggregating functions. +The example below will throw an error since `n.x`, which is not a grouping key, is combined with the aggregating function `count(*)`. + +[source, cypher, role=test-skip] +---- +RETURN n.x + count(*) +---- +To sort the result set using aggregating functions, the aggregation must be included in the `ORDER BY` sub-clause following the `RETURN` clause. [[grouping-key-examples]] -=== Examples of aggregating expressions +=== Examples .Simple aggregation without any grouping keys ====== @@ -1196,4 +1208,16 @@ RETURN groupingKey, groupingKey - max(f.age) | +116+ | +45+ 2+d|Rows: 1 |=== -====== \ No newline at end of file +====== + +=== Rules for aggregating expressions + +For aggregating expressions to be correctly computable for the buckets formed by the grouping key(s), they have to fulfill some requirements. +Specifically, each sub-expression in an aggregating expression has to be either: + +* an aggregating function, e.g. `sum(x.a)`, +* a constant, e.g. `0.1`, +* a parameter, e.g. `$param`, +* a grouping key, e.g. the `a` in `RETURN a, count(*)` +* a local variable, e.g. the `x` in `count(*) + size([ x IN range(1, 10) | x ])`, or +* a sub-expression, all operands of which have to be allowed in an aggregating expression. From baedb9b08c4ec847cc7b3691398f0f7e443442ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?= <112686610+JPryce-Aklundh@users.noreply.github.com> Date: Wed, 27 Sep 2023 13:46:57 +0200 Subject: [PATCH 3/5] fix list --- modules/ROOT/pages/functions/aggregating.adoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/functions/aggregating.adoc b/modules/ROOT/pages/functions/aggregating.adoc index 90fa1518c..bd637e1f9 100644 --- a/modules/ROOT/pages/functions/aggregating.adoc +++ b/modules/ROOT/pages/functions/aggregating.adoc @@ -1215,9 +1215,9 @@ RETURN groupingKey, groupingKey - max(f.age) For aggregating expressions to be correctly computable for the buckets formed by the grouping key(s), they have to fulfill some requirements. Specifically, each sub-expression in an aggregating expression has to be either: -* an aggregating function, e.g. `sum(x.a)`, -* a constant, e.g. `0.1`, -* a parameter, e.g. `$param`, -* a grouping key, e.g. the `a` in `RETURN a, count(*)` -* a local variable, e.g. the `x` in `count(*) + size([ x IN range(1, 10) | x ])`, or +* an aggregating function, e.g. `sum(x.a)`. +* a constant, e.g. `0.1`. +* a parameter, e.g. `$param`. +* a grouping key, e.g. the `a` in `RETURN a, count(*)`. +* a local variable, e.g. the `x` in `count(*) + size([ x IN range(1, 10) | x ])`. * a sub-expression, all operands of which have to be allowed in an aggregating expression. From 8250e0dc073ee11d89b4572c6ba048175791a76f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?= <112686610+JPryce-Aklundh@users.noreply.github.com> Date: Wed, 27 Sep 2023 14:08:54 +0200 Subject: [PATCH 4/5] more fixes --- modules/ROOT/pages/functions/aggregating.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/functions/aggregating.adoc b/modules/ROOT/pages/functions/aggregating.adoc index bd637e1f9..fb2945524 100644 --- a/modules/ROOT/pages/functions/aggregating.adoc +++ b/modules/ROOT/pages/functions/aggregating.adoc @@ -3,7 +3,7 @@ [[query-functions-aggregating]] = Aggregating functions -Aggregating functions take a set of values and calculate an aggregated value over them. +An aggregating function performs a calculation over a set of values, returning a single value. Aggregation can be computed over all the matching paths, or it can be further divided by introducing xref:functions/aggregating.adoc#[grouping keys]. [TIP] @@ -1037,14 +1037,14 @@ The sum of the two supplied Durations is returned: [[grouping-keys]] == Aggregating expressions and grouping keys -Aggregating expressions are expressions which contain one or more aggregating functions. +*Aggregating expressions* are expressions which contain one or more aggregating functions. A simple aggregating expression consists of a single aggregating function. For instance, `sum(x.a)` is an aggregating expression that only consists of the aggregating function `sum( )` with `x.a` as its argument. Aggregating expressions are also allowed to be more complex, where the result of one or more aggregating functions are input arguments to other expressions. For instance, `0.1 * (sum(x.a) / count(x.b))` is an aggregating expression that contains two aggregating functions, `sum( )` with `x.a` as its argument and `count( )` with `x.b` as its argument. Both are input arguments to the division expression. -Grouping keys are non-aggregating expressions that are used to group the values going into the aggregating functions. +*Grouping keys* are non-aggregating expressions that are used to group the values going into the aggregating functions. For example, given the following query containing two return expressions, `n` and `+count(*)+`: [source, cypher, role=test-skip] From ed7ad11e983f11efbbe7d926157ca304a0a1ce4f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?= <112686610+JPryce-Aklundh@users.noreply.github.com> Date: Wed, 27 Sep 2023 14:29:43 +0200 Subject: [PATCH 5/5] fix xref --- modules/ROOT/pages/functions/aggregating.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/functions/aggregating.adoc b/modules/ROOT/pages/functions/aggregating.adoc index fb2945524..9925a3ffd 100644 --- a/modules/ROOT/pages/functions/aggregating.adoc +++ b/modules/ROOT/pages/functions/aggregating.adoc @@ -4,7 +4,7 @@ = Aggregating functions An aggregating function performs a calculation over a set of values, returning a single value. -Aggregation can be computed over all the matching paths, or it can be further divided by introducing xref:functions/aggregating.adoc#[grouping keys]. +Aggregation can be computed over all the matching paths, or it can be further divided by introducing xref:functions/aggregating.adoc#grouping-keys[grouping keys]. [TIP] ====