relationalai 0.13.5__py3-none-any.whl → 1.0.0a1__py3-none-any.whl

relationalai/semantics/std/datetime.py

@@ -1,10 +1,22 @@
 from __future__ import annotations
+
+from relationalai.semantics.std import floats
+
+from . import StringValue, IntegerValue, DateValue, DateTimeValue, math, common
+from ..frontend.base import Aggregate, Library, Concept, NumberConcept, Expression, Field, Literal, Variable
+from ..frontend.core import Float, Number, String, Integer, Date, DateTime
+from .. import select
+
 from typing import Union, Literal
 import datetime as dt
 
-from relationalai.semantics.internal import internal as b
-from .std import _DateTime, _Date, _Integer, _String, _make_expr
-from .. import std
+# the front-end library object
+library = Library("datetime")
+
+
+#--------------------------------------------------
+# Format String Constants
+#--------------------------------------------------
 
 class ISO:
     DATE = "yyyy-mm-dd"
@@ -17,76 +29,115 @@ class ISO:
     MILLIS = "yyyy-mm-ddTHH:MM:SS.s"
     MILLIS_TZ = "yyyy-mm-ddTHH:MM:SS.sz"
 
+
+
 #--------------------------------------------------
-# Date functions
+# Date
 #--------------------------------------------------
 
-class date:
+# Constructors
+_construct_date = library.Relation("construct_date", [Field.input("year", Integer), Field.input("month", Integer), Field.input("day", Integer), Field("date", Date)])
+_construct_date_from_datetime = library.Relation("construct_date_from_datetime", [Field.input("datetime", DateTime), Field.input("timezone", String), Field("date", Date)])
+_construct_datetime_ms_tz = library.Relation("construct_datetime_ms_tz", [
+    Field.input("year", Integer), Field.input("month", Integer), Field.input("day", Integer),
+    Field.input("hour", Integer), Field.input("minute", Integer), Field.input("second", Integer), Field.input("milliseconds", Integer),
+    Field.input("timezone", String),
+    Field("datetime", DateTime)]
+)
+_parse_date = library.Relation("parse_date", [Field.input("date_string", String), Field.input("format", String), Field("date", Date)])
+
+# Formatting
+_date_format = library.Relation("date_format", [Field.input("date", Date), Field.input("format", String), Field("result", String)])
+
+# Extractors
+_date_year = library.Relation("date_year", [Field.input("date", Date), Field("year", Number.size(19, 0))])
+_date_quarter = library.Relation("date_quarter", [Field.input("date", Date), Field("quarter", Integer)])
+_date_month = library.Relation("date_month", [Field.input("date", Date), Field("month", Integer)])
+_date_week = library.Relation("date_week", [Field.input("date", Date), Field("week", Integer)])
+_date_day = library.Relation("date_day", [Field.input("date", Date), Field("day", Integer)])
+_date_dayofyear = library.Relation("date_dayofyear", [Field.input("date", Date), Field("dayofyear", Integer)])
+_date_weekday = library.Relation("date_weekday", [Field.input("date", Date), Field("weekday", Integer)])
+
+# Date Operations
+_date_add = library.Relation("date_add", [Field.input("date", Date), Field.input("period", Integer), Field("result", Date)])
+_date_subtract = library.Relation("date_subtract", [Field.input("date", Date), Field.input("period", Integer), Field("result", Date)])
+
+# Date Ranges
+#   Still unimplemented because we need to add support for emitters to transform lookups using DSL itself. Also,
+#   the API is not clear, it could be better to have date_range_from_date where periods can be negative to go backwards.
+# _date_range = library.Relation("date_range", [Field.input("start", Date), Field.input("end", Date), Field.input("frequency", String), Field("date", Date)])
+# _date_range_from_start = library.Relation("date_range_from_start", [Field.input("start", Date), Field.input("periods", Integer), Field.input("frequency", String), Field("date", Date)])
+# _date_range_from_end = library.Relation("date_range_from_end", [Field.input("end", Date), Field.input("periods", Integer), Field.input("frequency", String), Field("date", Date)])
 
