Date Functions

Overview

Date functions operate on dates, timestamps, and intervals.

Reference

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
// 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

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 pattern and time zone 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-dd'T'HH: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)))

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 pattern and time zone zone or offset from UTC.

The default pattern is ISO format yyyy-MM-dd'T'HH: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:00Z" */
date_format(now.millis - 3600000L)
/* 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

formatInterval

formatInterval(long interval) string

Converts interval in Unix time measured in milliseconds to a formatted interval consisting of non-zero years, days, hours, minutes, and seconds.

Examples:

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

formatIntervalShort

formatIntervalShort(long interval) string

Converts interval measured in milliseconds to a formatted interval consisting of up to the two highest subsequent non-zero time units, where the unit comprises years, days, hours, minutes, and seconds.

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"))