==============
Aggregations
==============


Aggregations in Cozo can be thought of as a function that acts on a stream of values
and produces a single value (the aggregate).

There are two kinds of aggregations in Cozo, *ordinary aggregations* and *semi-lattice aggregations*.
They are implemented differently in Cozo, with semi-lattice aggregations generally faster and more powerful
(only the latter can be used recursively).

The power of semi-lattice aggregations derive from the additional properties they satisfy: a `semilattice <https://en.wikipedia.org/wiki/Semilattice>`_:

    idempotency
        the aggregate of a single value ``a`` is ``a`` itself,
    commutativity
        the aggregate of ``a`` then ``b`` is equal to the aggregate of ``b`` then ``a``,
    associativity
        it is immaterial where we put the parentheses in an aggregate application.

------------------------------------
Semi-lattice aggregations
------------------------------------

.. module:: Aggr.SemiLattice
    :noindex:

.. function:: min(x)

    Aggregate the minimum value of all ``x``.

.. function:: max(x)

    Aggregate the maximum value of all ``x``.

.. function:: and(var)

    Aggregate the logical conjunction of the variable passed in.

.. function:: or(var)

    Aggregate the logical disjunction of the variable passed in.

.. function:: union(var)

    Aggregate the unions of ``var``, which must be a list.

.. function:: intersection(var)

    Aggregate the intersections of ``var``, which must be a list.

.. function:: choice(var)

    Non-deterministically chooses one of the values of ``var`` as the aggregate.
    It simply chooses the first value it meets (the order that it meets values is non-deterministic).

.. function:: choice_last(var)

    Non-deterministically chooses one of the values of ``var`` as the aggregate.
    It simply chooses the last value it meets.

.. function:: min_cost([data, cost])

    The argument should be a list of two elements and this aggregation chooses the list of the minimum ``cost``.

.. function:: shortest(var)

    ``var`` must be a list. Returns the shortest list among all values. Ties will be broken non-deterministically.

.. function:: coalesce(var)

    Returns the first non-null value it meets. The order is non-deterministic.

.. function:: bit_and(var)

    ``var`` must be bytes. Returns the bitwise 'and' of the values.

.. function:: bit_or(var)

    ``var`` must be bytes. Returns the bitwise 'or' of the values.

---------------------
Ordinary aggregations
---------------------

.. module:: Aggr.Ord
    :noindex:

.. function:: count(var)

    Count how many values are generated for ``var`` (using bag instead of set semantics).

.. function:: count_unique(var)

    Count how many unique values there are for ``var``.

.. function:: collect(var)

    Collect all values for ``var`` into a list.

.. function:: unique(var)

    Collect ``var`` into a list, keeping each unique value only once.

.. function:: group_count(var)

    Count the occurrence of unique values of ``var``, putting the result into a list of lists,
    e.g. when applied to ``'a'``, ``'b'``, ``'c'``, ``'c'``, ``'a'``, ``'c'``, the results is ``[['a', 2], ['b', 1], ['c', 3]]``.

.. function:: bit_xor(var)

    ``var`` must be bytes. Returns the bitwise 'xor' of the values.

.. function:: latest_by([data, time])

    The argument should be a list of two elements and this aggregation returns the ``data`` of the maximum ``cost``.
    This is very similar to ``min_cost``, the differences being that maximum instead of minimum is used,
    only the data itself is returned, and the aggregation is deliberately not a semi-lattice aggregation. Intended to be used in timestamped audit trails.

.. function:: choice_rand(var)

    Non-deterministically chooses one of the values of ``var`` as the aggregate.
    Each value the aggregation encounters has the same probability of being chosen.

    .. NOTE::
        This version of ``choice`` is not a semi-lattice aggregation
        since it is impossible to satisfy the uniform sampling requirement while maintaining no state,
        which is an implementation restriction unlikely to be lifted.

^^^^^^^^^^^^^^^^^^^^^^^^^
Statistical aggregations
^^^^^^^^^^^^^^^^^^^^^^^^^

.. function:: mean(x)

    The mean value of ``x``.

.. function:: sum(x)

    The sum of ``x``.

.. function:: product(x)

    The product of ``x``.

.. function:: variance(x)

    The sample variance of ``x``.

.. function:: std_dev(x)

    The sample standard deviation of ``x``.