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::floor() Rounds a datetime down by a specific duration
time::group() Groups a datetime by a particular time interval
time::hour() Extracts the hour as a number from a datetime
time::mins() 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 up by a specific duration
time::secs() Extracts the secs as a number from a datetime
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::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 select statement:

SELECT * FROM time::day("2021-11-01T08:30:17+00:00");
1

If the argument is not a datetime, then an EMPTY value will be returned:

SELECT * FROM time::day(12345);
null

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 select statement:

SELECT * FROM time::floor("2021-11-01T08:30:17+00:00", 1w);
"2021-10-28T00:00:00Z"

If the first argument is not a datetime, then an EMPTY value will be returned:

SELECT * FROM time::floor(12345, 1w);
null

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 select statement:

SELECT * FROM time::group("2021-11-01T08:30:17+00:00", "year");
"2021-01-01T00:00:00Z"

If the first argument is not a datetime, then an EMPTY value will be returned:

SELECT * FROM time::group(12345, "week");
null

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 select statement:

SELECT * FROM time::hour("2021-11-01T08:30:17+00:00");
8

If the argument is not a datetime, then an EMPTY value will be returned:

SELECT * FROM time::hour(12345);
null

time::mins

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

time::mins(datetime) -> number

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

SELECT * FROM time::mins("2021-11-01T08:30:17+00:00");
30

If the argument is not a datetime, then an EMPTY value will be returned:

SELECT * FROM time::mins(12345);
null

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 select statement:

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

If the argument is not a datetime, then an EMPTY value will be returned:

SELECT * FROM time::month(12345);
null

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 select statement:

SELECT * FROM time::nano("2021-11-01T08:30:17+00:00");
1635755417000000000

If the argument is not a datetime, then an EMPTY value will be returned:

SELECT * FROM time::nano(12345);
null

time::now

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

time::now() -> datetime

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

SELECT * FROM time::now();
"2022-04-27T19:27:09.232928Z"

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 select statement:

SELECT * FROM time::round("2021-11-01T08:30:17+00:00", 1w);
"2021-11-04T00:00:00Z"

If the first argument is not a datetime, then an EMPTY value will be returned:

SELECT * FROM time::round(12345, 1w);
null

time::secs

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

time::secs(datetime) -> number

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

SELECT * FROM time::secs("2021-11-01T08:30:17+00:00");
17

If the argument is not a datetime, then an EMPTY value will be returned:

SELECT * FROM time::secs(12345);
null

time::unix

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

time::unix(datetime) -> number

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

SELECT * FROM time::unix("2021-11-01T08:30:17+00:00");
1635755417

If the argument is not a datetime, then an EMPTY value will be returned:

SELECT * FROM time::unix(12345);
null

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 select statement:

SELECT * FROM time::wday("2021-11-01T08:30:17+00:00");
1

If the argument is not a datetime, then an EMPTY value will be returned:

SELECT * FROM time::wday(12345);
null

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 select statement:

SELECT * FROM time::week("2021-11-01T08:30:17+00:00");
44

If the argument is not a datetime, then an EMPTY value will be returned:

SELECT * FROM time::week(12345);
null

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 select statement:

SELECT * FROM time::yday("2021-11-01T08:30:17+00:00");
305

If the argument is not a datetime, then an EMPTY value will be returned:

SELECT * FROM time::yday(12345);
null

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 select statement:

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

If the argument is not a datetime, then an EMPTY value will be returned:

SELECT * FROM time::year(12345);
null