Back to top
Documentation SurrealQL Functions Time functions

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::EPOCH Constant containing the unix epoch 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::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() Calculates a datetimes based on an amount of microseconds since January 1, 1970 0:00:00 UTC.
time::from::millis() Calculates a datetimes based on an amount of milliseconds since January 1, 1970 0:00:00 UTC.
time::from::secs() Calculates a datetimes based on an amount of seconds since January 1, 1970 0:00:00 UTC.
time::from::unix() Calculates a datetimes based on an amount of seconds since January 1, 1970 0:00:00 UTC.

time::day

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

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::epoch

The time::EPOCH constant contains unix epoch timestamp as a datetime.

time::EPOCH -> datetime

The following example shows this constant when used in a RETURN statement:

RETURN time::EPOCH;
'1970-01-01T00:00:00Z'

time::floor

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

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 according to a specific format.

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.

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.

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 minutes as a number from a datetime.

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::min

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

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.

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.

time::month(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::nano function returns a datetime as an integer representing the number of nanoseconds since the UNIX epoch.

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.

time::now() -> datetime

time::round

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

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.

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.

time::timezone() -> string

time::unix

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

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::wday

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

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.

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.

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.

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

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

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 an amount of milliseconds since January 1, 1970 0:00:00 UTC.

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::secs

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

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 an amount of seconds since January 1, 1970 0:00:00 UTC.

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"