-    def __new__(cls, year: _Integer, month: _Integer, day: _Integer) -> b.Expression:
-        return _make_expr("construct_date", std.cast_to_int64(year), std.cast_to_int64(month), std.cast_to_int64(day), b.Date.ref("res"))
+class date:
+    def __new__(cls, year: IntegerValue, month: IntegerValue, day: IntegerValue) -> Expression:
+        return _construct_date(year, month, day)
 
     @classmethod
-    def year(cls, date: _Date) -> b.Expression:
-        return _make_expr("date_year", date, b.Int64.ref("res"))
+    def year(cls, date: DateValue) -> Expression:
+        return _date_year(date)
 
     @classmethod
-    def quarter(cls, date: _Date) -> b.Expression:
-        return _make_expr("date_quarter", date, b.Int64.ref("res"))
+    def quarter(cls, date: DateValue) -> Expression:
+        return _date_quarter(date)
 
     @classmethod
-    def month(cls, date: _Date) -> b.Expression:
-        return _make_expr("date_month", date, b.Int64.ref("res"))
+    def month(cls, date: DateValue) -> Expression:
+        return _date_month(date)
 
     @classmethod
-    def week(cls, date: _Date) -> b.Expression:
-        return _make_expr("date_week", date, b.Int64.ref("res"))
+    def week(cls, date: DateValue) -> Expression:
+        return _date_week(date)
 
     @classmethod
-    def day(cls, date: _Date) -> b.Expression:
-        return _make_expr("date_day", date, b.Int64.ref("res"))
+    def day(cls, date: DateValue) -> Expression:
+        return _date_day(date)
 
     @classmethod
-    def dayofyear(cls, date: _Date) -> b.Expression:
-        return _make_expr("date_dayofyear", date, b.Int64.ref("res"))
+    def dayofyear(cls, date: DateValue) -> Expression:
+        return _date_dayofyear(date)
 
     @classmethod
-    def isoweekday(cls, date: _Date) -> b.Expression:
+    def isoweekday(cls, date: DateValue) -> Expression:
         """
         Return the ISO weekday as an integer, where Monday is 1, and Sunday is 7.
         """
-        return _make_expr("date_weekday", date, b.Int64.ref("res"))
+        return _date_weekday(date)
 
     @classmethod
-    def weekday(cls, date: _Date) -> b.Expression:
+    def weekday(cls, date: DateValue) -> Expression:
         return cls.isoweekday(date) - 1 # Convert ISO weekday (1=Mon..7=Sun) to weekday (0=Mon..6=Sun)
 
     @classmethod
-    def fromordinal(cls, ordinal: _Integer) -> b.Expression:
+    def fromordinal(cls, ordinal: IntegerValue) -> Expression:
         # ordinal 1 = '0001-01-01'. Minus 1 day since we can't declare date 0000-00-00
-        return cls.add(b.Date(dt.date(1, 1, 1)), days(ordinal - 1))
+        return cls.add(Date(dt.date(1, 1, 1)), days(ordinal - 1))
 
     @classmethod
-    def to_datetime(cls, date: _Date, hour: int = 0, minute: int = 0, second: int = 0, millisecond: int = 0, tz: str = "UTC") -> b.Expression:
+    def to_datetime(cls, date: DateValue, hour: int = 0, minute: int = 0, second: int = 0, millisecond: int = 0, tz: str = "UTC") -> Expression:
         _year = cls.year(date)
         _month = cls.month(date)
         _day = cls.day(date)
-        return _make_expr("construct_datetime_ms_tz", _year, _month, _day, hour, minute, second, millisecond, tz, b.DateTime.ref("res"))
+        return _construct_datetime_ms_tz(_year, _month, _day, hour, minute, second, millisecond, tz)
 
     @classmethod
