Skip to main content
Version: 1.x

Time Functions

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

FunctionDescription
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.0Extracts the microseconds as a number from a datatime
time::millis()Since 1.1.0Extracts 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.0Calculates 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.0Calculates 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"