basic aggregate functions (piccolo-orm#146)

Author: sinisaos

docs/src/piccolo/query_types/count.rst

@@ -12,8 +12,7 @@ typical ORM.
 
     ./select
     ./objects
-    ./alter
-    ./count
+    ./alter  
     ./create_table
     ./delete
     ./exists

docs/src/piccolo/query_types/index.rst

@@ -79,6 +79,99 @@ convenient.
     # For joins:
     Band.select('manager.name').run_sync()
 
+
+Aggregate functions
+-------------------
+
+Count
+~~~~~
+
+Returns the number of rows which match the query.
+
+.. code-block:: python
+
+    >>> Band.count().where(Band.name == 'Pythonistas').run_sync()
+    1
+
+Avg
+~~~
+
+Returns average of numeric rows which match the query.
+
+.. code-block:: python
+
+    >>> from piccolo.query import Avg
+    >>> response = Band.select(Avg(Band.popularity)).first().run_sync()
+    >>> response["avg"]
+    750.0
+
+Sum
+~~~
+
+Returns sum of numeric rows which match the query.
+
+.. code-block:: python
+
+    >>> from piccolo.query import Sum
+    >>> response = Band.select(Sum(Band.popularity)).first().run_sync()
+    >>> response["sum"]
+    1500
+
+Max
+~~~
+
+Returns maximum of rows which match the query.
+
+.. code-block:: python
+
+    >>> from piccolo.query import Max
+    >>> response = Band.select(Max(Band.popularity)).first().run_sync()
+    >>> response["max"]
+    1000
+
+Min
+~~~
+
+Returns minimum of rows which match the query.
+
+.. code-block:: python
+
+    >>> from piccolo.query import Min
+    >>> response = Band.select(Min(Band.popularity)).first().run_sync()
+    >>> response["min"]
+    500
+
+Additional features
+~~~~~~~~~~~~~~~~~~~
+
+You also can chain multiple different aggregate functions in one query,
+
+.. code-block:: python
+
+    >>> from piccolo.query import Avg, Sum
+    >>> response = Band.select(Avg(Band.popularity), Sum(Band.popularity)).first().run_sync()
+    >>> response
+    {"avg": 750.0, "sum": 1500}
+
+use aliases for aggregate functions like this
+
+.. code-block:: python
+
+    >>> from piccolo.query import Avg
+    >>> response = Band.select(Avg(Band.popularity, alias="popularity_avg")).first().run_sync()
+    >>> response["popularity_avg"]
+    750.0
+
+or use ``as_alias`` method for aggregate functions like this.
+
+.. code-block:: python
+
+    >>> from piccolo.query import Avg
+    >>> response = Band.select(Avg(Band.popularity).as_alias("popularity_avg")).first().run_sync()
+    >>> response["popularity_avg"]
+    750.0
+
+
 Query clauses
 -------------
 

docs/src/piccolo/query_types/select.rst

@@ -1,16 +1,20 @@
 from .base import Query
 from .methods import (
     Alter,
+    Avg,
     Count,
     Create,
     CreateIndex,
     Delete,
     DropIndex,
     Exists,
     Insert,
+    Max,
+    Min,
     Objects,
     Raw,
     Select,
+    Sum,
     TableExists,
     Update,
 )

piccolo/query/__init__.py

@@ -8,6 +8,6 @@
 from .insert import Insert
 from .objects import Objects
 from .raw import Raw
-from .select import Select
+from .select import Avg, Max, Min, Select, Sum
 from .table_exists import TableExists
 from .update import Update

piccolo/query/methods/__init__.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import decimal
 import typing as t
 from collections import OrderedDict
 
@@ -24,6 +25,33 @@
     from piccolo.table import Table  # noqa
 
 
+class Avg(Selectable):
+    """
+    AVG() SQL function. Column type must be numeric to run the query.
+
+    await Band.select(Avg(Band.popularity)).run() or with aliases
+    await Band.select(Avg(Band.popularity, alias="popularity_avg")).run()
+    await Band.select(Avg(Band.popularity).as_alias("popularity_avg")).run()
+    """
+
+    def __init__(self, column: Column, alias: str = "avg"):
+        self.column = column
+        self.alias = alias
+
+    def as_alias(self, alias: str) -> Avg:
+        self.alias = alias
+        return self
+
+    def get_select_string(self, engine_type: str, just_alias=False) -> str:
+        if self.column.value_type in (int, decimal.Decimal, float):
+            column_name = self.column._meta.get_full_name(
+                just_alias=just_alias
+            )
+        else:
+            raise ValueError("Column type must be numeric to run the query.")
+        return f"AVG({column_name}) AS {self.alias}"
+
+
 class Count(Selectable):
     """
     Used in conjunction with the ``group_by`` clause in ``Select`` queries.
@@ -46,6 +74,77 @@ def get_select_string(self, engine_type: str, just_alias=False) -> str:
         return f"COUNT({column_name}) AS count"
 
 
+class Max(Selectable):
+    """
+    MAX() SQL function.
+
+    await Band.select(Max(Band.popularity)).run() or with aliases
+    await Band.select(Max(Band.popularity, alias="popularity_max")).run()
+    await Band.select(Max(Band.popularity).as_alias("popularity_max")).run()
+    """
+
+    def __init__(self, column: Column, alias: str = "max"):
+        self.column = column
+        self.alias = alias
+
+    def as_alias(self, alias: str) -> Max:
+        self.alias = alias
+        return self
+
+    def get_select_string(self, engine_type: str, just_alias=False) -> str:
+        column_name = self.column._meta.get_full_name(just_alias=just_alias)
+        return f"MAX({column_name}) AS {self.alias}"
+
+
+class Min(Selectable):
+    """
+    MIN() SQL function.
+
+    await Band.select(Min(Band.popularity)).run()
+    await Band.select(Min(Band.popularity, alias="popularity_min")).run()
+    await Band.select(Min(Band.popularity).as_alias("popularity_min")).run()
+    """
+
+    def __init__(self, column: Column, alias: str = "min"):
+        self.column = column
+        self.alias = alias
+
+    def as_alias(self, alias: str) -> Min:
+        self.alias = alias
+        return self
+
+    def get_select_string(self, engine_type: str, just_alias=False) -> str:
+        column_name = self.column._meta.get_full_name(just_alias=just_alias)
+        return f"MIN({column_name}) AS {self.alias}"
+
+
+class Sum(Selectable):
+    """
+    SUM() SQL function. Column type must be numeric to run the query.
+
+    await Band.select(Sum(Band.popularity)).run()
+    await Band.select(Sum(Band.popularity, alias="popularity_sum")).run()
+    await Band.select(Sum(Band.popularity).as_alias("popularity_sum")).run()
+    """
+
+    def __init__(self, column: Column, alias: str = "sum"):
+        self.column = column
+        self.alias = alias
+
+    def as_alias(self, alias: str) -> Sum:
+        self.alias = alias
+        return self
+
+    def get_select_string(self, engine_type: str, just_alias=False) -> str:
+        if self.column.value_type in (int, decimal.Decimal, float):
+            column_name = self.column._meta.get_full_name(
+                just_alias=just_alias
+            )
+        else:
+            raise ValueError("Column type must be numeric to run the query.")
+        return f"SUM({column_name}) AS {self.alias}"
+
+
 class Select(Query):
 
     __slots__ = (