diff --git a/extensions/functions_datetime.yaml b/extensions/functions_datetime.yaml index cd2867f29..4444c9b7a 100644 --- a/extensions/functions_datetime.yaml +++ b/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