prototype for Extract

piccolo/columns/column_types.py

@@ -62,6 +62,8 @@ class Band(Table):
 
 if t.TYPE_CHECKING: # pragma: no cover
  from piccolo.columns.base import ColumnMeta
+ from piccolo.custom_types import ExtractField
+ from piccolo.query.methods.select import Extract
  from piccolo.table import Table
 
 
@@ -928,6 +930,36 @@ def __init__(
  kwargs.update({"default": default})
  super().__init__(**kwargs)
 
+ ###########################################################################
+ # Extract part of the timestamp in a query (e.g. the year).
+
+ def extract(self, field: ExtractField) -> Extract:
+ """
+ Used for extracting part of a timestamp. For example::
+
+ >>> await Concert.select(Concert.starts.extract('year')).distinct()
+
+ Or alternatively, use this convenience method::
+
+ >>> await Concert.select(Concert.starts.year).distinct()
+
+ """
+ from piccolo.query.methods.select import Extract
+
+ return Extract(column=self, field=field)
+
+ @property
+ def year(self) -> Extract:
+ return self.extract(field="year")
+
+ @property
+ def month(self) -> Extract:
+ return self.extract(field="month")
+
+ @property
+ def day(self) -> Extract:
+ return self.extract(field="day")
+
  ###########################################################################
  # For update queries
 

piccolo/custom_types.py

@@ -2,6 +2,8 @@
 
 import typing as t
 
+from typing_extensions import Literal
+
 if t.TYPE_CHECKING: # pragma: no cover
  from piccolo.columns.combination import And, Or, Where, WhereRaw # noqa
  from piccolo.table import Table
@@ -14,6 +16,31 @@
 TableInstance = t.TypeVar("TableInstance", bound="Table")
 QueryResponseType = t.TypeVar("QueryResponseType", bound=t.Any)
 
+ExtractField = Literal[
+ "century",
+ "day",
+ "decade",
+ "dow",
+ "doy",
+ "epoch",
+ "hour",
+ "isodow",
+ "isoyear",
+ "julian",
+ "microseconds",
+ "millennium",
+ "milliseconds",
+ "minute",
+ "month",
+ "quarter",
+ "second",
+ "timezone",
+ "timezone_hour",
+ "timezone_minute",
+ "week",
+ "year",
+]
+
 
 ###############################################################################
 # For backwards compatibility:

piccolo/query/methods/select.py

@@ -33,7 +33,7 @@
 from piccolo.utils.warnings import colored_warning
 
 if t.TYPE_CHECKING: # pragma: no cover
- from piccolo.custom_types import Combinable
+ from piccolo.custom_types import Combinable, ExtractField
  from piccolo.table import Table # noqa
 
 
@@ -63,6 +63,29 @@ def get_select_string(
  return self.querystring.__str__()
 
 
+class Extract(Selectable):
+ def __init__(
+ self,
+ column: Column,
+ field: ExtractField,
+ alias: t.Optional[str] = None,
+ ):
+ self.column = column
+ self.field = field
+ self._alias = alias
+
+ def get_select_string(
+ self, engine_type: str, with_alias: bool = True
+ ) -> str:
+ # TODO - need to use strftime for SQLite
+ column_name = self.column._meta.get_full_name(with_alias=False)
+ field = self.field
+ alias = self._alias or field
+ return f'EXTRACT({field} FROM {column_name}) AS "{alias}"'
+
+ # TODO - proxy methods like >, ==, != to the underlying column
+
+
 class Avg(Selectable):
  """
  ``AVG()`` SQL function. Column type must be numeric to run the query.