java.lang.Object
- org.apache.pinot.common.function.scalar.DateTimeFunctions

```
public class DateTimeFunctions
extends Object
```
Inbuilt date time related transform functions NOTE: toEpochXXXBucket methods are only needed to convert from TimeFieldSpec to DateTimeFieldSpec, to maintain the backward compatibility. Practically, we should only need the toEpochXXXRounded methods. Use of toEpochXXXBucket bucket functions is discouraged unless you know what you are doing - (e.g. 5-minutes-since-epoch does not make sense to someone looking at the timestamp, or writing queries. instead, Millis-since-epoch rounded to 5 minutes makes a lot more sense) An example timeFieldSpec that needs the bucketing function: "timeFieldSpec": { "incomingGranularitySpec": { "name": "incoming", "dataType": "LONG", "timeType": "MILLISECONDS" }, "outgoingGranularitySpec": { "name": "outgoing", "dataType": "LONG", "timeType": "MINUTES", "timeSize": 5 } } An equivalent dateTimeFieldSpec is "dateTimeFieldSpecs": [{ "name": "outgoing", "dataType": "LONG", "format": "5:MINUTES:EPOCH", "granularity": "5:MINUTES", "transformFunction": "toEpochMinutesBucket(incoming, 5)" }]

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method	Description
`static long`	`ago(String periodString)`	Return time as epoch millis before the given period (in ISO-8601 duration format).
`static long`	`dateTrunc(String unit, long timeValue)`	The sql compatible date_trunc function for epoch time.
`static long`	`dateTrunc(String unit, long timeValue, String inputTimeUnitStr)`	The sql compatible date_trunc function for epoch time.
`static long`	`dateTrunc(String unit, long timeValue, String inputTimeUnitStr, String timeZone)`	The sql compatible date_trunc function for epoch time.
`static long`	`dateTrunc(String unit, long timeValue, String inputTimeUnitStr, String timeZone, String outputTimeUnitStr)`	The sql compatible date_trunc function for epoch time.
`static int`	`day(long millis)`	Returns the day of the month from the given epoch millis in UTC timezone.
`static int`	`day(long millis, String timezoneId)`	Returns the day of the month from the given epoch millis and timezone id.
`static int`	`dayOfMonth(long millis)`	An alias for day().
`static int`	`dayOfMonth(long millis, String timezoneId)`	An alias for day().
`static int`	`dayOfWeek(long millis)`	Returns the day of the week from the given epoch millis in UTC timezone.
`static int`	`dayOfWeek(long millis, String timezoneId)`	Returns the day of the week from the given epoch millis and timezone id.
`static int`	`dayOfYear(long millis)`	Returns the day of the year from the given epoch millis in UTC timezone.
`static int`	`dayOfYear(long millis, String timezoneId)`	Returns the day of the year from the given epoch millis and timezone id.
`static int`	`dow(long millis)`	An alias for dayOfWeek().
`static int`	`dow(long millis, String timezoneId)`	An alias for dayOfWeek().
`static int`	`doy(long millis)`	An alias for dayOfYear().
`static int`	`doy(long millis, String timezoneId)`	An alias for dayOfYear().
`static long`	`fromDateTime(String dateTimeString, String pattern)`	Converts DateTime string represented by pattern to epoch millis
`static long`	`fromDateTime(String dateTimeString, String pattern, String timeZoneId)`	Converts DateTime string represented by pattern to epoch millis
`static long`	`fromEpochDays(long days)`	Converts epoch days to epoch millis
`static long`	`fromEpochDaysBucket(long days, long bucket)`	Converts nDaysSinceEpoch (days that have been divided by a bucket), to epoch millis
`static long`	`fromEpochHours(long hours)`	Converts epoch hours to epoch millis
`static long`	`fromEpochHoursBucket(long hours, long bucket)`	Converts nHoursSinceEpoch (hours that have been divided by a bucket), to epoch millis
`static long`	`fromEpochMinutes(long minutes)`	Converts epoch minutes to epoch millis
`static long`	`fromEpochMinutesBucket(long minutes, long bucket)`	Converts nMinutesSinceEpoch (minutes that have been divided by a bucket), to epoch millis
`static long`	`fromEpochSeconds(long seconds)`	Converts epoch seconds to epoch millis
`static long`	`fromEpochSecondsBucket(long seconds, long bucket)`	Converts nSecondsSinceEpoch (seconds that have been divided by a bucket), to epoch millis
`static long`	`fromTimestamp(Timestamp timestamp)`	Converts Timestamp to epoch millis
`static int`	`hour(long millis)`	Returns the hour of the day from the given epoch millis in UTC timezone.
`static int`	`hour(long millis, String timezoneId)`	Returns the hour of the day from the given epoch millis and timezone id.
`static int`	`millisecond(long millis)`	Returns the millisecond of the second from the given epoch millis in UTC timezone.
`static int`	`millisecond(long millis, String timezoneId)`	Returns the millisecond of the second from the given epoch millis and timezone id.
`static int`	`minute(long millis)`	Returns the minute of the hour from the given epoch millis in UTC timezone.
`static int`	`minute(long millis, String timezoneId)`	Returns the minute of the hour from the given epoch millis and timezone id.
`static int`	`month(long millis)`	Returns the month of the year from the given epoch millis in UTC timezone.
`static int`	`month(long millis, String timezoneId)`	Returns the month of the year from the given epoch millis and timezone id.
`static long`	`now()`	Return current time as epoch millis TODO: Consider changing the return type to Timestamp
`static int`	`quarter(long millis)`	Returns the quarter of the year from the given epoch millis in UTC timezone.
`static int`	`quarter(long millis, String timezoneId)`	Returns the quarter of the year from the given epoch millis and timezone id.
`static long`	`round(long timeValue, long roundToNearest)`	Round the given time value to nearest multiple
`static int`	`second(long millis)`	Returns the second of the minute from the given epoch millis in UTC timezone.
`static int`	`second(long millis, String timezoneId)`	Returns the second of the minute from the given epoch millis and timezone id.
`static long`	`timestampAdd(String unit, long interval, long timestamp)`	Add a time period to the provided timestamp.
`static long`	`timestampDiff(String unit, long timestamp1, long timestamp2)`	Get difference between two timestamps and return the result in the specified timeunit.
`static int`	`timezoneHour(String timezoneId)`	Returns the hour of the time zone offset.
`static int`	`timezoneMinute(String timezoneId)`	Returns the minute of the time zone offset.
`static String`	`toDateTime(long millis, String pattern)`	Converts epoch millis to DateTime string represented by pattern
`static String`	`toDateTime(long millis, String pattern, String timezoneId)`	Converts epoch millis to DateTime string represented by pattern and the time zone id.
`static long`	`toEpochDays(long millis)`	Convert epoch millis to epoch days
`static long`	`toEpochDaysBucket(long millis, long bucket)`	Convert epoch millis to epoch days, divided by given bucket, to get nDaysSinceEpoch
`static long`	`toEpochDaysRounded(long millis, long roundToNearest)`	Convert epoch millis to epoch days, round to nearest rounding bucket
`static long`	`toEpochHours(long millis)`	Convert epoch millis to epoch hours
`static long`	`toEpochHoursBucket(long millis, long bucket)`	Convert epoch millis to epoch hours, divided by given bucket, to get nHoursSinceEpoch
`static long`	`toEpochHoursRounded(long millis, long roundToNearest)`	Convert epoch millis to epoch hours, round to nearest rounding bucket
`static long`	`toEpochMinutes(long millis)`	Convert epoch millis to epoch minutes
`static long`	`toEpochMinutesBucket(long millis, long bucket)`	Convert epoch millis to epoch minutes, divided by given bucket, to get nMinutesSinceEpoch
`static long`	`toEpochMinutesRounded(long millis, long roundToNearest)`	Convert epoch millis to epoch minutes, round to nearest rounding bucket
`static long`	`toEpochSeconds(long millis)`	Convert epoch millis to epoch seconds
`static long`	`toEpochSecondsBucket(long millis, long bucket)`	Convert epoch millis to epoch seconds, divided by given bucket, to get nSecondsSinceEpoch
`static long`	`toEpochSecondsRounded(long millis, long roundToNearest)`	Convert epoch millis to epoch seconds, round to nearest rounding bucket
`static Timestamp`	`toTimestamp(long millis)`	Converts epoch millis to Timestamp
`static int`	`week(long millis)`	Returns the ISO week of the year from the given epoch millis in UTC timezone.The value ranges from 1 to 53.
`static int`	`week(long millis, String timezoneId)`	Returns the ISO week of the year from the given epoch millis and timezone id.
`static int`	`weekOfYear(long millis)`	An alias for week().
`static int`	`weekOfYear(long millis, String timezoneId)`	An alias for week().
`static int`	`year(long millis)`	Returns the year from the given epoch millis in UTC timezone.
`static int`	`year(long millis, String timezoneId)`	Returns the year from the given epoch millis and timezone id.
`static int`	`yearOfWeek(long millis)`	Returns the year of the ISO week from the given epoch millis in UTC timezone.
`static int`	`yearOfWeek(long millis, String timezoneId)`	Returns the year of the ISO week from the given epoch millis and timezone id.
`static int`	`yow(long millis)`	An alias for yearOfWeek().
`static int`	`yow(long millis, String timezoneId)`	An alias for yearOfWeek().

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - toEpochSeconds
```
public static long toEpochSeconds(long millis)
```
    Convert epoch millis to epoch seconds
  - toEpochMinutes
