980 having clause (#1347)

* add `having` clause

* add a test

* add docs

* enable the test for sqlite

Author: dantownsend

docs/src/piccolo/query_clauses/having.rst

@@ -0,0 +1,40 @@
+.. _having:
+
+having
+======
+
+You can use the ``having`` clause with the following queries:
+
+* :ref:`Select`
+
+It is used in combination with the :ref:`group_by` clause, to filter the
+grouped rows.
+
+The syntax is identical to the :ref:`where` clause.
+
+-------------------------------------------------------------------------------
+
+Example
+-------
+
+In the following example, we get the number of albums per band (filtering out
+any bands with less than 2 albums).
+
+.. hint:: You can run this query in the :ref:`playground`.
+
+.. code-block:: python
+
+    >>> from piccolo.query.functions.aggregate import Count
+
+    >>> await Album.select(
+    ...     Album.band.name.as_alias('band_name'),
+    ...     Count()
+    ... ).group_by(
+    ...     Album.band
+    ... ).having(
+    ...     Count() >= 1
+    ... )
+
+    [
+        {"band_name": "Pythonistas", "count": 2},
+    ]

docs/src/piccolo/query_clauses/index.rst

@@ -25,6 +25,7 @@ by modifying the return values.
     ./distinct
     ./freeze
     ./group_by
+    ./having
     ./lock_rows
     ./offset
     ./on_conflict

piccolo/apps/playground/commands/run.py

@@ -299,6 +299,15 @@ def populate():
         Album(
             {
                 Album.name: "Awesome album 2",
+                Album.recorded_at: recording_studio_1,
+                Album.band: pythonistas,
+                Album.release_date: datetime.date(year=2025, month=1, day=1),
+                Album.awards: ["Grammy Award 2025"],
+            }
+        ),
+        Album(
+            {
+                Album.name: "Awesome album 3",
                 Album.recorded_at: recording_studio_2,
                 Album.band: rustaceans,
                 Album.release_date: datetime.date(year=2022, month=2, day=2),

piccolo/query/methods/select.py

@@ -161,6 +161,7 @@ class Select(Query[TableInstance, list[dict[str, Any]]]):
         "output_delegate",
         "callback_delegate",
         "where_delegate",
+        "having_delegate",
         "lock_rows_delegate",
     )
 
@@ -186,6 +187,7 @@ def __init__(
         self.output_delegate = OutputDelegate()
         self.callback_delegate = CallbackDelegate()
         self.where_delegate = WhereDelegate()
+        self.having_delegate = WhereDelegate()
         self.lock_rows_delegate = LockRowsDelegate()
 
         self.columns(*columns_list)
@@ -477,6 +479,10 @@ def where(self: Self, *where: Union[Combinable, QueryString]) -> Self:
         self.where_delegate.where(*where)
         return self
 
+    def having(self: Self, *where: Union[Combinable, QueryString]) -> Self:
+        self.having_delegate.where(*where)
+        return self
+
     async def batch(
         self,
         batch_size: Optional[int] = None,
@@ -569,13 +575,18 @@ def default_querystrings(self) -> Sequence[QueryString]:
 
         select_joins = self._get_joins(self.columns_delegate.selected_columns)
         where_joins = self._get_joins(self.where_delegate.get_where_columns())
+        having_joins = self._get_joins(
+            self.having_delegate.get_where_columns()
+        )
         order_by_joins = self._get_joins(
             self.order_by_delegate.get_order_by_columns()
         )
 
         # Combine all joins, and remove duplicates
         joins: list[str] = list(
-            OrderedDict.fromkeys(select_joins + where_joins + order_by_joins)
+            OrderedDict.fromkeys(
+                select_joins + where_joins + having_joins + order_by_joins
+            )
         )
 
         #######################################################################
@@ -627,6 +638,10 @@ def default_querystrings(self) -> Sequence[QueryString]:
             query += "{}"
             args.append(self.group_by_delegate._group_by.querystring)
 
+        if self.having_delegate._where:
+            query += " HAVING {}"
+            args.append(self.having_delegate._where.querystring)
+
         if self.order_by_delegate._order_by.order_by_items:
             query += "{}"
             args.append(self.order_by_delegate._order_by.querystring)

tests/table/test_select.py

@@ -11,6 +11,7 @@
 from piccolo.query.methods.select import SelectRaw
 from piccolo.query.mixins import DistinctOnError
 from piccolo.table import Table, create_db_tables_sync, drop_db_tables_sync
+from piccolo.testing.test_case import AsyncTableTest
 from tests.base import (
     DBTestCase,
     engine_is,
@@ -1507,3 +1508,36 @@ def test_distinct_on_order_by_error(self):
             Album.select().distinct(on=[Album.band]).order_by(
                 Album.release_date
             ).run_sync()
+
+
+class TestHaving(AsyncTableTest):
+    tables = [Album]
+
+    async def test_having(self):
+        await Album.insert(
+            Album(
+                {
+                    Album.band: "Pythonistas",
+                }
+            ),
+            Album(
+                {
+                    Album.band: "Pythonistas",
+                }
+            ),
+            Album(
+                {
+                    Album.band: "Rustaceans",
+                }
+            ),
+        )
+
+        response = (
+            await Album.select(Album.band)
+            .group_by(Album.band)
+            .having(Count() >= 2)
+            .output(as_list=True)
+        )
+
+        self.assertIn("Pythonistas", response)
+        self.assertNotIn("Rustaceans", response)