Time

This page contains built-in functions and constants for working with and manipulating datetime values. From SurrealDB 4.0, most of them also work with the date, time and timestamp types, as described in Dates, times and timestamps.

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 on. 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();

Dates, times and timestamps

From SurrealDB 4.0, most of these functions also take a date, time or timestamp. A function that reads a part of the calendar takes a value that has a date, and a function that reads a part of the clock takes a value that has a time of day. A function that changes a value returns the same type that it was given.

A function given a date must give a whole date back, so a result that is not midnight is an error rather than a value that loses its time. Cast the date to a timestamp first to keep the time:

time::set_year(pd'2026-10-27', 2030);
//- pd'2030-10-27'

time::set_hour(pd'2026-10-27', 3);
//- 'Incorrect arguments for function time::set_hour(). The result is not a whole date, so the argument must be cast to a timestamp first.'

time::set_hour(<timestamp> pd'2026-10-27', 3);
//- ts'2026-10-27T03:00:00'

A value of the wrong type is refused with the types the function accepts:

time::hour(pd'2026-10-27');
//- 'Incorrect arguments for function time::hour(). The argument must be a time, timestamp or datetime, found date.'

Called with no argument, a function such as time::year() reads the current datetime, as before.

Time functions

Time constants

time::age

Available since: v4.0.0

The time::age function returns the difference between two values as an interval of years, months, days and time, as the PostgreSQL age function does. The first argument is the later value, and a result is negative when the first argument is earlier than the second.

time::age(date|timestamp|datetime, date|timestamp|datetime) -> interval

The following example shows this function, and its output:

time::age(ts'2026-10-27T12:00:00', ts'2020-02-29T06:30:00');
//- ivl'P6Y7M27DT5H30M'

time::age(ts'2020-02-29T06:30:00', ts'2026-10-27T12:00:00');
//- ivl'P-6Y-7M-27DT-5H-30M'

time::age(pd'2026-03-01', pd'2026-01-31');
//- ivl'P1M1D'

The difference is counted in whole calendar units first, so a month is the distance from one day of a month to the same day of the next. When the later value has an earlier day of the month than the earlier value, the function borrows the length of the earlier value's month, as in the last example above. The two arguments can be of different types, and an argument of infinity or -infinity is refused.

The subtraction operator gives a different result: timestamp - timestamp returns days and time but no months, so it is the better choice for a length that should not depend on the calendar.

ts'2026-10-27T00:00:00' - ts'2026-09-27T00:00:00';
//- ivl'P30D'

time::age(ts'2026-10-27T00:00:00', ts'2026-09-27T00:00:00');
//- ivl'P1M'

time::ceil

The time::ceil function raises a datetime to the nearest multiple of duration from the Unix epoch (January 1, 1970).

time::ceil(datetime, $ceiling: duration) -> datetime
time::ceil(timestamp, $ceiling: duration) -> timestamp
time::ceil(date, $ceiling: duration) -> date

The following example shows this function, and its output:

LET $now = d'2024-08-30T02:22:50.231631Z';

RETURN [
  time::ceil($now, 1h),
  time::ceil($now, 1w)
];

[
	d'2024-08-30T03:00:00Z',
	d'2024-09-05T00:00:00Z'
]

Implementation details

Since this function raises a datetime to the next multiple of duration from the Unix epoch, this means for example that:

• •

  time::ceil(now, 18d) rounds up from the nearest multiple of 18 days since epoch

• •

  time::ceil(now, 17d) rounds up from the nearest multiple of 17 days since epoch

Each call uses a different modular base, so the truncation points land at different offsets that may not be sequential. For example, for October 23, 2023 (day ~19,653 since epoch):

• •

  19653 / 18 = 1091.83… → 1092 × 18 = day 19,656 → Oct 26

• •

  19653 / 17 = 1156.05… → 1157 × 17 = day 19,669 → Nov 08

