Date Functions

Overview

Date functions operate on dates, timestamps, and intervals.

View the list of available window date fields here.

Reference

date_parse
date_format
DateFormatter
elapsed_minutes
elapsedTime
elapsedTime for DateTime
IntervalFormatter
formatInterval
formatIntervalShort
formatSecondOffset
now
precise_now
milliseconds
seconds
to_datetime
today
tomorrow
yesterday
window_length_time
window_length_count
windowStartTime

`now`

now DateTime

Returns the current time as a DateTime object.

Access DateTime object fields using dot notation.

// returns true on Thursdays
now.dayOfWeek == 4

When printed as text, for example with ${now} placeholder, the DateTime object is ISO date with time zone information.

2018-08-17T15:13:16.946Z[Etc/UTC]

Examples:

// returns true on Thursdays at anytime between 15:00 and 16:00 (exclusive)
now.day_of_week == 'Thursday' && now.hourOfDay == 15

// true when current time is between 09:45 and 17:45
now.timeOfDay BETWEEN '09:45' and '17:45'

// returns true if difference between current Unix time (long, milliseconds)
// and create_ms (long, Unix time in milliseconds) exceeds 15 minutes
(now.millis - create_ms) > 15*60000

// returns the same result as above using the elapsedTime function
elapsedTime(create_ms) > 15*60000

// returns the same result as above using the elapsed_minutes function
elapsed_minutes(create_ms) > 15

`precise_now`

precise_now DateTime

Returns the current time as a DateTime object with nanosecond precision.

Examples:

// calculates elapsed time with high precision
precise_now.epochNano - date_parse(properties.write_time, 'yyMMddHHmmssSSSSSS', 'UTC').epochNano

`today`

today DateTime

Returns the current day at midnight, 00:00:00, as a DateTime object.

`tomorrow`

tomorrow DateTime

Returns the following day at midnight, 00:00:00, as a DateTime object.

`yesterday`

yesterday DateTime

Returns the previous day at midnight, 00:00:00, as a DateTime object.

`window_length_time`

window_length_time() long

Returns the length of a time-based window in seconds.

`window_length_count`

window_length_count() long

Returns the length of a count-based window.

`windowStartTime`

windowStartTime() long

Returns time when the first command is received by the window, in Unix time with millisecond precision.

`milliseconds`

milliseconds(string date [,string pattern [,string zone]]) long

Parses the date string date into Unix time in milliseconds according to the specified date pattern and time zone (or offset from UTC).

Returns 0 if date is null or empty.

Available time zones and offsets are listed in time zones.

The default pattern is ISO format yyyy-MM-ddTHH:mm:ss[.S]Z and the default time zone is the server time zone.

Warning

The function raises an error if the time zone or offset from UTC is specified in the date string date and differs from the time zone or offset zone.

Example:

/* Returns true if the difference between the event time and start
time (ISO) retrieved from the property record is greater than 5 minutes. */
command_time.millis - milliseconds(property('docker.container::startedAt')) >  5*60000

`seconds`

seconds(string date [,string pattern [,string zone]]) long

Accepts the same arguments as the milliseconds function with the result in Unix time measured in seconds instead of milliseconds.

`elapsedTime`

elapsedTime(long timestamp) long

elapsedTime(DateTime timestamp) long

elapsedTime(string timestamp) long

Calculates the number of milliseconds between the current time and timestamp specified as Unix time in milliseconds, DateTime object, or date specified in the following format:

yyyy-MM-dd[(T| )[hh:mm:ss[.SSS[Z]]]]

Function returns 0 if date is null or empty.

Example:

/* Assuming current time of 2017-08-15T00:01:30Z, returned elapsed time is 90000 */
elapsedTime("2017-08-15T00:00:00Z")

/* Returns elapsed time in milliseconds since ISO date in tags.last_updated */
elapsedTime(milliseconds(tags.last_updated))

Format the interval in milliseconds with formatInterval or formatintervalshort.

/* Returns interval in short notation, for example 2y 201d */
formatIntervalShort(elapsedTime(milliseconds(tags.last_updated)))

`elapsedTime for DateTime`

elapsedTime(DateTime a, DateTime b) long

