4.9.6. Time: time()

Details for using the time() function.

4.9.6.1. Getting the current Time

time() returns the current Time value. If no time zone parameter is specified, the local time zone will be used.

Syntax: time([ {timezone} ])

Returns:

A Time.

Arguments:

Name Description

A single map consisting of the following:

 

timezone

A string expression that represents the time zone

Considerations:

If no parameters are provided, time() must be invoked (time({}) is invalid).

Query. 

RETURN time() AS currentTime

The current time of day using the local time zone is returned.

Table 4.148. Result
currentTime

1 row

19:06:12.090Z

Try this query live.  none RETURN time() AS currentTime

Query. 

RETURN time({ timezone: 'America/Los Angeles' }) AS currentTimeInLA

The current time of day in California is returned.

Table 4.149. Result
currentTimeInLA

1 row

12:06:12.101-07:00

Try this query live.  none RETURN time( {timezone: 'America/Los Angeles'} ) AS currentTimeInLA

time.transaction()

time.transaction() returns the current Time value using the transaction clock. This value will be the same for each invocation within the same transaction. However, a different value may be produced for different transactions.

Syntax: time.transaction([ {timezone} ])

Returns:

A Time.

Arguments:

Name Description

timezone

A string expression that represents the time zone

Query. 

RETURN time.transaction() AS currentTime

Table 4.150. Result
currentTime

1 row

19:06:12.102Z

Try this query live.  none RETURN time.transaction() AS currentTime

time.statement()

time.statement() returns the current Time value using the statement clock. This value will be the same for each invocation within the same statement. However, a different value may be produced for different statements within the same transaction.

Syntax: time.statement([ {timezone} ])

Returns:

A Time.

Arguments:

Name Description

timezone

A string expression that represents the time zone

Query. 

RETURN time.statement() AS currentTime

Table 4.151. Result
currentTime

1 row

19:06:12.114Z

Try this query live.  none RETURN time.statement() AS currentTime

Query. 

RETURN time.statement('America/Los Angeles') AS currentTimeInLA

Table 4.152. Result
currentTimeInLA

1 row

12:06:12.121-07:00

Try this query live.  none RETURN time.statement('America/Los Angeles') AS currentTimeInLA

time.realtime()

time.realtime() returns the current Time value using the realtime clock. This value will be the live clock of the system.

Syntax: time.realtime([ {timezone} ])

Returns:

A Time.

Arguments:

Name Description

timezone

A string expression that represents the time zone

Query. 

RETURN time.realtime() AS currentTime

Table 4.153. Result
currentTime

1 row

19:06:12.128Z

Try this query live.  none RETURN time.realtime() AS currentTime

4.9.6.2. Creating a Time

time() returns a Time value with the specified hour, minute, second, millisecond, microsecond, nanosecond and timezone component values.

Syntax: time({hour [, minute, second, millisecond, microsecond, nanosecond, timezone]})

Returns:

A Time.

Arguments:

Name Description

A single map consisting of the following:

 

hour

An integer between 0 and 23 that specifies the hour of the day.

minute

An integer between 0 and 59 that specifies the number of minutes.

second

An integer between 0 and 59 that specifies the number of seconds.

millisecond

An integer between 0 and 999 that specifies the number of milliseconds.

microsecond

An integer between 0 and 999,999 that specifies the number of microseconds.

nanosecond

An integer between 0 and 999,999,999 that specifies the number of nanoseconds.

timezone

An expression that specifies the time zone.

Considerations:

The hour component will default to 0 if hour is omitted.

The minute component will default to 0 if minute is omitted.

The second component will default to 0 if second is omitted.

Any missing millisecond, microsecond or nanosecond values will default to 0.

The timezone component will default to the configured default time zone if timezone is omitted.

If millisecond, microsecond and nanosecond are given in combination (as part of the same set of parameters), the individual values must be in the range 0 to 999.

The least significant components in the set hour, minute, and second may be omitted; i.e. it is possible to specify only hour and minute, but specifying hour and second is not permitted.