• •

  19653 / 16 = 1228.31… → 1229 × 16 = day 19,664 → Nov 03

• •

  19653 / 15 = 1310.20… → 1311 × 15 = day 19,665 → Nov 04

LET $now = d'2023-10-23T09:12:53Z';

time::ceil($now, 18d); -- d'2023-10-26T00:00:00Z'
time::ceil($now, 17d); -- d'2023-11-08T00:00:00Z'
time::ceil($now, 16d); -- d'2023-11-03T00:00:00Z'
time::ceil($now, 15d); -- d'2023-11-04T00:00:00Z'

To use this function to raise to midnight of the next day, the duration values above can be subtracted from the datetime first, followed by 1d for the ceiling.

LET $now = d'2023-10-23T09:12:53Z';

time::ceil($now - 18d, 1d); -- d'2023-10-06T00:00:00Z'
time::ceil($now - 17d, 1d); -- d'2023-10-07T00:00:00Z'
time::ceil($now - 16d, 1d); -- d'2023-10-08T00:00:00Z'
time::ceil($now - 15d, 1d); -- d'2023-10-09T00: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.

time::day(option<date|timestamp|datetime>) -> number

The following example shows this function, and its output:

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

1

time::epoch

The time::epoch constant returns the datetime for the UNIX epoch (1 January 1970).

-- Return the const
RETURN time::epoch;
//- d'1970-01-01T00:00:00Z'

-- Define field using the const
DEFINE FIELD since_epoch ON event COMPUTED time::now().floor(1d) - time::epoch;
-- Possible output, since the value depends on the current date
CREATE ONLY event:one;
//- { id: event:one, since_epoch: 56y45w6d }

time::extract

Available since: v4.0.0

The time::extract function returns one field of a date, time, timestamp or datetime, named by a string, as the PostgreSQL extract function does.

time::extract(date|time|timestamp|datetime, $field: string) -> number

The field names are not case-sensitive. A field that needs a date cannot be read from a time, and a field that needs a time of day cannot be read from a date.

The following example shows this function, and its output:

time::extract(ts'2026-10-27T12:30:45.5', 'quarter');
//- 4

time::extract(ts'2026-10-27T12:30:45.5', 'century');
//- 21

time::extract(ts'2026-10-27T12:30:45.5', 'second');
//- 45.5dec

time::extract(ts'2026-10-27T12:30:45.5', 'epoch');
//- 1793104245.5dec

time::extract(pd'2026-10-27', 'julian');
//- 2461341

time::extract(pt'12:30:45', 'year');
//- 'Incorrect arguments for function time::extract(). `year` cannot be read from a time.'

For infinity and -infinity, a field that only grows over time, such as year, century or epoch, returns Infinity or -Infinity. Every other field returns NULL.

time::extract(ts'infinity', 'year');
//- Infinity

time::extract(ts'infinity', 'month');
//- NULL

time::floor

The time::floor function truncates a datetime to the nearest lower multiple of duration from the Unix epoch (January 1, 1970).

time::floor(datetime, $floor: duration) -> datetime
time::floor(timestamp, $floor: duration) -> timestamp
time::floor(date, $floor: duration) -> date

The following example shows this function, and its output:

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

d'2021-10-28T00:00:00Z'

Implementation details

Since this function truncates a datetime to the nearest lower multiple of duration from the Unix epoch, this means for example that:

• •

  time::floor(now, 18d) rounds down to the nearest multiple of 18 days since epoch

• •

  time::floor(now, 17d) rounds down to the nearest multiple of 17 days since epoch

Each call uses a different modular base, so the truncation points land at different offsets that may not be sequential. For example, for October 23, 2023 (day ~19,653 since epoch):

• •

  19653 / 18 = 1091.83… → 1091 × 18 = day 19,638 → Oct 8

• •

  19653 / 17 = 1156.05… → 1156 × 17 = day 19,652 → Oct 22

• •

  19653 / 16 = 1228.31… → 1228 × 16 = day 19,648 → Oct 18