```
public static long toEpochMinutes(long millis)
```
    Convert epoch millis to epoch minutes
  - toEpochHours
```
public static long toEpochHours(long millis)
```
    Convert epoch millis to epoch hours
  - toEpochDays
```
public static long toEpochDays(long millis)
```
    Convert epoch millis to epoch days
  - toEpochSecondsRounded
```
public static long toEpochSecondsRounded(long millis,
                                         long roundToNearest)
```
    Convert epoch millis to epoch seconds, round to nearest rounding bucket
  - toEpochMinutesRounded
```
public static long toEpochMinutesRounded(long millis,
                                         long roundToNearest)
```
    Convert epoch millis to epoch minutes, round to nearest rounding bucket
  - toEpochHoursRounded
```
public static long toEpochHoursRounded(long millis,
                                       long roundToNearest)
```
    Convert epoch millis to epoch hours, round to nearest rounding bucket
  - toEpochDaysRounded
```
public static long toEpochDaysRounded(long millis,
                                      long roundToNearest)
```
    Convert epoch millis to epoch days, round to nearest rounding bucket
  - toEpochSecondsBucket
```
public static long toEpochSecondsBucket(long millis,
                                        long bucket)
```
    Convert epoch millis to epoch seconds, divided by given bucket, to get nSecondsSinceEpoch
  - toEpochMinutesBucket