-    def format(cls, date: _Date, format: _String) -> b.Expression:
-        return _make_expr("date_format", date, format, b.String.ref("res"))
+    def format(cls, date: DateValue, format: StringValue) -> Expression:
+        return _date_format(date, format)
 
     @classmethod
-    def add(cls, date: _Date, period: b.Producer) -> b.Expression:
-        return _make_expr("date_add", date, period, b.Date.ref("res"))
+    def add(cls, date: DateValue, period: Variable) -> Expression:
+        return _date_add(date, period)
 
     @classmethod
-    def subtract(cls, date: _Date, period: b.Producer) -> b.Expression:
-        return _make_expr("date_subtract", date, period, b.Date.ref("res"))
+    def subtract(cls, date: DateValue, period: Variable) -> Expression:
+        return _date_subtract(date, period)
 
     @classmethod
-    def range(cls, start: _Date | None = None, end: _Date | None = None, periods: int = 1, freq: Frequency = "D") -> b.Expression:
+    def range(cls, start: DateValue | None = None, end: DateValue | None = None, periods: IntegerValue = 1, freq: Frequency = "D") -> Variable:
+        if start is None and end is None:
+            raise ValueError("Invalid start/end date for date.range. Must provide at least start date or end date")
+        if freq not in _days.keys():
+            raise ValueError(f"Frequency '{freq}' is not allowed for date_range. List of allowed frequencies: {list(_days.keys())}")
         """
         Note on date_ranges and datetime_range: The way the computation works is that it first overapproximates the
         number of periods.
@@ -98,18 +149,11 @@ class date:
         one too many in the second case. That's why a filter end >= _date (or variant of) is applied, to remove any
         extra item. The result is two items in both cases.
         """
-        if start is None and end is None:
-            raise ValueError("Invalid start/end date for date_range. Must provide at least start date or end date")
-        _days = {
-            "D": 1,
-            "W": 1/7,
-            "M": 1/(365/12),
-            "Y": 1/365,
-        }
-        if freq not in _days.keys():
-            raise ValueError(f"Frequency '{freq}' is not allowed for date_range. List of allowed frequencies: {list(_days.keys())}")
+        # TODO - this transformation is currently LQP-focused. Eventually we will want to
+        # move it into the LQP stack and have something general here.
         date_func = cls.add
         if start is None:
+            # compute end - periods*freq
             start = end
             end = None
             date_func = cls.subtract
@@ -117,146 +161,171 @@ class date:
         if end is not None:
             num_days = cls.period_days(start, end)
             if freq in ["W", "M", "Y"]:
-                range_end = std.cast(b.Int64, std.math.ceil(num_days * _days[freq]))
+                range_end = math.ceil(num_days * _days[freq])
             else:
                 range_end = num_days
             # date_range is inclusive. add 1 since std.range is exclusive
-            ix = std.range(0, range_end + 1, 1)
+            ix = common.range(0, range_end + 1, 1)
         else:
-            ix = std.range(0, periods, 1)
+            ix = common.range(0, periods, 1)
         _date = date_func(start, _periods[freq](ix))
         if isinstance(end, dt.date) :
-            return b.Date(end) >= _date
+            return select(_date).where(Date(end) >= _date)
         elif end is not None:
-            return end >= _date
+            return select(_date).where(end >= _date)
         return _date
 
+
     @classmethod
-    def period_days(cls, start: _Date, end: _Date) -> b.Expression:
-        return _make_expr("dates_period_days", start, end, b.Int64.ref("res"))
+    def period_days(cls, start: DateValue, end: DateValue) -> Expression:
+        return _dates_period_days(start, end)
 
     @classmethod
-    def fromisoformat(cls, date_string: _String) -> b.Expression:
-        return _make_expr("parse_date", date_string, ISO.DATE, b.Date.ref("res"))
+    def fromisoformat(cls, date_string: StringValue) -> Expression:
+        return _parse_date(date_string, ISO.DATE)
 
 #--------------------------------------------------
-# DateTime functions
+# DateTime
 #--------------------------------------------------
 
