.. _aggregation:

Aggregation
===========

``qalx`` provides an interface to the MongoDB aggregation pipeline.  This powerful
feature allows you to perform many complex operations on your data using the `aggregate` argument.

.. code-block:: python
    :caption: Grouping some items.

    >>> from pyqalx import QalxSession
    >>> qalx = QalxSession()

    >>> # First, let's add some items to perform the aggregation on
    >>> items = [{"data": {"key": "aggregation_example",
    >>>                    "value": x % 2}} for x in range(0, 15)]
    >>> qalx.item.add_many(items=items)

    >>> # This simple aggregation groups data on the `value` key after filtering
    >>> # the data on a specific key
    >>> qalx.item.aggregate(aggregate=[
    >>>                         {"$match": {"data.key": "aggregation_example"}},
    >>>                         {"$group": {"_id": "$data.value", "count": {"$sum": 1}}}])
    {'aggregate': [{'$match': {'data.key': 'aggregation_example'}},
                   {'$group': {'_id': '$data.value', 'count': {'$sum': 1}}}]},
     'data': [{'_id': 1, 'count': 7}, {'_id': 0, 'count': 8}]}


Consult the MongoDB `documentation <https://docs.mongodb.com/manual/core/aggregation-pipeline/>`_ for more
information about what is possible using aggregation