• •

  19653 / 15 = 1310.20… → 1310 × 15 = day 19,650 → Oct 20

LET $now = d'2023-10-23T09:12:53Z';

time::floor($now, 18d); -- d'2023-10-08T00:00:00Z'
time::floor($now, 17d); -- d'2023-10-22T00:00:00Z'
time::floor($now, 16d); -- d'2023-10-18T00:00:00Z'
time::floor($now, 15d); -- d'2023-10-20T00:00:00Z'

To use this function to truncate to the day, the duration values above can be subtracted from the datetime first, followed by 1d for the floor.

LET $now = d'2023-10-23T09:12:53Z';

time::floor($now - 18d, 1d); -- d'2023-10-05T00:00:00Z'
time::floor($now - 17d, 1d); -- d'2023-10-06T00:00:00Z'
time::floor($now - 16d, 1d); -- d'2023-10-07T00:00:00Z'
time::floor($now - 15d, 1d); -- d'2023-10-08T00:00:00Z'

time::format

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

time::format(date|timestamp|datetime, $format: string) -> string

The following example shows this function, and its output:

time::format(d"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.

time::group(datetime, $group_by: 'year'|'month'|'day'|'hour'|'minute'|'second') -> datetime
time::group(timestamp, $group_by: 'year'|'month'|'day'|'hour'|'minute'|'second') -> timestamp
time::group(date, $group_by: 'year'|'month'|'day'|'hour'|'minute'|'second') -> date

The following example shows this function, and its output:

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

d'2021-01-01T00:00:00Z'

From SurrealDB 4.0, a date or a timestamp is grouped in the same way and keeps its type. For more units, such as week or quarter, use time::trunc.

time::group(pd'2026-10-27', 'month');
//- pd'2026-10-01'

time::group(ts'2026-10-27T12:30:45', 'hour');
//- ts'2026-10-27T12:00:00'

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.

time::hour(option<time|timestamp|datetime>) -> number

The following example shows this function, and its output:

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

8

time::make_date

Available since: v4.0.0

The time::make_date function builds a date from a year, a month and a day.

time::make_date($year: int, $month: int, $day: int) -> date

The following example shows this function, and its output:

time::make_date(2026, 10, 27);
//- pd'2026-10-27'

time::make_date(2026, 2, 30);
//- 'Incorrect arguments for function time::make_date(). 2026-2-30 is not a valid date.'

time::make_time

Available since: v4.0.0

The time::make_time function builds a time from an hour, a minute and a second. The second can have a fraction, and 24:00:00 is the latest time it accepts.

time::make_time($hour: int, $minute: int, $second: number) -> time

The following example shows this function, and its output:

time::make_time(12, 30, 45.5);
//- pt'12:30:45.500'

time::make_time(24, 0, 0);
//- pt'24:00:00'

time::make_time(24, 1, 0);
//- 'Incorrect arguments for function time::make_time(). The time fields are out of range.'

time::make_timestamp

Available since: v4.0.0

The time::make_timestamp function builds a timestamp from a year, month, day, hour, minute and second. The second can have a fraction.

time::make_timestamp($year: int, $month: int, $day: int, $hour: int, $minute: int, $second: number) -> timestamp

The following example shows this function, and its output:

time::make_timestamp(2026, 10, 27, 12, 30, 45.25);

ts'2026-10-27T12:30:45.250'

time::max

The time::max function returns the greatest datetime from an array of datetimes.

time::max(array<datetime>) -> datetime
time::max(array<date>) -> date
time::max(array<time>) -> time
time::max(array<timestamp>) -> timestamp
time::max(array<interval>) -> interval

The following example shows this function, and its output:

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

d'1988-06-22T08:30:45Z'

From SurrealDB 4.0, the array can also hold dates, times, timestamps or intervals, as long as every element has the same type. Intervals compare by their total length, with a month counted as 30 days:

time::max([ivl'1 mon', ivl'29 days']);
//- ivl'P1M'

time::max([pd'2026-10-28', pt'01:00:00']);
//- 'Incorrect arguments for function time::max(). The elements must all be of one kind.'

When time::max reads a field over the records of a group, as in GROUP BY, GROUP ALL or a pre-computed table view, keep the values of each group to one temporal kind. A group that mixes kinds does not return an error, and its result depends on the order in which the records are read.

See also:

• •

  array::max, which extracts the greatest value from an array of values

• •

  math::max, which extracts the greatest number from an array of numbers

time::maximum

Available since: v2.3.0

The time::maximum constant returns the greatest possible datetime that can be used.

time::maximum -> datetime

Some examples of the constant in use:

time::maximum;

time::maximum + 1ns;

time::now() IN time::minimum..time::maximum;

-------- Query 1 --------

d'+262142-12-31T23:59:59.999Z'

-------- Query 2 --------

"Failed to compute: \"1ns + d'+262142-12-31T23:59:59.999999999Z'\", as the operation results in an arithmetic overflow."

-------- Query 3 --------

true

time::micros

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

time::micros(option<time|timestamp|datetime>) -> number

The following example shows this function, and its output:

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

551349045000000

From SurrealDB 4.0, a time gives the microseconds since midnight, and a timestamp gives the microseconds since 1970-01-01T00:00:00, read as UTC:

time::micros(pt'00:00:01');
//- 1000000

time::millis

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

time::millis(option<time|timestamp|datetime>) -> number

The following example shows this function, and its output:

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

551349045000

From SurrealDB 4.0, a time gives the milliseconds since midnight, and a timestamp gives the milliseconds since 1970-01-01T00:00:00, read as UTC:

time::millis(pt'00:00:01');
//- 1000

time::min

The time::min function returns the least datetime from an array of datetimes.

time::min(array<datetime>) -> datetime
time::min(array<date>) -> date
time::min(array<time>) -> time
time::min(array<timestamp>) -> timestamp
time::min(array<interval>) -> interval

The following example shows this function, and its output:

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

d'1987-06-22T08:30:45Z'

As with time::max, from SurrealDB 4.0 the array can hold dates, times, timestamps or intervals, as long as every element has the same type. The values in each group of a GROUP BY, a GROUP ALL or a pre-computed table view also need to be of one temporal kind.

See also:

• •

  array::min, which extracts the least value from an array of values

• •

  math::min, which extracts the least number from an array of numbers

time::minimum

Available since: v2.3.0

The time::minimum constant returns the least possible datetime that can be used.

time::minimum -> datetime

Some examples of the constant in use:

time::minimum;

time::now() IN time::minimum..time::maximum;

-------- Query 1 --------

d'-262143-01-01T00:00:00Z'

-------- Query 2 --------

true

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.

time::minute(option<time|timestamp|datetime>) -> number

The following example shows this function, and its output:

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.

time::month(option<date|timestamp|datetime>) -> number

The following example shows this function, and its output:

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

time::nano(option<time|timestamp|datetime>) -> number

The result must fit in a signed 64-bit integer (roughly spanning datetimes from 1677 through 2262). Values outside that range return an arithmetic overflow error instead of 0.

The following example shows this function, and its output:

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

1635755417000000000

From SurrealDB 4.0, a time gives the nanoseconds since midnight, and a timestamp gives the nanoseconds since 1970-01-01T00:00:00, read as UTC:

time::nano(pt'00:00:01');
//- 1000000000

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, $round_to: duration) -> datetime
time::round(timestamp, $round_to: duration) -> timestamp
time::round(date, $round_to: duration) -> date

