Merge pull request github#3143 from ginsbach/the

Uniqueness aggregate in handbook and reference

Author: alexet

docs/language/ql-handbook/expressions.rst

@@ -296,6 +296,22 @@ The following aggregates are available in QL:
   evaluates to the empty set (instead of defaulting to ``0`` or the empty string).
   This is useful if you're only interested in results where the aggregation body is non-trivial.
 
+.. index:: unique
+
+- ``unique``: This aggregate depends on the values of ``<expression>`` over all possible assignments to
+  the aggregation variables. If there is a unique value of ``<expression>`` over the aggregation variables,
+  then the aggregate evaluates to that value.
+  Otherwise, the aggregate has no value.
+
+  For example, the following query returns the positive integers ``1``, ``2``, ``3``, ``4``, ``5``.
+  For negative integers ``x``, the expressions ``x`` and ``x.abs()`` have different values, so the
+  value for ``y`` in the aggregate expression is not uniquely determined. ::
+
+      from int x
+      where x in [-5 .. 5] and x != 0
+      select unique(int y | y = x or y = x.abs() | y)
+
+  The ``unique`` aggregate is supported from release 2.1.0 of the CodeQL CLI, and release 1.24 of LGTM Enterprise.
 
 Evaluation of aggregates
 ========================

docs/language/ql-spec/language.rst

@@ -1058,6 +1058,7 @@ An aggregation can be written in one of two forms:
 
    aggregation ::= aggid ("[" expr "]")? "(" (var_decls)? ("|" (formula)? ("|" as_exprs ("order" "by" aggorderbys)?)?)? ")"
                |   aggid ("[" expr "]")? "(" as_exprs ("order" "by" aggorderbys)? ")"
+               |   "unique" "(" var_decls "|" (formula)? ("|" as_exprs)? ")"
 
    aggid ::= "avg" | "concat" | "count" | "max" | "min" | "rank" | "strictconcat" | "strictcount" | "strictsum" | "sum"
 
@@ -1098,7 +1099,7 @@ The typing environment for ordering directives is obtained by taking the typing
 
 The number and types of the aggregation expressions are restricted as follows:
 
--  A ``max``, ``min`` or ``rank`` aggregation must have a single expression.
+-  A ``max``, ``min``, ``rank`` or ``unique`` aggregation must have a single expression.
 -  The type of the expression in a ``max``, ``min`` or ``rank`` aggregation without an ordering directive expression must be an orderable type.
 -  A ``count`` or ``strictcount`` aggregation must not have an expression.
 -  A ``sum``, ``strictsum`` or ``avg`` aggregation must have a single aggregation expression, which must have a type which is a subtype of ``float``.
@@ -1140,6 +1141,8 @@ The values of the aggregation expression are given by applying the aggregation f
 
 -  If the aggregation id is ``strictconcat``, then the result is the same as for ``concat`` except in the case where there are no aggregation tuples in which case the aggregation has no value.
 
+ -  If the aggregation id is ``unique``, then the result is the value of the aggregation variable if there is precisely one such value. Otherwise, the aggregation has no value.
+
 Any
 ~~~
 
@@ -1976,7 +1979,8 @@ The complete grammar for QL is as follows:
 
    aggregation ::= aggid ("[" expr "]")? "(" (var_decls)? ("|" (formula)? ("|" as_exprs ("order" "by" aggorderbys)?)?)? ")"
                |   aggid ("[" expr "]")? "(" as_exprs ("order" "by" aggorderbys)? ")"
-
+               |   "unique" "(" var_decls "|" (formula)? ("|" as_exprs)? ")"
+ 
    aggid ::= "avg" | "concat" | "count" | "max" | "min" | "rank" | "strictconcat" | "strictcount" | "strictsum" | "sum"
 
    aggorderbys ::= aggorderby ("," aggorderby)*