```
public static long toEpochMinutesBucket(long millis,
                                        long bucket)
```
    Convert epoch millis to epoch minutes, divided by given bucket, to get nMinutesSinceEpoch
  - toEpochHoursBucket
```
public static long toEpochHoursBucket(long millis,
                                      long bucket)
```
    Convert epoch millis to epoch hours, divided by given bucket, to get nHoursSinceEpoch
  - toEpochDaysBucket
```
public static long toEpochDaysBucket(long millis,
                                     long bucket)
```
    Convert epoch millis to epoch days, divided by given bucket, to get nDaysSinceEpoch
  - fromEpochSeconds
```
public static long fromEpochSeconds(long seconds)
```
    Converts epoch seconds to epoch millis
  - fromEpochMinutes
```
public static long fromEpochMinutes(long minutes)
```
    Converts epoch minutes to epoch millis
  - fromEpochHours
```
public static long fromEpochHours(long hours)
```
    Converts epoch hours to epoch millis
  - fromEpochDays
```
public static long fromEpochDays(long days)
```
    Converts epoch days to epoch millis
  - fromEpochSecondsBucket
```
public static long fromEpochSecondsBucket(long seconds,
                                          long bucket)
```
    Converts nSecondsSinceEpoch (seconds that have been divided by a bucket), to epoch millis
  - fromEpochMinutesBucket