The following example shows this function, and its output:

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.

time::second(option<time|timestamp|datetime>) -> number

The following example shows this function, and its output:

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.

time::timezone() -> string

time::trunc

Available since: v4.0.0

The time::trunc function truncates a value to the start of a unit, as the PostgreSQL date_trunc function does, and returns the same type that it was given. It is a wider form of time::group that also accepts week, quarter, decade, century and millennium.

time::trunc(datetime, $unit: string) -> datetime
time::trunc(timestamp, $unit: string) -> timestamp
time::trunc(date, $unit: string) -> date
time::trunc(time, $unit: string) -> time

The units are microseconds, milliseconds, second, minute, hour, day, week, month, quarter, year, decade, century and millennium. A week starts on a Monday, and a century or a millennium starts with year 1, as in 2001-01-01. A time can only be truncated to hour or a smaller unit.

The following example shows this function, and its output:

time::trunc(ts'2026-10-27T12:30:45.123456', 'minute');
//- ts'2026-10-27T12:30:00'

time::trunc(ts'2026-10-27T12:30:45.123456', 'week');
//- ts'2026-10-26T00:00:00'

time::trunc(pd'2026-10-27', 'century');
//- pd'2001-01-01'

time::trunc(pt'12:30:45', 'hour');
//- pt'12:00:00'

