Time Functions

These functions can be used when working with and manipulating datetime values.

Function	Description
`time::day()`	Extracts the day as a number from a datetime
`time::floor()`	Rounds a datetime down by a specific duration
`time::format()`	Outputs a datetime according to a specific format
`time::group()`	Groups a datetime by a particular time interval
`time::hour()`	Extracts the hour as a number from a datetime
`time::max()`	Finds the most recent datetime in an array
`time::micros()`Since 1.1.0	Extracts the microseconds as a number from a datatime
`time::millis()`Since 1.1.0	Extracts the milliseconds as a number from a datatime
`time::min()`	Finds the least recent datetime in an array
`time::minute()`	Extracts the minutes as a number from a datetime
`time::month()`	Extracts the month as a number from a datetime
`time::nano()`	Returns the number of nanoseconds since the UNIX epoch
`time::now()`	Returns the current datetime
`time::round()`	Rounds a datetime to the nearest multiple of a specific duration
`time::second()`	Extracts the second as a number from a datetime
`time::timezone()`	Returns the current local timezone offset in hours
`time::unix()`	Returns the number of seconds since the UNIX epoch
`time::wday()`	Extracts the week day as a number from a datetime
`time::week()`	Extracts the week as a number from a datetime
`time::yday()`	Extracts the yday as a number from a datetime
`time::year()`	Extracts the year as a number from a datetime
`time::from::micros()`Since 1.1.0	Calculates a datetime based on the microseconds since January 1, 1970 0:00:00 UTC.
`time::from::millis()`	Calculates a datetime based on the milliseconds since January 1, 1970 0:00:00 UTC.
`time::from::nanos()`Since 1.1.0	Calculates a datetime based on the nanoseconds since January 1, 1970 0:00:00 UTC.
`time::from::secs()`	Calculates a datetime based on the seconds since January 1, 1970 0:00:00 UTC.
`time::from::unix()`	Calculates a datetime based on the seconds since January 1, 1970 0:00:00 UTC.

`time::day`

The time::day function extracts the day as a number from a datetime.

API DEFINITION
time::day(datetime) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::day("2021-11-01T08:30:17+00:00");

1

`time::floor`

The time::floor function rounds a datetime down by a specific duration.

API DEFINITION
time::floor(datetime, duration) -> datetime

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::floor("2021-11-01T08:30:17+00:00", 1w);

"2021-10-28T00:00:00Z"

`time::format`

The time::format function outputs a datetime as a string according to a specific format.

API DEFINITION
time::format(datetime, string) -> string

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::format("2021-11-01T08:30:17+00:00", "%Y-%m-%d");

"2021-11-01"

View all format options

`time::group`

The time::group function reduces and rounds a datetime down to a particular time interval. The second argument must be a string, and can be one of the following values: year, month, day, hour, minute, second.

API DEFINITION
time::group(datetime, string) -> datetime

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::group("2021-11-01T08:30:17+00:00", "year");

"2021-01-01T00:00:00Z"

`time::hour`

The time::hour function extracts the hour as a number from a datetime.

API DEFINITION
time::hour(datetime) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::hour("2021-11-01T08:30:17+00:00");

8

`time::max`

The time::max function extracts the maximum as a number from a datetime.

API DEFINITION
time::max(array) -> datetime

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::max([ "1987-06-22T08:30:45Z", "1988-06-22T08:30:45Z" ])

"1988-06-22T08:30:45Z"

`time::micros` Since 1.1.0

The time::micros function extracts the microseconds as a number from a datetime.

API DEFINITION
time::micros(datetime) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::micros("1987-06-22T08:30:45Z");

551349045000000

`time::millis` Since 1.1.0

The time::millis function extracts the milliseconds as a number from a datetime.

API DEFINITION
time::millis(datetime) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::millis("1987-06-22T08:30:45Z");

551349045000

`time::min`

The time::min function extracts the minimum as a number from a datetime.

API DEFINITION
time::min(array) -> datetime

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::min([ "1987-06-22T08:30:45Z", "1988-06-22T08:30:45Z" ])

"1987-06-22T08:30:45Z"

`time::minute`

The time::minute function extracts the minutes as a number from a datetime.

API DEFINITION
time::minute(datetime) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::minute("2021-11-01T08:30:17+00:00");

30

`time::month`

The time::month function extracts the month as a number from a datetime.