```
public static long fromEpochMinutesBucket(long minutes,
                                          long bucket)
```
    Converts nMinutesSinceEpoch (minutes that have been divided by a bucket), to epoch millis
  - fromEpochHoursBucket
```
public static long fromEpochHoursBucket(long hours,
                                        long bucket)
```
    Converts nHoursSinceEpoch (hours that have been divided by a bucket), to epoch millis
  - fromEpochDaysBucket
```
public static long fromEpochDaysBucket(long days,
                                       long bucket)
```
    Converts nDaysSinceEpoch (days that have been divided by a bucket), to epoch millis
  - toTimestamp
```
public static Timestamp toTimestamp(long millis)
```
    Converts epoch millis to Timestamp
  - fromTimestamp
```
public static long fromTimestamp(Timestamp timestamp)
```
    Converts Timestamp to epoch millis
  - toDateTime
```
public static String toDateTime(long millis,
                                String pattern)
```
    Converts epoch millis to DateTime string represented by pattern
  - toDateTime
```
public static String toDateTime(long millis,
                                String pattern,
                                String timezoneId)
```
    Converts epoch millis to DateTime string represented by pattern and the time zone id.
  - fromDateTime
```
public static long fromDateTime(String dateTimeString,
                                String pattern)
```
    Converts DateTime string represented by pattern to epoch millis
  - fromDateTime
```
public static long fromDateTime(String dateTimeString,
                                String pattern,
                                String timeZoneId)
```
    Converts DateTime string represented by pattern to epoch millis
  - round
```
public static long round(long timeValue,
                         long roundToNearest)
```
    Round the given time value to nearest multiple
    
    Returns:
    
    the original value but rounded to the nearest multiple of @param roundToNearest
  - now
```
public static long now()
```
    Return current time as epoch millis TODO: Consider changing the return type to Timestamp
  - ago
```
public static long ago(String periodString)
```
    Return time as epoch millis before the given period (in ISO-8601 duration format). Examples: "PT20.345S" -- parses as "20.345 seconds" "PT15M" -- parses as "15 minutes" (where a minute is 60 seconds) "PT10H" -- parses as "10 hours" (where an hour is 3600 seconds) "P2D" -- parses as "2 days" (where a day is 24 hours or 86400 seconds) "P2DT3H4M" -- parses as "2 days, 3 hours and 4 minutes" "P-6H3M" -- parses as "-6 hours and +3 minutes" "-P6H3M" -- parses as "-6 hours and -3 minutes" "-P-6H+3M" -- parses as "+6 hours and -3 minutes"
  - timezoneHour
```
public static int timezoneHour(String timezoneId)
```
    Returns the hour of the time zone offset.
  - timezoneMinute
```
public static int timezoneMinute(String timezoneId)
```
    Returns the minute of the time zone offset.
  - year
```
public static int year(long millis)
```
    Returns the year from the given epoch millis in UTC timezone.
  - year
```
public static int year(long millis,
                       String timezoneId)
```
    Returns the year from the given epoch millis and timezone id.
  - yearOfWeek
```
public static int yearOfWeek(long millis)
```
    Returns the year of the ISO week from the given epoch millis in UTC timezone.
  - yearOfWeek
```
public static int yearOfWeek(long millis,
                             String timezoneId)
```
    Returns the year of the ISO week from the given epoch millis and timezone id.
  - yow
```
public static int yow(long millis)
```
    An alias for yearOfWeek().
  - yow
```
public static int yow(long millis,
                      String timezoneId)
```
    An alias for yearOfWeek().
  - quarter
```
public static int quarter(long millis)
```
    Returns the quarter of the year from the given epoch millis in UTC timezone. The value ranges from 1 to 4.
  - quarter
```
public static int quarter(long millis,
                          String timezoneId)
```
    Returns the quarter of the year from the given epoch millis and timezone id. The value ranges from 1 to 4.
  - month