infinity and -infinity truncate to themselves.

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.

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

The following example shows this function, and its output:

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.

time::wday(option<date|timestamp|datetime>) -> number

The following example shows this function, and its output:

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.

time::week(option<date|timestamp|datetime>) -> number

The following example shows this function, and its output:

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.

time::yday(option<date|timestamp|datetime>) -> number

The following example shows this function, and its output:

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.

time::year(option<date|timestamp|datetime>) -> number

The following example shows this function, and its output:

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

2021

time::is_leap_year()

The time::is_leap_year() function checks if a given datetime is a leap year.

time::is_leap_year(option<date|timestamp|datetime>) -> bool

The following example shows this function, and its output:

-- Checks with current datetime if none is passed
time::is_leap_year();

time::is_leap_year(d"1987-06-22T08:30:45Z");
//- false

time::is_leap_year(d"1988-06-22T08:30:45Z");
//- true

-- Using function via method chaining
d'2024-09-03T02:33:15.349397Z'.is_leap_year();
//- true

time::from_micros

The time::from_micros function calculates a datetime based on the microseconds since 1 January 1970 000 UTC.

time::from_micros(number) -> datetime

The following example shows this function, and its output:

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 1 January 1970 000 UTC.

time::from_millis(number) -> datetime

The following example shows this function, and its output:

time::from_millis(1000);

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

time::from_nanos

The time::from_nanos function calculates a datetime based on the nanoseconds since 1 January 1970 000 UTC.

time::from_nanos(number) -> datetime

The following example shows this function, and its output:

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 1 January 1970 000 UTC.

time::from_secs(number) -> datetime

The following example shows this function, and its output:

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 1 January 1970 000 UTC.

time::from_unix(number) -> datetime

The following example shows this function, and its output:

time::from_unix(1000);

d'1970-01-01T00:16:40Z'

time::from_ulid

The time::from_ulid function calculates a datetime based on the ULID.

time::from_ulid(ulid) -> datetime

The following example shows this function, and its output:

time::from_ulid("01JH5BBTK9FKTGSDXHWP5YP9TQ");

d'2025-01-09T10:57:03.593Z'

As a ULID is only precise up to the millisecond, a conversion from a ULID to a timestamp will truncate nanosecond precision.

LET $now = time::now();
[$now, time::from_ulid(rand::ulid($now))];

-- Output:
[
	d'2026-01-29T02:07:06.494218Z',
	d'2026-01-29T02:07:06.494Z'
]

time::from_uuid

The time::from_uuid function calculates a datetime based on the UUID.

time::from_uuid(uuid) -> datetime

The following example shows this function, and its output:

time::from_uuid(u'01944ab6-c1e5-7760-ab6a-127d37eb1b94');

d'2025-01-09T10:57:58.757Z'