Subtracts date a from date b and returns the interval in milliseconds. If one of the dates is null, the function returns Long.MAX_VALUE which is 9223372036854775807.

/* How many milliseconds passed between the time of the command and the time it is added */
elapsedTime(command_time, add_time)

`elapsed_minutes`

elapsed_minutes(long timestamp) long

elapsed_minutes(DateTime timestamp) long

elapsed_minutes(string timestamp) long

Calculates the number of minutes between the current time and timestamp specified as Unix time in milliseconds, DateTime object, or date specified in the following format:

yyyy-MM-dd[(T| )[hh:mm:ss[.SSS[Z]]]]

Function returns 0 if date is null or empty.

Returns the same result as the elapsedTime function divided by 60000.

`date_parse`

date_parse(string date [,string pattern [,string zone]]) DateTime

Parses the input string date into a DateTime object according to the specified date pattern and time zone or offset from UTC.

The default pattern is ISO format yyyy-MM-ddTHH:mm:ss[.S]Z and the default time zone is the server time zone.

Warning

The function raises an error if the time zone (or offset from UTC) is specified in date and differs from the time zone (offset) zone.

Access fields of the DateTime object using dot notation:

date_parse("2018-01-13T16:45:22.303Z").day_of_week
date_parse("2018-01-13T16:45:22.303Z").millis
date_parse("2018-01-13T16:45:22.303Z").next_workday

Examples:

/* Returns true if the specified date is a working day. */
date_parse(property('config::deleted')).is_workday()

/* Uses the server time zone to construct a DateTime object. */
date_parse("31.01.2017 12:36:03.283", "dd.MM.yyyy HH:mm:ss.SSS")

/* Uses the offset specified in the datetime string to construct a DateTime object. */
date_parse("31.01.2017 12:36:03.283 -08:00", "dd.MM.yyyy HH:mm:ss.SSS ZZ")

/* Uses the time zone specified in the datetime string to construct a DateTime object. */
date_parse("31.01.2017 12:36:03.283 Europe/Berlin", "dd.MM.yyyy HH:mm:ss.SSS ZZZ")

/* Constructs a DateTime object from the time zone provided as the third argument. */
date_parse("31.01.2017 12:36:03.283", "dd.MM.yyyy HH:mm:ss.SSS", "Europe/Berlin")

/* Constructs a DateTime object from the UTC offset provided as the third argument. */
date_parse("31.01.2017 12:36:03.283", "dd.MM.yyyy HH:mm:ss.SSS", "+01:00")

/* Time zone (offset) specified in the datetime must be the same as provided in the third argument. */
date_parse("31.01.2017 12:36:03.283 Europe/Berlin", "dd.MM.yyyy HH:mm:ss.SSS ZZZ", "Europe/Berlin")

/* These expressions lead to exceptions. */
date_parse("31.01.2017 12:36:03.283 +01:00", "dd.MM.yyyy HH:mm:ss.SSS ZZ", "Europe/Berlin")
date_parse("31.01.2017 12:36:03.283 Europe/Brussels", "dd.MM.yyyy HH:mm:ss.SSS ZZZ", "Europe/Berlin")

`to_datetime`

to_datetime(long time [, string zone]) DateTime

Returns DateTime object initialized from Unix time in milliseconds time in the server time zone. If the optional time zone argument zone is specified, the DateTime is initialized in the user-defined time zone.

Example:

/* Returns true if the create_ms date is a working day. */
to_datetime(create_ms, 'America/Chicago').is_workday()

`date_format`

date_format(long time | DateTime date
               [, string pattern
                   [, string zone]]) string

Converts timestamp time, specified as Unix time in milliseconds or a DateTime object, to a string according to the specified date pattern and the time zone.

If neither the date pattern nor the time zone are specified, the input time is formatted with the default ISO format in the UTC time zone. If time zone is not specified, the input time t is formatted using pattern in the server time zone.

Examples:

/* Returns current time minus 1 hour formatted as "2018-01-09T15:23:40.000Z" */
date_format(now.millis - 3600000L)

/* Returns command time formatted as "Jan-09 15:23:40.022" in Pacific Standard Time */
date_format(command_time, "MMM-dd HH:mm:ss.SSS", "US/Pacific")