+# Constructors
+_construct_datetime_ms_tz = library.Relation("construct_datetime_ms_tz", [
+    Field.input("year", Integer), Field.input("month", Integer), Field.input("day", Integer),
+    Field.input("hour", Integer), Field.input("minute", Integer), Field.input("second", Integer), Field.input("milliseconds", Integer),
+    Field.input("timezone", String),
+    Field("datetime", DateTime)]
+)
+_datetime_now = library.Relation("datetime_now", [Field("datetime", DateTime)])
+_parse_datetime = library.Relation("parse_datetime", [Field.input("datetime_string", String), Field.input("format", String), Field("datetime", DateTime)])
+
+# Formatting
+_datetime_format = library.Relation("datetime_format", [Field.input("datetime", DateTime), Field.input("format", String), Field.input("timezone", String), Field("result", String)])
+
+# Extractors
+_datetime_year = library.Relation("datetime_year", [Field.input("datetime", DateTime), Field.input("timezone", String), Field("year", Integer)])
+_datetime_quarter = library.Relation("datetime_quarter", [Field.input("datetime", DateTime), Field.input("timezone", String), Field("quarter", Integer)])
+_datetime_month = library.Relation("datetime_month", [Field.input("datetime", DateTime), Field.input("timezone", String), Field("month", Integer)])
+_datetime_week = library.Relation("datetime_week", [Field.input("datetime", DateTime), Field.input("timezone", String), Field("week", Integer)])
+_datetime_day = library.Relation("datetime_day", [Field.input("datetime", DateTime), Field.input("timezone", String), Field("day", Integer)])
+_datetime_dayofyear = library.Relation("datetime_dayofyear", [Field.input("datetime", DateTime), Field.input("timezone", String), Field("dayofyear", Integer)])
+_datetime_hour = library.Relation("datetime_hour", [Field.input("datetime", DateTime), Field.input("timezone", String), Field("hour", Integer)])
+_datetime_minute = library.Relation("datetime_minute", [Field.input("datetime", DateTime), Field.input("timezone", String), Field("minute", Integer)])
+# no timezone needed for second extraction
+_datetime_second = library.Relation("datetime_second", [Field.input("datetime", DateTime), Field("second", Integer)])
+_datetime_weekday = library.Relation("datetime_weekday", [Field.input("datetime", DateTime), Field.input("timezone", String), Field("weekday", Integer)])
+
+# DateTime Operations
+_datetime_add = library.Relation("datetime_add", [Field.input("datetime", DateTime), Field.input("period", Integer), Field("result", DateTime)])
+_datetime_subtract = library.Relation("datetime_subtract", [Field.input("datetime", DateTime), Field.input("period", Integer), Field("result", DateTime)])
+
+# DateTime Ranges (see comment on Date Ranges)
+# _datetime_range = library.Relation("datetime_range", [Field.input("start", DateTime), Field.input("end", DateTime), Field.input("frequency", String), Field("datetime", DateTime)])
+# _datetime_range_from_start = library.Relation("datetime_range_from_start", [Field.input("start", DateTime), Field.input("periods", Integer), Field.input("frequency", String), Field("datetime", DateTime)])
+# _datetime_range_from_end = library.Relation("datetime_range_from_end", [Field.input("end", DateTime), Field.input("periods", Integer), Field.input("frequency", String), Field("datetime", DateTime)])
+
 class datetime:
 
-    def __new__(cls, year: _Integer, month: _Integer, day: _Integer, hour: _Integer = 0, minute: _Integer = 0,
-             second: _Integer = 0, millisecond: _Integer = 0, tz: dt.tzinfo|_String = "UTC") -> b.Expression:
+    def __new__(cls, year: IntegerValue, month: IntegerValue, day: IntegerValue, hour: IntegerValue = 0, minute: IntegerValue = 0,
+             second: IntegerValue = 0, millisecond: IntegerValue = 0, tz: dt.tzinfo|StringValue = "UTC") -> Expression:
         if isinstance(tz, dt.tzinfo):
             tz = str(tz)