```
public static int month(long millis)
```
    Returns the month of the year from the given epoch millis in UTC timezone. The value ranges from 1 to 12.
  - month
```
public static int month(long millis,
                        String timezoneId)
```
    Returns the month of the year from the given epoch millis and timezone id. The value ranges from 1 to 12.
  - week
```
public static int week(long millis)
```
    Returns the ISO week of the year from the given epoch millis in UTC timezone.The value ranges from 1 to 53.
  - week
```
public static int week(long millis,
                       String timezoneId)
```
    Returns the ISO week of the year from the given epoch millis and timezone id. The value ranges from 1 to 53.
  - weekOfYear
```
public static int weekOfYear(long millis)
```
    An alias for week().
  - weekOfYear
```
public static int weekOfYear(long millis,
                             String timezoneId)
```
    An alias for week().
  - dayOfYear
```
public static int dayOfYear(long millis)
```
    Returns the day of the year from the given epoch millis in UTC timezone. The value ranges from 1 to 366.
  - dayOfYear
```
public static int dayOfYear(long millis,
                            String timezoneId)
```
    Returns the day of the year from the given epoch millis and timezone id. The value ranges from 1 to 366.
  - doy
```
public static int doy(long millis)
```
    An alias for dayOfYear().
  - doy
```
public static int doy(long millis,
                      String timezoneId)
```
    An alias for dayOfYear().
  - day
```
public static int day(long millis)
```
    Returns the day of the month from the given epoch millis in UTC timezone. The value ranges from 1 to 31.
  - day
```
public static int day(long millis,
                      String timezoneId)
```
    Returns the day of the month from the given epoch millis and timezone id. The value ranges from 1 to 31.
  - dayOfMonth
```
public static int dayOfMonth(long millis)
```
    An alias for day().
  - dayOfMonth
```
public static int dayOfMonth(long millis,
                             String timezoneId)
```
    An alias for day().
  - dayOfWeek
```
public static int dayOfWeek(long millis)
```
    Returns the day of the week from the given epoch millis in UTC timezone. The value ranges from 1 (Monday) to 7 (Sunday).
  - dayOfWeek
```
public static int dayOfWeek(long millis,
                            String timezoneId)
```
    Returns the day of the week from the given epoch millis and timezone id. The value ranges from 1 (Monday) to 7 (Sunday).
  - dow
```
public static int dow(long millis)
```
    An alias for dayOfWeek().
  - dow
```
public static int dow(long millis,
                      String timezoneId)
```
    An alias for dayOfWeek().
  - hour
```
public static int hour(long millis)
```
    Returns the hour of the day from the given epoch millis in UTC timezone. The value ranges from 0 to 23.
  - hour
```
public static int hour(long millis,
                       String timezoneId)
```
    Returns the hour of the day from the given epoch millis and timezone id. The value ranges from 0 to 23.
  - minute
```
public static int minute(long millis)
```
    Returns the minute of the hour from the given epoch millis in UTC timezone. The value ranges from 0 to 59.
  - minute
```
public static int minute(long millis,
                         String timezoneId)
```
    Returns the minute of the hour from the given epoch millis and timezone id. The value ranges from 0 to 59.
  - second
```
public static int second(long millis)
```
    Returns the second of the minute from the given epoch millis in UTC timezone. The value ranges from 0 to 59.
  - second
```
public static int second(long millis,
                         String timezoneId)
```
    Returns the second of the minute from the given epoch millis and timezone id. The value ranges from 0 to 59.
  - millisecond
```
public static int millisecond(long millis)
```
    Returns the millisecond of the second from the given epoch millis in UTC timezone. The value ranges from 0 to 999.
  - millisecond
```
public static int millisecond(long millis,
                              String timezoneId)
```
    Returns the millisecond of the second from the given epoch millis and timezone id. The value ranges from 0 to 999.
  - dateTrunc
