feat: add temporal functions

Co-authored-by: Weston Pace <[email protected]>

extensions/functions_datetime.yaml

@@ -3,36 +3,111 @@
 scalar_functions:
   -
     name: extract
-    description: Extract portion of a date/time value.
+    description:  >-
+      Extract portion of a date/time value.
+      * YEAR Return the year of the value.
+      * ISO_YEAR Return the ISO 8601 week-numbering year. First week of an ISO year has the majority (4 or more) of its
+        days in January.
+      * US_YEAR Return US epidemiological year. First week of US epidemiological year has the majority (4 or more) of
+        its days in January. Last week of US epidemiological year has the year's last Wednesday in it.
+        US epidemiological week starts on Sunday.
+      * QUARTER Return the quarter from the value (1-4).
+      * MONTH Return the month from value (1-12).
+      * DAY Return the day of the month (1-31).
+      * DAY_OF_YEAR Return the day of year (1 to 366). January 1st maps to day number 1, February 1st to 32, etc.
+      * MONDAY_DAY_OF_WEEK Return the day of week from Monday (1) to Sunday (7).
+      * SUNDAY_DAY_OF_WEEK Return the day of week from Sunday (1) to Saturday (7).
+      * MONDAY_WEEK Return week of year number (1-53). First week starts on first Monday of January.
+      * SUNDAY_WEEK Return week of year number (1-53). First week starts on first Sunday of January.
+      * ISO_WEEK Return ISO week of year number (1-53). First ISO calendar week has the majority (4 or more) of its
+        days in January. ISO week starts on Monday.
+      * US_WEEK Return ISO-like week of year number (1-53). First US calendar week has the majority (4 or more) of its
+        days in January. US week starts on Sunday.
+      * HOUR Return the hour (0-23).
+      * MINUTE Return the minute (0-59).
+      * SECOND Return the second (0-59).
+      * MILLISECOND Return number of milliseconds since the last full second.
+      * MICROSECOND Return number of microseconds since the last full millisecond.
+      * SUBSECOND Return number of microseconds since the last full second of the given timestamp.
+      * UNIX_TIME Return number of seconds that have elapsed since 1970-01-01 00:00:00 UTC, ignoring leap seconds.
+      * TIMEZONE_OFFSET Return number of seconds of timezone offset to UTC.
+
+      Timezone strings must be as defined by IANA timezone database (https://www.iana.org/time-zones).
+      Examples: "Pacific/Marquesas", "Etc/GMT+1".
+      If timezone is invalid an error is thrown.
     impls:
       - args:
           - name: component
-            options: [ YEAR, MONTH, DAY, SECOND ]
+            options: [ YEAR, ISO_YEAR, US_YEAR, QUARTER, MONTH, DAY, DAY_OF_YEAR, MONDAY_DAY_OF_WEEK,
+                       SUNDAY_DAY_OF_WEEK, MONDAY_WEEK, SUNDAY_WEEK, ISO_WEEK, US_WEEK, HOUR, MINUTE, SECOND,
+                       MILLISECOND, MICROSECOND, SUBSECOND, UNIX_TIME, TIMEZONE_OFFSET ]
             description: The part of the value to extract.
           - name: x
-            value: timestamp
+            value: timestamp_tz
+          - name: timezone
+            description: Timezone string from IANA tzdb.
+            value: string
         return: i64
       - args:
           - name: component
-            options: [ YEAR, MONTH, DAY, SECOND ]
+            options: [ YEAR, ISO_YEAR, US_YEAR, QUARTER, MONTH, DAY, DAY_OF_YEAR, MONDAY_DAY_OF_WEEK,
+                       SUNDAY_DAY_OF_WEEK, MONDAY_WEEK, SUNDAY_WEEK, ISO_WEEK, US_WEEK, HOUR, MINUTE, SECOND,
+                       MILLISECOND, MICROSECOND, SUBSECOND, UNIX_TIME ]
             description: The part of the value to extract.
           - name: x
-            value: timestamp_tz
+            value: timestamp
         return: i64
       - args:
           - name: component
-            options: [ YEAR, MONTH, DAY ]
+            options: [ YEAR, ISO_YEAR, US_YEAR, QUARTER, MONTH, DAY, DAY_OF_YEAR, MONDAY_DAY_OF_WEEK,
+                       SUNDAY_DAY_OF_WEEK, MONDAY_WEEK, SUNDAY_WEEK, ISO_WEEK, US_WEEK, UNIX_TIME ]
             description: The part of the value to extract.
           - name: x
             value: date
         return: i64
       - args:
           - name: component
-            options: [ SECOND ]
+            options: [ HOUR, MINUTE, SECOND, MILLISECOND, MICROSECOND, SUBSECOND ]
             description: The part of the value to extract.
           - name: x
             value: time
         return: i64
+  -
+    name: "extract_boolean"
+    description: >-
+      Extract boolean values of a date/time value.
+      * IS_LEAP_YEAR Return true if year of the given value is a leap year and false otherwise.
+      * IS_DST Return true if DST (Daylight Savings Time) is observed at the given value
+        in the given timezone.
+
+      Timezone strings must be as defined by IANA timezone database (https://www.iana.org/time-zones).
+      Examples: "Pacific/Marquesas", "Etc/GMT+1".
+      If timezone is invalid an error is thrown.
+    impls:
+      - args:
+          - name: component
+            options: [ IS_LEAP_YEAR ]
+            description: The part of the value to extract.
+          - name: x
+            value: timestamp
+        return: boolean
+      - args:
+          - name: component
+            options: [ IS_LEAP_YEAR, IS_DST ]
+            description: The part of the value to extract.
+          - name: x
+            value: timestamp_tz
+          - name: timezone
+            description: Timezone string from IANA tzdb.
+            value: string
+        return: boolean
+      - args:
+          - name: component
+            options: [ IS_LEAP_YEAR ]
+            description: The part of the value to extract.
+          - name: x
+            value: date
+        return: boolean
   -
     name: "add"
     description: >-
@@ -287,3 +362,255 @@ scalar_functions:
           - name: y
             value: interval_year
         return: boolean
+  -
+    name: "assume_timezone"
+    description: >-
+      Convert local timestamp to UTC-relative timestamp_tz using given local time's timezone.
+
+      Timezone strings must be as defined by IANA timezone database (https://www.iana.org/time-zones).
+      Examples: "Pacific/Marquesas", "Etc/GMT+1".
+      If timezone is invalid an error is thrown.
+    impls:
+      - args:
+          - name: x
+            value: timestamp
+          - name: timezone
+            description: Timezone string from IANA tzdb.
+            value: string
+        return: timestamp_tz
+      - args:
+          - name: x
+            value: date
+          - name: timezone
+            description: Timezone string from IANA tzdb. Returned timestamp_tz will have time set to 00:00:00.
+            value: string
+        return: timestamp_tz
+  -
+    name: "convert_timezone"
+    description: >-
+      Convert UTC-relative timestamp_tz to local timestamp using given local time's timezone.
+
+      Timezone strings must be as defined by IANA timezone database (https://www.iana.org/time-zones).
+      Examples: "Pacific/Marquesas", "Etc/GMT+1".
+      If timezone is invalid an error is thrown.
+    impls:
+      - args:
+          - name: x
+            value: timestamp_tz
+          - name: timezone
+            description: Timezone string from IANA tzdb.
+            value: string
+        return: timestamp
+  -
+    name: "strptime"
+    description: >-
+      Parse string into timestamp/date/time using provided format,
+      see https://man7.org/linux/man-pages/man3/strptime.3.html for reference.
+      If timezone is present in timestamp and provided as parameter an error is thrown.
+
+      Timezone strings must be as defined by IANA timezone database (https://www.iana.org/time-zones).
+      Examples: "Pacific/Marquesas", "Etc/GMT+1".
+      If timezone is supplied as parameter and present in the parsed string the parsed timezone is used.
+      If parameter supplied timezone is invalid an error is thrown.
+    impls:
+      - args:
+          - name: timestamp_string
+            value: string
+          - name: format
+            value: string
+          - name: timezone
+            description: Timezone string from IANA tzdb.
+            value: string
+        return: timestamp_tz
+      - args:
+          - name: timestamp_string
+            value: string
+          - name: format
+            value: string
+        return: timestamp_tz
+      - args:
+          - name: date_string
+            value: string
+          - name: format
+            value: string
+        return: date
+      - args:
+          - name: time_string
+            value: string
+          - name: format
+            value: string
+        return: time
+  -
+    name: "strftime"
+    description: >-
+      Convert timestamp/date/time to string using provided format,
+      see https://man7.org/linux/man-pages/man3/strftime.3.html for reference.
+
+      Timezone strings must be as defined by IANA timezone database (https://www.iana.org/time-zones).
+      Examples: "Pacific/Marquesas", "Etc/GMT+1".
+      If timezone is invalid an error is thrown.
+    impls:
+      - args:
+          - name: x
+            value: timestamp
+          - name: format
+            value: string
+        return: string
+      - args:
+          - name: x
+            value: timestamp_tz
+          - name: format
+            value: string
+          - name: timezone
+            description: Timezone string from IANA tzdb.
+            value: string
+        return: string
+      - args:
+          - name: x
+            value: date
+          - name: format
+            value: string
+        return: string
+      - args:
+          - name: x
+            value: time
+          - name: format
+            value: string
+        return: string
+  -
+    name: "round_temporal"
+    description: >-
+      Round a given timestamp/date/time to a multiple of a time unit. If the given timestamp is not already an
+      exact multiple from the origin in the given timezone, the resulting point is chosen as one of the
+      two nearest multiples. Which of these is chosen is governed by rounding: FLOOR means to use the earlier
+      one, CEIL means to use the later one, ROUND_TIE_DOWN means to choose the nearest and tie to the
+      earlier one if equidistant, ROUND_TIE_UP means to choose the nearest and tie to the later one if
+      equidistant.
+
+      Timezone strings must be as defined by IANA timezone database (https://www.iana.org/time-zones).
+      Examples: "Pacific/Marquesas", "Etc/GMT+1".
+      If timezone is invalid an error is thrown.
+    impls:
+      - args:
+          - name: x
+            value: timestamp
+          - name: rounding
+            options: [ FLOOR, CEIL, ROUND_TIE_DOWN, ROUND_TIE_UP ]
+          - name: unit
+            options: [ YEAR, MONTH, WEEK, DAY, HOUR, MINUTE, SECOND, MILLISECOND, MICROSECOND ]
+          - name: multiple
+            value: i64
+          - name: origin
+            value: timestamp
+        return: timestamp
+      - args:
+          - name: x
+            value: timestamp_tz
+          - name: rounding
+            options: [ FLOOR, CEIL, ROUND_TIE_DOWN, ROUND_TIE_UP ]
+          - name: unit
+            options: [ YEAR, MONTH, WEEK, DAY, HOUR, MINUTE, SECOND, MILLISECOND, MICROSECOND ]
+          - name: multiple
+            value: i64
+          - name: timezone
+            description: Timezone string from IANA tzdb.
+            value: string
+          - name: origin
+            value: timestamp_tz
+        return: timestamp_tz
+      - args:
+          - name: x
+            value: date
+          - name: rounding
+            options: [ FLOOR, CEIL, ROUND_TIE_DOWN, ROUND_TIE_UP ]
+          - name: unit
+            options: [ YEAR, MONTH, WEEK, DAY ]
+          - name: multiple
+            value: i64
+          - name: origin
+            value: date
+        return: date
+      - args:
+          - name: x
+            value: time
+          - name: rounding
+            options: [ FLOOR, CEIL, ROUND_TIE_DOWN, ROUND_TIE_UP ]
+          - name: unit
+            options: [ HOUR, MINUTE, SECOND, MILLISECOND, MICROSECOND ]
+          - name: multiple
+            value: i64
+          - name: origin
+            value: time
+        return: time
+  -
+    name: "round_calendar"
+    description: >-
+      Round a given timestamp/date/time to a multiple of a time unit. If the given timestamp is not already an
+      exact multiple from the last origin unit in the given timezone, the resulting point is chosen as one of the
+      two nearest multiples. Which of these is chosen is governed by rounding: FLOOR means to use the earlier
+      one, CEIL means to use the later one, ROUND_TIE_DOWN means to choose the nearest and tie to the
+      earlier one if equidistant, ROUND_TIE_UP means to choose the nearest and tie to the later one if
+      equidistant.
+
+      Timezone strings must be as defined by IANA timezone database (https://www.iana.org/time-zones).
+      Examples: "Pacific/Marquesas", "Etc/GMT+1".
+      If timezone is invalid an error is thrown.
+
+    impls:
+      - args:
+          - name: x
+            value: timestamp
+          - name: rounding
+            options: [ FLOOR, CEIL, ROUND_TIE_DOWN, ROUND_TIE_UP ]
+          - name: unit
+            options: [ YEAR, MONTH, WEEK, DAY, HOUR, MINUTE, SECOND, MILLISECOND, MICROSECOND ]
+          - name: origin
+            options: [ YEAR, MONTH, MONDAY_WEEK, SUNDAY_WEEK, ISO_WEEK,
+                       US_WEEK, DAY, HOUR, MINUTE, SECOND, MILLISECOND ]
+          - name: multiple
+            value: i64
+        return: timestamp
+      - args:
+          - name: x
+            value: timestamp_tz
+          - name: rounding
+            options: [ FLOOR, CEIL, ROUND_TIE_DOWN, ROUND_TIE_UP ]
+          - name: unit
+            options: [ YEAR, MONTH, WEEK, DAY, HOUR, MINUTE, SECOND, MILLISECOND, MICROSECOND ]
+          - name: origin
+            options: [ YEAR, MONTH, MONDAY_WEEK, SUNDAY_WEEK, ISO_WEEK,
+                       US_WEEK, DAY, HOUR, MINUTE, SECOND, MILLISECOND ]
+          - name: multiple
+            value: i64
+          - name: timezone
+            description: Timezone string from IANA tzdb.
+            value: string
+        return: timestamp_tz
+      - args:
+          - name: x
+            value: date
+          - name: rounding
+            options: [ FLOOR, CEIL, ROUND_TIE_DOWN, ROUND_TIE_UP ]
+          - name: unit
+            options: [ YEAR, MONTH, WEEK, DAY ]
+          - name: origin
+            options: [ YEAR, MONTH, MONDAY_WEEK, SUNDAY_WEEK, ISO_WEEK, US_WEEK, DAY ]
+          - name: multiple
+            value: i64
+          - name: origin
+            value: date
+        return: date
+      - args:
+          - name: x
+            value: time
+          - name: rounding
+            options: [ FLOOR, CEIL, ROUND_TIE_DOWN, ROUND_TIE_UP ]
+          - name: unit
+            options: [ DAY, HOUR, MINUTE, SECOND, MILLISECOND, MICROSECOND ]
+          - name: origin
+            options: [ DAY, HOUR, MINUTE, SECOND, MILLISECOND ]
+          - name: multiple
+            value: i64
+          - name: origin
+            value: time
+        return: time