-        return _make_expr("construct_datetime_ms_tz", std.cast_to_int64(year), std.cast_to_int64(month),
-                          std.cast_to_int64(day), std.cast_to_int64(hour), std.cast_to_int64(minute),
-                          std.cast_to_int64(second), std.cast_to_int64(millisecond), tz, b.DateTime.ref("res"))
+        return _construct_datetime_ms_tz(year, month, day, hour, minute, second, millisecond, tz)
 
     @classmethod
-    def now(cls) -> b.Expression:
-        return _make_expr("datetime_now", b.DateTime.ref("res"))
+    def now(cls) -> Expression:
+        return _datetime_now()
 
     @classmethod
-    def year(cls, datetime: _DateTime, tz: dt.tzinfo|_String|None = None) -> b.Expression:
+    def year(cls, datetime: DateTimeValue, tz: dt.tzinfo|StringValue|None = None) -> Expression:
         tz = _extract_tz(datetime, tz)
-        return _make_expr("datetime_year", datetime, tz, b.Int64.ref("res"))
+        return _datetime_year(datetime, tz)
 
     @classmethod
-    def quarter(cls, datetime: _DateTime,  tz: dt.tzinfo|_String|None = None) -> b.Expression:
+    def quarter(cls, datetime: DateTimeValue,  tz: dt.tzinfo|StringValue|None = None) -> Expression:
         tz = _extract_tz(datetime, tz)
-        return _make_expr("datetime_quarter", datetime, tz, b.Int64.ref("res"))
+        return _datetime_quarter(datetime, tz)
 
     @classmethod
-    def month(cls, datetime: _DateTime, tz: dt.tzinfo|_String|None = None) -> b.Expression:
+    def month(cls, datetime: DateTimeValue, tz: dt.tzinfo|StringValue|None = None) -> Expression:
         tz = _extract_tz(datetime, tz)
-        return _make_expr("datetime_month", datetime, tz, b.Int64.ref("res"))
+        return _datetime_month(datetime, tz)
 
     @classmethod
-    def week(cls, datetime: _DateTime, tz: dt.tzinfo|_String|None = None) -> b.Expression:
+    def week(cls, datetime: DateTimeValue, tz: dt.tzinfo|StringValue|None = None) -> Expression:
         tz = _extract_tz(datetime, tz)
-        return _make_expr("datetime_week", datetime, tz, b.Int64.ref("res"))
+        return _datetime_week(datetime, tz)
 
     @classmethod
-    def day(cls, datetime: _DateTime, tz: dt.tzinfo|_String|None = None) -> b.Expression:
+    def day(cls, datetime: DateTimeValue, tz: dt.tzinfo|StringValue|None = None) -> Expression:
         tz = _extract_tz(datetime, tz)
-        return _make_expr("datetime_day", datetime, tz, b.Int64.ref("res"))
+        return _datetime_day(datetime, tz)
 
     @classmethod
-    def dayofyear(cls, datetime: _DateTime, tz: dt.tzinfo|_String|None = None) -> b.Expression:
+    def dayofyear(cls, datetime: DateTimeValue, tz: dt.tzinfo|StringValue|None = None) -> Expression:
         tz = _extract_tz(datetime, tz)
-        return _make_expr("datetime_dayofyear", datetime, tz, b.Int64.ref("res"))
+        return _datetime_dayofyear(datetime, tz)
 
     @classmethod
-    def hour(cls, datetime: _DateTime, tz: dt.tzinfo|_String|None = None) -> b.Expression:
+    def hour(cls, datetime: DateTimeValue, tz: dt.tzinfo|StringValue|None = None) -> Expression:
         tz = _extract_tz(datetime, tz)
-        return _make_expr("datetime_hour", datetime, tz, b.Int64.ref("res"))
+        return _datetime_hour(datetime, tz)
 
     @classmethod
-    def minute(cls, datetime: _DateTime, tz: dt.tzinfo|_String|None = None) -> b.Expression:
+    def minute(cls, datetime: DateTimeValue, tz: dt.tzinfo|StringValue|None = None) -> Expression:
         tz = _extract_tz(datetime, tz)