```
public static long dateTrunc(String unit,
                             long timeValue)
```
    The sql compatible date_trunc function for epoch time.
    
    Parameters:
    
    unit - truncate to unit (millisecond, second, minute, hour, day, week, month, quarter, year)
    
    timeValue - value to truncate
    
    Returns:
    
    truncated timeValue in TimeUnit.MILLISECONDS
  - dateTrunc
```
public static long dateTrunc(String unit,
                             long timeValue,
                             String inputTimeUnitStr)
```
    The sql compatible date_trunc function for epoch time.
    
    Parameters:
    
    unit - truncate to unit (millisecond, second, minute, hour, day, week, month, quarter, year)
    
    timeValue - value to truncate
    
    inputTimeUnitStr - TimeUnit of value, expressed in Java's joda TimeUnit
    
    Returns:
    
    truncated timeValue in same TimeUnit as the input
  - dateTrunc
```
public static long dateTrunc(String unit,
                             long timeValue,
                             String inputTimeUnitStr,
                             String timeZone)
```
    The sql compatible date_trunc function for epoch time.
    
    Parameters:
    
    unit - truncate to unit (millisecond, second, minute, hour, day, week, month, quarter, year)
    
    timeValue - value to truncate
    
    inputTimeUnitStr - TimeUnit of value, expressed in Java's joda TimeUnit
    
    timeZone - timezone of the input
    
    Returns:
    
    truncated timeValue in same TimeUnit as the input
  - dateTrunc
```
public static long dateTrunc(String unit,
                             long timeValue,
                             String inputTimeUnitStr,
                             String timeZone,
                             String outputTimeUnitStr)
```
    The sql compatible date_trunc function for epoch time.
    
    Parameters:
    
    unit - truncate to unit (millisecond, second, minute, hour, day, week, month, quarter, year)
    
    timeValue - value to truncate
    
    inputTimeUnitStr - TimeUnit of value, expressed in Java's joda TimeUnit
    
    timeZone - timezone of the input
    
    outputTimeUnitStr - TimeUnit to convert the output to
    
    Returns:
    
    truncated timeValue
  - timestampAdd
```
public static long timestampAdd(String unit,
                                long interval,
                                long timestamp)
```
    Add a time period to the provided timestamp. e.g. timestampAdd('days', 10, NOW()) will add 10 days to the current timestamp and return the value
    
    Parameters:
    
    unit - the timeunit of the period to add. e.g. milliseconds, seconds, days, year
    
    interval - value of the period to add.
    
    timestamp -
    
    Returns:
  - timestampDiff
```
public static long timestampDiff(String unit,
                                 long timestamp1,
                                 long timestamp2)
```
    Get difference between two timestamps and return the result in the specified timeunit. e.g. timestampDiff('days', ago('10D'), ago('2D')) will return 8 i.e. 8 days
    
    Parameters:
    
    unit -
    
    timestamp1 -
    
    timestamp2 -
    
    Returns:

Class DateTimeFunctions

Method Summary

Methods inherited from class java.lang.Object

Method Detail

toEpochSeconds

toEpochMinutes

toEpochHours

toEpochDays

toEpochSecondsRounded

toEpochMinutesRounded

toEpochHoursRounded

toEpochDaysRounded

toEpochSecondsBucket

toEpochMinutesBucket

toEpochHoursBucket

toEpochDaysBucket

fromEpochSeconds

fromEpochMinutes

fromEpochHours

fromEpochDays

fromEpochSecondsBucket

fromEpochMinutesBucket

fromEpochHoursBucket

fromEpochDaysBucket

toTimestamp

fromTimestamp

toDateTime

toDateTime

fromDateTime

fromDateTime

round

now

ago

timezoneHour

timezoneMinute

year

year

yearOfWeek

yearOfWeek

yow

yow

quarter

quarter

month

month

week

week

weekOfYear

weekOfYear

dayOfYear

dayOfYear

doy

doy

day

day

dayOfMonth

dayOfMonth

dayOfWeek

dayOfWeek

dow

dow

hour

hour

minute

minute

second

second

millisecond

millisecond

dateTrunc

dateTrunc

dateTrunc

dateTrunc

timestampAdd

timestampDiff