command_time is a DateTime object containing the sample time of the most recently added or removed command.

/* Returns current time formatted as "Jan-09 15:23" in server time zone */
date_format(now, "MMM-dd HH:mm")

/* Returns formatted time string  "2018-01-09 15:23:40.00 Europe/Berlin" */
date_format(milliseconds('2018-01-09T14:23.40Z'), "yyyy-MM-dd HH:mm:ss.SSS ZZZ", "Europe/Berlin")

Related Functions

Related date parsing function: date_parse

`DateFormatter`

DateFormatter(string pattern [, string timezone [, string locale]])

The DateFormatter can be configured once as a variable and re-used in actions to format the dates using the specified pattern, time zone and locale. Locale matching is case-insensitive.

The formatter implements a format() method that format the date argument as a string.

format(DateTime from | long milliseconds)

A convenience method f() accepting the same arguments is provided for brevity.

Example:

// formatter is initialized as variable
df = DateFormatter('yyyy-MMM-dd HH:mm:ss', 'Asia/Seoul', 'KOREAN')

// formatter is used to format dates
df.format(add_time)          ->      2019-4월-12 14:20:00

// format and add backticks for markdown
df = DateFormatter('`HH:mm:ss.SSS`')

`IntervalFormatter`

IntervalFormatter(string pattern)

The IntervalFormatter can be configured once as a variable and re-used in actions to format the duration between two dates using the specified pattern.

Supported patterns:

short
default
milliseconds...years

The formatter implements a format() method that returns the interval between the from and to dates as a string.

format(DateTime from, DateTime to)

A convenience method f() accepting the same arguments is provided for brevity.

Example:

// formatter is initialized as variable
inf = IntervalFormatter('default')

// formatter is used to format dates
inf.format(add_time, command_time)          ->      5s 15ms

`formatInterval`

formatInterval(long interval) string

Converts interval in Unix time measured in milliseconds to a string consisting of non-zero time units, where the unit is year, day, hour, minute, and second.

If the interval is less than one second, the function returns 0s.

Examples:

/* Returns formatted interval: 2y 139d 16h 47m 15s */
formatInterval(75228435000L)

formatInterval(elapsedTime(milliseconds(tags.last_updated)))

`formatIntervalShort`

formatIntervalShort(long interval) string

Converts interval in Unix time measured in milliseconds to a string consisting of up to the two highest subsequent non-zero time units, where the unit is year, day, hour, minute, and second.

If the interval is less than one second, the function returns 0s.

Examples:

/* Returns formatted interval: 2y 139d */
formatIntervalShort(75228435000L)

/* Assuming current time of 2017-08-15T00:01:30Z, returns a short interval of elapsed time: 1m 30s */
formatIntervalShort(elapsedTime("2017-08-15T00:00:00Z"))

`formatSecondOffset`

formatSecondOffset(int interval) string

Converts UTC offset in seconds to time zone pattern ±hh:mm. The input seconds are negative for time zones ahead of UTC, such as Europe/Vienna.

Examples:

/* Returns 00:00 */
formatSecondOffset(0)

/* Returns +02:00 */
formatSecondOffset(-7200)

${formatSecondOffset(column('TMZDIFF'))}

# Date Functions

# Overview

# Reference

# now

# precise_now

# today

# tomorrow

# yesterday

# window_length_time

# window_length_count

# windowStartTime

# milliseconds

# seconds

# elapsedTime

# elapsedTime for DateTime

# elapsed_minutes

# date_parse

# to_datetime

# date_format

# DateFormatter

# IntervalFormatter

# formatInterval

# formatIntervalShort

# formatSecondOffset

Date Functions

Overview

Reference

`now`

`precise_now`

`today`

`tomorrow`

`yesterday`

`window_length_time`

`window_length_count`

`windowStartTime`

`milliseconds`

`seconds`

`elapsedTime`

`elapsedTime for DateTime`

`elapsed_minutes`

`date_parse`

`to_datetime`

`date_format`

`DateFormatter`

`IntervalFormatter`

`formatInterval`

`formatIntervalShort`

`formatSecondOffset`