-        return _make_expr("datetime_minute", datetime, tz, b.Int64.ref("res"))
+        return _datetime_minute(datetime, tz)
 
     @classmethod
-    def second(cls, datetime: _DateTime) -> b.Expression:
-        return _make_expr("datetime_second", datetime, b.Int64.ref("res"))
+    def second(cls, datetime: DateTimeValue) -> Expression:
+        return _datetime_second(datetime)
 
     @classmethod
-    def isoweekday(cls, datetime: _DateTime, tz: dt.tzinfo|_String|None = None) -> b.Expression:
+    def isoweekday(cls, datetime: DateTimeValue, tz: dt.tzinfo|StringValue|None = None) -> Expression:
         """
         Return the ISO weekday as an integer, where Monday is 1, and Sunday is 7.
         """
         tz = _extract_tz(datetime, tz)
-        return _make_expr("datetime_weekday", datetime, tz, b.Int64.ref("res"))
+        return _datetime_weekday(datetime, tz)
 
     @classmethod
-    def weekday(cls, datetime: _DateTime, tz: dt.tzinfo|_String|None = None) -> b.Expression:
+    def weekday(cls, datetime: DateTimeValue, tz: dt.tzinfo|StringValue|None = None) -> Expression:
         return cls.isoweekday(datetime, tz) - 1 # Convert ISO weekday (1=Mon..7=Sun) to weekday (0=Mon..6=Sun)
 
     @classmethod
-    def fromordinal(cls, ordinal: _Integer) -> b.Expression:
+    def fromordinal(cls, ordinal: IntegerValue) -> Expression:
         # Convert ordinal to milliseconds, since ordinals in Python are days
         # Minus 1 day since we can't declare date 0000-00-00
         ordinal_milliseconds = (ordinal - 1) * 86400000 # 24 * 60 * 60 * 1000
-        return cls.add(b.DateTime(dt.datetime(1, 1, 1, 0, 0, 0)), milliseconds(ordinal_milliseconds))
+        return cls.add(DateTime(dt.datetime(1, 1, 1, 0, 0, 0)), milliseconds(ordinal_milliseconds))
 
     @classmethod
-    def strptime(cls, date_str: _String, format: _String) -> b.Expression:
-        return _make_expr("parse_datetime", date_str, format, b.DateTime.ref("res"))
+    def strptime(cls, date_str: StringValue, format: StringValue) -> Expression:
+        return _parse_datetime(date_str, format)
 
     @classmethod
-    def to_date(cls, datetime: _DateTime, tz: dt.tzinfo|_String|None = None) -> b.Expression:
+    def to_date(cls, datetime: DateTimeValue, tz: dt.tzinfo|StringValue|None = None) -> Expression:
         tz = _extract_tz(datetime, tz)
-        return _make_expr("construct_date_from_datetime", datetime, tz, b.Date.ref("res"))
+        return _construct_date_from_datetime(datetime, tz)
 
     @classmethod
-    def format(cls, date: _DateTime, format: _String, tz: dt.tzinfo|_String|None = None) -> b.Expression:
+    def format(cls, date: DateTimeValue, format: StringValue, tz: dt.tzinfo|StringValue|None = None) -> Expression:
         tz = _extract_tz(date, tz)
-        return _make_expr("datetime_format", date, format, tz, b.String.ref("res"))
+        return _datetime_format(date, format, tz)
 
     @classmethod
-    def add(cls, date: _DateTime, period: b.Producer) -> b.Expression:
-        return _make_expr("datetime_add", date, period, b.DateTime.ref("res"))
+    def add(cls, date: DateTimeValue, period: Variable) -> Expression:
+        return _datetime_add(date, period)
 
     @classmethod
