4.9.5. LocalTime: localtime()

Details for using the localtime() function.

4.9.5.1. Getting the current LocalTime

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

Syntax: localtime([ {timezone} ])

Returns:

A LocalTime.

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, localtime() must be invoked (localtime({}) is invalid).

Query. 

RETURN localtime() AS now

The current local time (i.e. in the local time zone) is returned.

Table 4.138. Result
now

1 row

10:36:56.107

Try this query live.  none RETURN localtime() AS now

Query. 

RETURN localtime({ timezone: 'America/Los Angeles' }) AS nowInLA

The current local time in California is returned.

Table 4.139. Result
nowInLA

1 row

03:36:56.119

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

localtime.transaction()

localtime.transaction() returns the current LocalTime 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: localtime.transaction([ {timezone} ])

Returns:

A LocalTime.

Arguments:

Name Description

timezone

A string expression that represents the time zone

Query. 

RETURN localtime.transaction() AS now

Table 4.140. Result
now

1 row

10:36:56.120

Try this query live.  none RETURN localtime.transaction() AS now

localtime.statement()

localtime.statement() returns the current LocalTime 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: localtime.statement([ {timezone} ])

Returns:

A LocalTime.

Arguments:

Name Description

timezone

A string expression that represents the time zone

Query. 

RETURN localtime.statement() AS now

Table 4.141. Result
now

1 row

10:36:56.145

Try this query live.  none RETURN localtime.statement() AS now

Query. 

RETURN localtime.statement('America/Los Angeles') AS nowInLA

Table 4.142. Result
nowInLA

1 row

03:36:56.161

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

localtime.realtime()

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

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

Returns:

A LocalTime.

Arguments:

Name Description

timezone

A string expression that represents the time zone

Query. 

RETURN localtime.realtime() AS now

Table 4.143. Result
now

1 row

10:36:56.173

Try this query live.  none RETURN localtime.realtime() AS now

4.9.5.2. Creating a LocalTime

localtime() returns a LocalTime value with the specified hour, minute, second, millisecond, microsecond and nanosecond component values.

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

Returns:

A LocalTime.

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.

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.

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 [
localtime({ hour:12, minute:31, second:14, nanosecond: 789, millisecond: 123, microsecond: 456 }),
localtime({ hour:12, minute:31, second:14 }),
localtime({ hour:12 })
] AS theTime
RETURN theTime

Table 4.144. Result
theTime

3 rows

12:31:14.123456789

12:31:14

12:00

Try this query live.  none UNWIND [ localtime({hour:12, minute:31, second:14, nanosecond: 789, millisecond: 123, microsecond: 456}), localtime({hour:12, minute:31, second:14}), localtime({hour:12}) ] as theTime RETURN theTime

4.9.5.3. Creating a LocalTime from a string

localtime() returns the LocalTime value obtained by parsing a string representation of a temporal value.

Syntax: localtime(temporalValue)

Returns:

A LocalTime.

Arguments:

Name Description

temporalValue

A string representing a temporal value.

Considerations:

temporalValue must comply with the format defined for times.

localtime(null) returns the current time.

temporalValue must denote a valid time; i.e. a temporalValue denoting 13:46:64 is invalid.

Query. 

UNWIND [
localtime('21:40:32.142'),
localtime('214032.142'),
localtime('21:40'),
localtime('21')
] AS theTime
RETURN theTime

Table 4.145. Result
theTime

4 rows

21:40:32.142

21:40:32.142

21:40

21:00

Try this query live.  none UNWIND [ localtime('21:40:32.142'), localtime('214032.142'), localtime('21:40'), localtime('21') ] AS theTime RETURN theTime

4.9.5.4. Creating a LocalTime using other temporal values as components

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

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

Returns:

A LocalTime.

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.

Considerations:

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

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

Query. 

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

Table 4.146. Result
timeOnly timeSS

1 row

12:31:14.645876

12:31:42.645876

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

4.9.5.5. Truncating a LocalTime

localtime.truncate() returns the LocalTime 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 LocalTime 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: localtime.truncate(unit, temporalInstantValue [, mapOfComponents ])

Returns:

A LocalTime.

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.

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.

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 localtime.truncate('day', t) AS truncDay,
localtime.truncate('hour', t) AS truncHour,
localtime.truncate('minute', t, { millisecond:2 }) AS truncMinute,
localtime.truncate('second', t) AS truncSecond,
localtime.truncate('millisecond', t) AS truncMillisecond,
localtime.truncate('microsecond', t) AS truncMicrosecond

Table 4.147. Result
truncDay truncHour truncMinute truncSecond truncMillisecond truncMicrosecond

1 row

00:00

12:00

12:31:00.002

12:31:14

12:31:14.645

12:31:14.645876

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