One or more of millisecond, microsecond and nanosecond can only be specified as long as second is also specified.

Query. 

UNWIND [
time({ hour:12, minute:31, second:14, millisecond: 123, microsecond: 456, nanosecond: 789 }),
time({ hour:12, minute:31, second:14, nanosecond: 645876123 }),
time({ hour:12, minute:31, second:14, microsecond: 645876, timezone: '+01:00' }),
time({ hour:12, minute:31, timezone: '+01:00' }),
time({ hour:12, timezone: '+01:00' })
] AS theTime
RETURN theTime

Table 4.154. Result
theTime

5 rows

12:31:14.123456789Z

12:31:14.645876123Z

12:31:14.645876+01:00

12:31+01:00

12:00+01:00

Try this query live.  none UNWIND [ time({hour:12, minute:31, second:14, millisecond: 123, microsecond: 456, nanosecond: 789}), time({hour:12, minute:31, second:14, nanosecond: 645876123}), time({hour:12, minute:31, second:14, microsecond: 645876, timezone: '+01:00'}), time({hour:12, minute:31, timezone: '+01:00'}), time({hour:12, timezone: '+01:00'}) ] AS theTime RETURN theTime

4.9.6.3. Creating a Time from a string

time() returns the Time value obtained by parsing a string representation of a temporal value.

Syntax: time(temporalValue)

Returns:

A Time.

Arguments:

Name Description

temporalValue

A string representing a temporal value.

Considerations:

temporalValue must comply with the format defined for times and time zones.

The timezone component will default to the configured default time zone if it is omitted.

time(null) returns the current time.

temporalValue must denote a valid time; i.e. a temporalValue denoting 15:67 is invalid.

Query. 

UNWIND [
time('21:40:32.142+0100'),
time('214032.142Z'),
time('21:40:32+01:00'),
time('214032-0100'),
time('21:40-01:30'),
time('2140-00:00'),
time('2140-02'),
time('22+18:00')
] AS theTime
RETURN theTime

Table 4.155. Result
theTime

8 rows

21:40:32.142+01:00

21:40:32.142Z

21:40:32+01:00

21:40:32-01:00

21:40-01:30

21:40Z

21:40-02:00

22:00+18:00

Try this query live.  none UNWIND [ time('21:40:32.142+0100'), time('214032.142Z'), time('21:40:32+01:00'), time('214032-0100'), time('21:40-01:30'), time('2140-00:00'), time('2140-02'), time('22+18:00') ] AS theTime RETURN theTime

4.9.6.4. Creating a Time using other temporal values as components

time() returns the Time value obtained by selecting and composing components from another temporal value. In essence, this allows a DateTime, LocalDateTime or LocalTime value to be converted to a Time, and for "missing" components to be provided.

Syntax: time({time [, hour, …​, timezone]})

Returns:

A Time.

Arguments:

Name Description

A single map consisting of the following:

 

time

A Time value.

hour

An integer between 0 and 23 that specifies the hour of the day.

minute

An integer between 0 and 59 that specifies the number of minutes.

second

An integer between 0 and 59 that specifies the number of seconds.

millisecond

An integer between 0 and 999 that specifies the number of milliseconds.

microsecond

An integer between 0 and 999,999 that specifies the number of microseconds.

nanosecond

An integer between 0 and 999,999,999 that specifies the number of nanoseconds.

timezone

An expression that specifies the time zone.

Considerations:

If any of the optional parameters are provided, these will override the corresponding components of time.

time(tt) may be written instead of time({time: tt}).

Selecting a Time or DateTime value as the time component also selects its time zone. If a LocalTime or LocalDateTime is selected instead, the default time zone is used. In any case, the time zone can be overridden explicitly.

Selecting a DateTime or Time as the time component and overwriting the time zone will adjust the local time to keep the same point in time.

Query. 

WITH localtime({ hour:12, minute:31, second:14, microsecond: 645876 }) AS tt
RETURN time({ time:tt }) AS timeOnly,
time({ time:tt, timezone:'+05:00' }) AS timeTimezone,
time({ time:tt, second: 42 }) AS timeSS,
time({ time:tt, second: 42, timezone:'+05:00' }) AS timeSSTimezone