API DEFINITION
time::minute(datetime) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::month("2021-11-01T08:30:17+00:00");

11

`time::nano`

The time::nanofunction returns a datetime as an integer representing the number of nanoseconds since the UNIX epoch.

API DEFINITION
time::nano(datetime) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::nano("2021-11-01T08:30:17+00:00");

1635755417000000000

`time::now`

The time::now function returns the current datetime as an ISO8601 timestamp.

API DEFINITION
time::now() -> datetime

`time::round`

The time::round function rounds a datetime up by a specific duration.

API DEFINITION
time::round(datetime, duration) -> datetime

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::round("2021-11-01T08:30:17+00:00", 1w);

"2021-11-04T00:00:00Z"

`time::second`

The time::second function extracts the second as a number from a datetime.

API DEFINITION
time::second(datetime) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::second("2021-11-01T08:30:17+00:00");

17

`time::timezone`

The time::timezone function returns the current local timezone offset in hours.

API DEFINITION
time::timezone() -> string

`time::unix`

The time::unix function returns a datetime as an integer representing the number of seconds since the UNIX epoch.

API DEFINITION
time::unix(datetime) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::unix("2021-11-01T08:30:17+00:00");

1635755417

`time::wday`

The time::wday function extracts the week day as a number from a datetime.

API DEFINITION
time::wday(datetime) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::wday("2021-11-01T08:30:17+00:00");

1

`time::week`

The time::week function extracts the week as a number from a datetime.

API DEFINITION
time::week(datetime) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::week("2021-11-01T08:30:17+00:00");

44

`time::yday`

The time::yday function extracts the yday as a number from a datetime.

API DEFINITION
time::yday(datetime) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::yday("2021-11-01T08:30:17+00:00");

305

`time::year`

The time::year function extracts the year as a number from a datetime.

API DEFINITION
time::year(datetime) -> number

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::year("2021-11-01T08:30:17+00:00");

2021

`time::from::micros` Since 1.1.0

The time::from::micros function calculates a datetime based on the microseconds since January 1, 1970 0:00:00 UTC.

API DEFINITION
time::from::micros(number) -> datetime

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::from::micros(1000000);

"1970-01-01T00:00:01Z"

`time::from::millis`

The time::from::millis function calculates a datetime based on the milliseconds since January 1, 1970 0:00:00 UTC.

API DEFINITION
time::from::millis(number) -> datetime

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::from::millis(1000);

"1970-01-01T00:00:01Z"

`time::from::nanos` Since 1.1.0

The time::from::nanos function calculates a datetime based on the nanoseconds since January 1, 1970 0:00:00 UTC.

API DEFINITION
time::from::nanos(number) -> datetime

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::from::nanos(1000000);

'1970-01-01T00:00:00.001Z'

`time::from::secs`

The time::from::secs function calculates a datetime based on the seconds since January 1, 1970 0:00:00 UTC.

API DEFINITION
time::from::secs(number) -> datetime

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::from::secs(1000);

"1970-01-01T00:16:40Z"

`time::from::unix`

The time::from::unix function calculates a datetime based on the seconds since January 1, 1970 0:00:00 UTC.

API DEFINITION
time::from::unix(number) -> datetime

The following example shows this function, and its output, when used in a RETURN statement:

RETURN time::from::unix(1000);

"1970-01-01T00:16:40Z"

Time Functions

time::day​

time::floor​

time::format​

time::group​

time::hour​

time::max​

time::micros Since 1.1.0​

time::millis Since 1.1.0​

time::min​

time::minute​

time::month​

time::nano​

time::now​

time::round​

time::second​

time::timezone​

time::unix​

time::wday​

time::week​

time::yday​

time::year​

time::from::micros Since 1.1.0​

time::from::millis​

time::from::nanos Since 1.1.0​

time::from::secs​

time::from::unix​

`time::day`

`time::floor`

`time::format`

`time::group`

`time::hour`

`time::max`

`time::micros` Since 1.1.0

`time::millis` Since 1.1.0

`time::min`

`time::minute`

`time::month`

`time::nano`

`time::now`

`time::round`

`time::second`

`time::timezone`

`time::unix`

`time::wday`

`time::week`

`time::yday`

`time::year`

`time::from::micros` Since 1.1.0

`time::from::millis`

`time::from::nanos` Since 1.1.0

`time::from::secs`

`time::from::unix`