-    def subtract(cls, date: _DateTime, period: b.Producer) -> b.Expression:
-        return _make_expr("datetime_subtract", date, period, b.DateTime.ref("res"))
+    def subtract(cls, date: DateTimeValue, period: Variable) -> Expression:
+        return _datetime_subtract(date, period)
 
     @classmethod
-    def range(cls, start: _DateTime | None = None, end: _DateTime | None = None, periods: int = 1, freq: Frequency = "D") -> b.Expression:
-        """
-        Note on date_ranges and datetime_range: The way the computation works is that it first overapproximates the
-        number of periods.
-
-        For example, date_range(2025-02-01, 2025-03-01, freq='M') and date_range(2025-02-01, 2025-03-31, freq='M') will
-        compute range_end to be ceil(28*1/(365/12))=1 and ceil(58*1/(365/12))=2.
-
-        Then, the computation fetches range_end+1 items into _date, which is the right number in the first case but
-        one too many in the second case. That's why a filter end >= _date (or variant of) is applied, to remove any
-        extra item. The result is two items in both cases.
-        """
+    def range(cls, start: DateTimeValue | None = None, end: DateTimeValue | None = None, periods: IntegerValue = 1, freq: Frequency = "D") -> Variable:
         if start is None and end is None:
-            raise ValueError("Invalid start/end datetime for datetime_range. Must provide at least start datetime or end datetime")
+            raise ValueError("Invalid start/end date for datetime.range. Must provide at least start date or end date")
+        # TODO - this transformation is currently LQP-focused. Eventually we will want to
+        # move it into the LQP stack and have something general here.
         _milliseconds = {
             "ms": 1,
             "s": 1 / 1_000,
@@ -278,55 +347,86 @@ class datetime:
             if freq == "ms":
                 _end = num_ms
             else:
-                _end = std.cast(b.Int64, std.math.ceil(num_ms * _milliseconds[freq]))
-            # datetime_range is inclusive. add 1 since std.range is exclusive
-            ix = std.range(0, _end + 1, 1)
+                _end = math.ceil(num_ms * Float(_milliseconds[freq]))
+            # datetime_range is inclusive. add 1 since common.range is exclusive
+            ix = common.range(0, _end + 1, 1)
         else:
-            ix = std.range(0, periods, 1)
+            ix = common.range(0, periods, 1)
         _date = date_func(start, _periods[freq](ix))
         if isinstance(end, dt.datetime) :
-            return b.DateTime(end) >= _date
+            return select(_date).where(DateTime(end) >= _date)
         elif end is not None:
-            return end >= _date
+            return select(_date).where(end >= _date)
         return _date
 
+
+
     @classmethod
-    def period_milliseconds(cls, start: _DateTime, end: _DateTime) -> b.Expression:
-        return _make_expr("datetimes_period_milliseconds", start, end, b.Int64.ref("res"))
+    def period_milliseconds(cls, start: DateTimeValue, end: DateTimeValue) -> Expression:
+        return _datetimes_period_milliseconds(start, end)
+
 
 #--------------------------------------------------
 # Periods
 #--------------------------------------------------
 
-def nanoseconds(period: _Integer) -> b.Expression:
-    return _make_expr("nanosecond", std.cast_to_int64(period), b.Int64.ref("res"))
+# Concepts
+Nanoseconds = library.Type("Nanoseconds", [Integer])
+Microseconds = library.Type("Microseconds", [Integer])
+Milliseconds = library.Type("Milliseconds", [Integer])
+Seconds = library.Type("Seconds", [Integer])
+Minutes = library.Type("Minutes", [Integer])
+Hours = library.Type("Hours", [Integer])
+Days = library.Type("Days", [Integer])
+Weeks = library.Type("Weeks", [Integer])
+Months = library.Type("Months", [Integer])
+Years = library.Type("Years", [Integer])
+
+# Constructors from Date/DateTime
+_dates_period_days = library.Relation("dates_period_days", [Field.input("start", Date), Field.input("end", Date), Field("days", Days)])
+_datetimes_period_milliseconds = library.Relation("datetimes_period_milliseconds", [Field.input("start", DateTime), Field.input("end", DateTime), Field("milliseconds", Milliseconds)])
+
+# Basic Constructors
+_nanosecond = library.Relation("nanosecond", [Field.input("nanoseconds", Integer), Field("period", Nanoseconds)])
+_microsecond = library.Relation("microsecond", [Field.input("microseconds", Integer), Field("period", Microseconds)])
+_millisecond = library.Relation("millisecond", [Field.input("milliseconds", Integer), Field("period", Milliseconds)])
+_second = library.Relation("second", [Field.input("seconds", Integer), Field("period", Seconds)])
+_minute = library.Relation("minute", [Field.input("minutes", Integer), Field("period", Minutes)])
+_hour = library.Relation("hour", [Field.input("hours", Integer), Field("period", Hours)])
+_day = library.Relation("day", [Field.input("days", Integer), Field("period", Days)])
+_week = library.Relation("week", [Field.input("weeks", Integer), Field("period", Weeks)])
+_month = library.Relation("month", [Field.input("months", Integer), Field("period", Months)])
+_year = library.Relation("year", [Field.input("years", Integer), Field("period", Years)])
+
+def nanoseconds(period: IntegerValue) -> Expression:
+    return _nanosecond(period)
 
-def microseconds(period: _Integer) -> b.Expression:
-    return _make_expr("microsecond", std.cast_to_int64(period), b.Int64.ref("res"))
+def microseconds(period: IntegerValue) -> Expression:
+    return _microsecond(period)
 
-def milliseconds(period: _Integer) -> b.Expression:
-    return _make_expr("millisecond", std.cast_to_int64(period), b.Int64.ref("res"))
+def milliseconds(period: IntegerValue) -> Expression:
+    return _millisecond(period)
 
-def seconds(period: _Integer) -> b.Expression:
-    return _make_expr("second", std.cast_to_int64(period), b.Int64.ref("res"))
+def seconds(period: IntegerValue) -> Expression:
+    return _second(period)
 
-def minutes(period: _Integer) -> b.Expression:
-    return _make_expr("minute", std.cast_to_int64(period), b.Int64.ref("res"))
+def minutes(period: IntegerValue) -> Expression:
+    return _minute(period)
 
-def hours(period: _Integer) -> b.Expression:
-    return _make_expr("hour", std.cast_to_int64(period), b.Int64.ref("res"))
+def hours(period: IntegerValue) -> Expression:
+    return _hour(period)
 
-def days(period: _Integer) -> b.Expression:
-    return _make_expr("day", std.cast_to_int64(period), b.Int64.ref("res"))
+def days(period: IntegerValue) -> Expression:
+    return _day(period)
 
-def weeks(period: _Integer) -> b.Expression:
-    return _make_expr("week", std.cast_to_int64(period), b.Int64.ref("res"))
+def weeks(period: IntegerValue) -> Expression:
+    return _week(period)
 
-def months(period: _Integer) -> b.Expression:
-    return _make_expr("month", std.cast_to_int64(period), b.Int64.ref("res"))
+def months(period: IntegerValue) -> Expression:
+    return _month(period)
 
-def years(period: _Integer) -> b.Expression:
-    return _make_expr("year", std.cast_to_int64(period), b.Int64.ref("res"))
+def years(period: IntegerValue) -> Expression:
+    return _year(period)
 
 
 Frequency = Union[
@@ -351,7 +451,18 @@ _periods = {
     "Y": years,
 }
 
-def _extract_tz(datetime: _DateTime, tz: dt.tzinfo|_String|None) -> _String:
+_days = {
+    "D": 1,
+    "W": Float(1/7),
+    "M": Float(1/(365/12)),
+    "Y": Float(1/365),
+}
+
+#--------------------------------------------------
+# Helpers
+#--------------------------------------------------
+
+def _extract_tz(datetime: DateTimeValue, tz: dt.tzinfo|StringValue|None) -> StringValue:
     default_tz = "UTC"
     if tz is None:
         if isinstance(datetime, dt.datetime):