SurrealDB Docs Logo

Enter a search query

Time Functions

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

Many time functions take an option<datetime> in order to return certain values from a datetime such as its hours, minutes, day of the year, and so in. If no argument is present, the current datetime will be extracted and used. As such, all of the following function calls are valid and will not return an error.

time::hour(d'2024-09-04T00:32:44.107Z'); time::hour(); time::minute(d'2024-09-04T00:32:44.107Z'); time::minute(); time::yday(d'2024-09-04T00:32:44.107Z'); time::yday();
FunctionDescription
time::ceil()Rounds a datetime up to the next largest duration
time::day()Extracts the day as a number from a datetime or current 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 or current datetime
time::max()Finds the most recent datetime in an array
time::micros()Extracts the microseconds as a number from a datatime or current datetime
time::millis()Extracts the milliseconds as a number from a datatime or current datetime
time::min()Finds the least recent datetime in an array
time::minute()Extracts the minutes as a number from a datetime or current datetime
time::month()Extracts the month as a number from a datetime or current datetime
time::nano()Returns the number of nanoseconds since the UNIX epoch until a datetime or current datetime
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 or current 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 or current datetime
time::week()Extracts the week as a number from a datetime or current datetime
time::yday()Extracts the yday as a number from a datetime or current datetime
time::year()Extracts the year as a number from a datetime or current datetime
time::is::leap_year()Checks if given datatime is a leap year
time::from::micros()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()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::ceil

The time::ceil function rounds a datetime up to the next largest duration.

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

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

LET $now = d'2024-08-30T02:22:50.231631Z'; RETURN [ time::ceil($now, 1h), time::ceil($now, 1w) ];
Output
[ d'2024-08-30T03:00:00Z', d'2024-09-05T00:00:00Z' ]

time::day

The time::day function extracts the day as a number from a datetime, or from the current date if no datetime argument is present.

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

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

RETURN time::day(d"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(d"2021-11-01T08:30:17+00:00", 1w); d"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(d"2021-11-01T08:30:17+00:00", "%Y-%m-%d");
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(d"2021-11-01T08:30:17+00:00", "year"); d"2021-01-01T00:00:00Z"

time::hour

The time::hour function extracts the hour as a number from a datetime, or from the current date if no datetime argument is present.

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

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

RETURN time::hour(d"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([ d"1987-06-22T08:30:45Z", d"1988-06-22T08:30:45Z" ]) d"1988-06-22T08:30:45Z"

time::micros

Available since: v1.1.0

The time::micros function extracts the microseconds as a number from a datetime, or from the current date if no datetime argument is present.

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

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

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

time::millis

Available since: v1.1.0

The time::millis function extracts the milliseconds as a number from a datetime, or from the current date if no datetime argument is present.

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

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

RETURN time::millis(d"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([ d"1987-06-22T08:30:45Z", d"1988-06-22T08:30:45Z" ]) d"1987-06-22T08:30:45Z"

time::minute

The time::minute function extracts the minutes as a number from a datetime, or from the current date if no datetime argument is present.

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

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

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

time::month

The time::month function extracts the month as a number from a datetime, or from the current date if no datetime argument is present.

API DEFINITION
time::month(option<datetime>) -> number

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

RETURN time::month(d"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 until a datetime, or the current date if no datetime argument is present.

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

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

RETURN time::nano(d"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(d"2021-11-01T08:30:17+00:00", 1w); d"2021-11-04T00:00:00Z"

time::second

The time::second function extracts the second as a number from a datetime, or from the current date if no datetime argument is present.

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

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

RETURN time::second(d"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 until a certain datetime, or from the current date if no datetime argument is present.

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

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

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

time::wday

The time::wday function extracts the week day as a number from a datetime, or from the current date if no datetime argument is present.

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

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

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

time::week

The time::week function extracts the week as a number from a datetime, or from the current date if no datetime argument is present.

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

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

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

time::yday

The time::yday function extracts the day of the year as a number from a datetime, or from the current date if no datetime argument is present.

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

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

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

time::year

The time::year function extracts the year as a number from a datetime, or from the current date if no datetime argument is present.

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

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

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

time::is::leap_year()

The time::is::leap_year() function Checks if given datatime is a leap year.

API DEFINITION
time::is::leap_year(datetime) -> bool

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

-- Checks with current datatime if none is passed RETURN time::is::leap_year(); RETURN time::is::leap_year(d"1987-06-22T08:30:45Z"); [false] RETURN time::is::leap_year(d"1988-06-22T08:30:45Z"); [true] -- Using function via method chaining RETURN d'2024-09-03T02:33:15.349397Z'.is_leap_year(); [true]

time::from::micros

Available since: v1.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); d"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); d"1970-01-01T00:00:01Z"

time::from::nanos

Available since: v1.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); d"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); d"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); d"1970-01-01T00:16:40Z"


© SurrealDB GitHub Discord Community Cloud Features Releases Install