The UUID must be a version 1, 6 or 7 UUID, because only these versions hold a time. Any other version, such as the version 4 UUID that rand::uuid::v4() generates, fails with Incorrect arguments for function time::from_uuid(). The first argument must be a v1, v6 or v7 UUID. A version 1 or 6 UUID can also hold a date before 1970:

time::from_uuid(u'3c230000-a32f-1163-8000-000000000000');

d'1900-01-01T00:00:00Z'

A version 7 UUID, which rand::uuid() generates, is only precise to the millisecond, so a conversion from it to a datetime drops anything smaller.

LET $now = time::now();
[$now, time::from_uuid(rand::uuid($now))];

[
	d'2026-01-29T02:12:13.848476Z',
	d'2026-01-29T02:12:13.848Z'
]

time::set_year

Available since: v3.0.2

The time::set_year function sets the year value of a datetime.

time::set_year(datetime, $year: integer) -> datetime
time::set_year(timestamp, $year: integer) -> timestamp
time::set_year(date, $year: integer) -> date

Example:

d'1970-01-01T00:00:00.500000005Z'.set_year(2026);
-- Output
d'2026-01-01T00:00:00.500000000Z'

time::set_month

Available since: v3.0.2

The time::set_month function sets the month value of a datetime.

time::set_month(datetime, $month: integer) -> datetime
time::set_month(timestamp, $month: integer) -> timestamp
time::set_month(date, $month: integer) -> date

Example:

d'1970-01-01T00:00:00.500000005Z'.set_month(9);
-- Output
d'1970-09-01T00:00:00.500000005Z'

time::set_day

Available since: v3.0.2

The time::set_day function sets the day value of a datetime.

time::set_day(datetime, $day: integer) -> datetime
time::set_day(timestamp, $day: integer) -> timestamp
time::set_day(date, $day: integer) -> date

Example:

d'1970-01-01T00:00:00.500000005Z'.set_day(10);
-- Output
d'1970-01-10T00:00:00.500000005Z'

time::set_hour

Available since: v3.0.2

The time::set_hour function sets the hour value of a datetime.

time::set_hour(datetime, $hour: integer) -> datetime
time::set_hour(timestamp, $hour: integer) -> timestamp
time::set_hour(date, $hour: integer) -> date

Example:

d'1970-01-01T00:00:00.500000005Z'.set_hour(10);
-- Output
d'1970-01-01T10:00:00.500000005Z'

time::set_minute

Available since: v3.0.2

The time::set_minute function sets the minute value of a datetime.

time::set_minute(datetime, $minute: integer) -> datetime
time::set_minute(timestamp, $minute: integer) -> timestamp
time::set_minute(date, $minute: integer) -> date

Example:

d'1970-01-01T10:00:00.500000005Z'.set_minute(55);
-- Output
d'1970-01-01T10:55:00.500000005Z'

time::set_second

Available since: v3.0.2

The time::set_second function sets the second value of a datetime.

time::set_second(datetime, $second: integer) -> datetime
time::set_second(timestamp, $second: integer) -> timestamp
time::set_second(date, $second: integer) -> date

Example:

d'1970-01-01T10:00:00.500000005Z'.set_second(30);
-- Output
d'1970-01-01T10:00:30.500000005Z'

time::set_nanosecond

Available since: v3.0.2

The time::set_nanosecond function sets the nanosecond value of a datetime.

time::set_nanosecond(datetime, $nanosecond: integer) -> datetime
time::set_nanosecond(timestamp, $nanosecond: integer) -> timestamp
time::set_nanosecond(date, $nanosecond: integer) -> date

Example:

d'1970-01-01T10:00:00.500000005Z'.set_nanosecond(3535);
-- Output
d'1970-01-01T10:00:00.000003535Z'

Since nanoseconds are not needed in a datetime, setting the nanoseconds of a datetime to 0 can be used to make a datetime look cleaner.

d'1970-01-01T00:00:00.500000000Z'.set_nanosecond(0);
d'1970-01-01T00:00:00Z' -- output