Table 4.156. Result
timeOnly timeTimezone timeSS timeSSTimezone

1 row

12:31:14.645876Z

12:31:14.645876+05:00

12:31:42.645876Z

12:31:42.645876+05:00

Try this query live.  none WITH localtime({hour:12, minute:31, second:14, microsecond: 645876}) AS tt RETURN time({time:tt}) AS timeOnly, time({time:tt, timezone:'+05:00'}) AS timeTimezone, time({time:tt, second: 42}) AS timeSS, time({time:tt, second: 42, timezone:'+05:00'}) AS timeSSTimezone

4.9.6.5. Truncating a Time

time.truncate() returns the Time value obtained by truncating a specified temporal instant value at the nearest preceding point in time at the specified component boundary (which is denoted by the truncation unit passed as a parameter to the function). In other words, the Time returned will have all components that are less significant than the specified truncation unit set to their default values.

It is possible to supplement the truncated value by providing a map containing components which are less significant than the truncation unit. This will have the effect of overriding the default values which would otherwise have been set for these less significant components. For example, minute — with some value x — may be provided when the truncation unit is hour in order to ensure the returned value has the minute set to x instead of the default minute (which is 1).

Syntax: time.truncate(unit, temporalInstantValue [, mapOfComponents ])

Returns:

A Time.

Arguments:

Name Description

unit

A string expression evaluating to one of the following: {day, hour, minute, second, millisecond, microsecond}.

temporalInstantValue

An expression of one of the following types: {DateTime, LocalDateTime, Time, LocalTime}.

mapOfComponents

An expression evaluating to a map containing components less significant than unit. During truncation, a time zone can be attached or overridden using the key timezone.

Considerations:

Truncating time to day — i.e. unit is 'day'  — is supported, and yields midnight at the start of the day (00:00), regardless of the value of temporalInstantValue. However, the time zone of temporalInstantValue is retained.

The time zone of temporalInstantValue may be overridden; for example, time.truncate('minute', input, {timezone:'+0200'}).

If temporalInstantValue is one of {Time, DateTime} — a value with a time zone — and the time zone is overridden, no time conversion occurs.

If temporalInstantValue is one of {LocalTime, LocalDateTime, Date} — a value without a time zone — and the time zone is not overridden, the configured default time zone will be used.

Any component that is provided in mapOfComponents must be less significant than unit; i.e. if unit is 'second', mapOfComponents cannot contain information pertaining to a minute.

Any component that is not contained in mapOfComponents and which is less significant than unit will be set to its minimal value.

If mapOfComponents is not provided, all components of the returned value which are less significant than unit will be set to their default values.

Query. 

WITH time({ hour:12, minute:31, second:14, nanosecond: 645876123, timezone: '-01:00' }) AS t
RETURN time.truncate('day', t) AS truncDay, time.truncate('hour', t) AS truncHour, time.truncate('minute', t) AS truncMinute, time.truncate('second', t) AS truncSecond, time.truncate('millisecond', t, { nanosecond:2 }) AS truncMillisecond, time.truncate('microsecond', t) AS truncMicrosecond

Table 4.157. Result
truncDay truncHour truncMinute truncSecond truncMillisecond truncMicrosecond

1 row

00:00-01:00

12:00-01:00

12:31-01:00

12:31:14-01:00

12:31:14.645000002-01:00

12:31:14.645876-01:00

Try this query live.  none WITH time({hour:12, minute:31, second:14, nanosecond: 645876123, timezone: '-01:00'}) AS t RETURN time.truncate('day', t) AS truncDay, time.truncate('hour', t) AS truncHour, time.truncate('minute', t) AS truncMinute, time.truncate('second', t) AS truncSecond, time.truncate('millisecond', t, {nanosecond:2}) AS truncMillisecond, time.truncate('microsecond', t) AS truncMicrosecond