1374 Add NullIf function (#1375)

* add `NullIf` function

* remove `default=None`

Author: dantownsend

docs/src/piccolo/functions/conditional.rst

@@ -7,3 +7,9 @@ Coalesce
 --------
 
 .. autoclass:: Coalesce
+
+
+NullIf
+------
+
+.. autoclass:: NullIf

piccolo/apps/playground/commands/run.py

@@ -72,6 +72,7 @@ class Venue(Table):
     id: Serial
     name = Varchar(length=100)
     capacity = Integer(default=0)
+    address = Text(null=True)
 
     @classmethod
     def get_readable(cls) -> Readable:

piccolo/query/functions/conditional.py

@@ -78,3 +78,45 @@ def __init__(
         placeholders = ", ".join("{}" for _ in args)
 
         super().__init__(f"COALESCE({placeholders})", *args, alias=alias)
+
+
+class NullIf(QueryString):
+    def __init__(
+        self,
+        identifier: Union[Column, QueryString],
+        value: Union[BasicTypes, QueryString],
+        alias: Optional[str] = None,
+    ):
+        """
+        Returns null if the value in the database equals ``value``.
+
+        An example is where a ``Varchar`` or ``Text`` column contains a mix of
+        empty strings and null. We might want to standardise the response so
+        it's just null.
+
+        For example::
+
+            class Venue(Table):
+                name = Varchar()
+                address = Text(null=True)
+
+            >>> await Venue.select(Venue.name, NullIf(Venue.address, ''))
+            [{'name': 'Amazing venue', 'address': None}]
+
+        """
+        # Preserve the original alias from the column.
+
+        from piccolo.columns import Column
+
+        if isinstance(identifier, Column):
+            alias = (
+                alias
+                or identifier._alias
+                or identifier._meta.get_default_alias()
+            )
+        elif isinstance(identifier, QueryString):
+            alias = alias or identifier._alias
+
+        #######################################################################
+
+        super().__init__("NULLIF({}, {})", identifier, value, alias=alias)

tests/query/functions/test_conditional.py

@@ -1,5 +1,5 @@
-from piccolo.columns import Integer
-from piccolo.query.functions.conditional import Coalesce
+from piccolo.columns import Integer, Text, Varchar
+from piccolo.query.functions.conditional import Coalesce, NullIf
 from piccolo.table import Table
 from piccolo.testing.test_case import AsyncTableTest
 
@@ -23,3 +23,22 @@ async def test_coalesce(self):
     async def test_coalesce_pipe_syntax(self):
         response = await Band.select(Band.popularity | 10)
         self.assertListEqual(response, [{"popularity": 10}])
+
+
+class Venue(Table):
+    name = Varchar()
+    address = Text(null=True)
+
+
+class TestNullIf(AsyncTableTest):
+
+    tables = [Venue]
+
+    async def test_null_if(self):
+        await Venue({Venue.name: "Amazing Venue", Venue.address: ""}).save()
+
+        response = await Venue.select(Venue.name, NullIf(Venue.address, ""))
+
+        self.assertListEqual(
+            response, [{"name": "Amazing Venue", "address": None}]
+        )