Temporal functions - instant types

Temporal functions allow for the creation and manipulation of values for each temporal type — DATE, ZONED TIME, LOCAL TIME, ZONED DATETIME, and LOCAL DATETIME.

The following functions are included on this page:

DATE ZONED DATETIME LOCAL DATETIME LOCAL TIME ZONED TIME

`DATE`	`ZONED DATETIME`	`LOCAL DATETIME`	`LOCAL TIME`	`ZONED TIME`
date()	datetime()	localdatetime()	localtime()	time()
	datetime.fromEpoch()
	datetime.fromEpochMillis()
date.realtime()	datetime.realtime()	localdatetime.realtime()	localtime.realtime()	time.realtime()
date.statement()	datetime.statement()	localdatetime.statement()	localtime.statement()	time.statement()
date.transaction()	datetime.transaction()	localdatetime.transaction()	localtime.transaction()	time.transaction()

datetime.fromEpochMillis()

date.realtime()

datetime.realtime()

localdatetime.realtime()

localdatetime.statement()

localtime.statement()

time.statement()

date.transaction()

datetime.transaction()

localdatetime.transaction()

localtime.transaction()

time.transaction()

Temporal instant types

An overview of temporal instant type creation

Each function bears the same name as the type, and construct the type they correspond to in one of four ways:

Capturing the current time.
Composing the components of the type.
Parsing a STRING representation of the temporal value.
Selecting and composing components from another temporal value by
- either combining temporal values (such as combining a DATE with a ZONED TIME to create a ZONED DATETIME), or
- selecting parts from a temporal value (such as selecting the DATE from a ZONED DATETIME); the extractors — groups of components which can be selected — are:
  - date — contains all components for a DATE (conceptually year, month and day).
  - time — contains all components for a ZONED TIME (hour, minute, second, and sub-seconds; namely millisecond, microsecond and nanosecond). If the type being created and the type from which the time component is being selected both contain timezone (and a timezone is not explicitly specified) the timezone is also selected.
  - datetime — selects all components, and is useful for overriding specific components. Analogously to time, if the type being created and the type from which the time component is being selected both contain timezone (and a timezone is not explicitly specified) the timezone is also selected.
- In effect, this allows for the conversion between different temporal types, and allowing for 'missing' components to be specified.

Temporal instant type creation functions
Function	`DATE`	`ZONED TIME`	`LOCAL TIME`	`ZONED DATETIME`	`LOCAL DATETIME`
Getting the current value.
Creating a calendar-based (Year-Month-Day) value.
Creating a week-based (Year-Week-Day) value.
Creating a quarter-based (Year-Quarter-Day) value.
Creating an ordinal (Year-Day) value.
Creating a value from time components.
Creating a value from other temporal values using extractors (i.e. converting between different types).
Creating a value from a `STRING`.
Creating a value from a timestamp.

All the temporal instant types — including those that do not contain timezone information support such as DATE, LOCAL TIME and ZONED DATETIME — allow for a timezone to specified for the functions that retrieve the current instant. This allows for the retrieval of the current instant in the specified timezone.

Controlling which clock to use

The functions which create temporal instant values based on the current instant use the statement clock as default. However, there are three different clocks available for more fine-grained control:

transaction: The same instant is produced for each invocation within the same transaction. A different time may be produced for different transactions.
statement: The same instant is produced for each invocation within the same statement. A different time may be produced for different statements within the same transaction.
realtime: The instant produced will be the live clock of the system.

The following table lists the different sub-functions for specifying the clock to be used when creating the current temporal instant value:

Type	default	transaction	statement	realtime
Date	date()	date.transaction()	date.statement()	date.realtime()
Time	time()	time.transaction()	time.statement()	time.realtime()
LocalTime	localtime()	localtime.transaction()	localtime.statement()	localtime.realtime()
DateTime	datetime()	datetime.transaction()	datetime.statement()	datetime.realtime()
LocalDateTime	localdatetime()	localdatetime.transaction()	localdatetime.statement()	localdatetime.realtime()

Type

default

transaction

statement

realtime

Date

Time

LocalTime

localtime.transaction()

localtime.statement()

localtime.realtime()

DateTime

datetime()

datetime.transaction()

datetime.statement()

datetime.realtime()

LocalDateTime

localdatetime()

localdatetime.transaction()

localdatetime.statement()

localdatetime.realtime()

Truncating temporal values

A temporal instant value can be created by truncating another temporal instant value at the nearest preceding point in time at a specified component boundary (namely, a truncation unit). A temporal instant value created in this way will have all components which are smaller 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 smaller than the truncation unit. This will have the effect of overriding the default values which would otherwise have been set for these smaller components.

The following table lists the supported truncation units and the corresponding sub-functions:

Truncation unit DATE ZONED TIME LOCAL TIME ZONED DATETIME LOCAL DATETIME

Truncation unit	`DATE`	`ZONED TIME`	`LOCAL TIME`	`ZONED DATETIME`	`LOCAL DATETIME`
`millennium`	date.truncate('millennium', input)			datetime.truncate('millennium', input)	localdatetime.truncate('millennium', input)
`century`	date.truncate('century', input)			datetime.truncate('century', input)	localdatetime.truncate('century', input)
`decade`	date.truncate('decade', input)			datetime.truncate('decade', input)	localdatetime.truncate('decade', input)
`year`	date.truncate('year', input)			datetime.truncate('year', input)	localdatetime.truncate('year', input)
`weekYear`	date.truncate('weekYear', input)			datetime.truncate('weekYear', input)	localdatetime.truncate('weekYear', input)
`quarter`	date.truncate('quarter', input)			datetime.truncate('quarter', input)	localdatetime.truncate('quarter', input)
`month`	date.truncate('month', input)			datetime.truncate('month', input)	localdatetime.truncate('month', input)
`week`	date.truncate('week', input)			datetime.truncate('week', input)	localdatetime.truncate('week', input)
`day`	date.truncate('day', input)	time.truncate('day', input)	localtime.truncate('day', input)	datetime.truncate('day', input)	localdatetime.truncate('day', input)
`hour`		time.truncate('hour', input)	localtime.truncate('hour', input)	datetime.truncate('hour', input)	localdatetime.truncate('hour',input)
`minute`		time.truncate('minute', input)	localtime.truncate('minute', input)	datetime.truncate('minute', input)	localdatetime.truncate('minute', input)
`second`		time.truncate('second', input)	localtime.truncate('second', input)	datetime.truncate('second', input)	localdatetime.truncate('second', input)
`millisecond`		time.truncate('millisecond', input)	localtime.truncate('millisecond', input)	datetime.truncate('millisecond', input)	localdatetime.truncate('millisecond', input)
`microsecond`		time.truncate('microsecond', input)	localtime.truncate('microsecond', input)	datetime.truncate('microsecond', input)	localdatetime.truncate('microsecond', input)

millennium

date.truncate('millennium', input)

datetime.truncate('millennium', input)

localdatetime.truncate('millennium', input)

century

date.truncate('century', input)

datetime.truncate('century', input)

localdatetime.truncate('century', input)

decade

date.truncate('decade', input)

datetime.truncate('decade', input)

localdatetime.truncate('decade', input)

year

date.truncate('year', input)

datetime.truncate('year', input)

localdatetime.truncate('year', input)

weekYear

date.truncate('weekYear', input)

datetime.truncate('weekYear', input)

localdatetime.truncate('weekYear', input)

quarter

date.truncate('quarter', input)

datetime.truncate('quarter', input)

localdatetime.truncate('quarter', input)

month

date.truncate('month', input)

datetime.truncate('month', input)

localdatetime.truncate('month', input)

week

date.truncate('week', input)

datetime.truncate('week', input)

localdatetime.truncate('week', input)

day

date.truncate('day', input)

time.truncate('day', input)

localtime.truncate('day', input)

datetime.truncate('day', input)

localdatetime.truncate('day', input)

hour

time.truncate('hour', input)

localtime.truncate('hour', input)

datetime.truncate('hour', input)

localdatetime.truncate('hour',input)

minute

time.truncate('minute', input)

localtime.truncate('minute', input)

datetime.truncate('minute', input)

localdatetime.truncate('minute', input)

second

time.truncate('second', input)

localtime.truncate('second', input)

datetime.truncate('second', input)

localdatetime.truncate('second', input)

millisecond

time.truncate('millisecond', input)

localtime.truncate('millisecond', input)

datetime.truncate('millisecond', input)

localdatetime.truncate('millisecond', input)

microsecond

time.truncate('microsecond', input)

localtime.truncate('microsecond', input)

datetime.truncate('microsecond', input)

localdatetime.truncate('microsecond', input)

date()

Details
Syntax	`date( [input] )`
Description	Creates a `DATE` instant.
Arguments	Name	Type	Description
	`input`	`ANY`	Either a string representation of a temporal value, a map containing the single key 'timezone', or a map containing temporal values ('date', 'year', 'month', 'day', 'week', 'dayOfWeek', 'quarter', 'dayOfQuarter', 'ordinalDay') as components.
Returns	`DATE`

Temporal components
Name	Description
`date`	A `DATE` value.
`year`	An expression consisting of at least four digits that specifies the year.
`month`	An integer between `1` and `12` that specifies the month.
`day`	An integer between `1` and `31` that specifies the day of the month.
`week`	An integer between `1` and `53` that specifies the week.
`dayOfWeek`	An integer between `1` and `7` that specifies the day of the week.
`quarter`	An integer between `1` and `4` that specifies the quarter.
`dayOfQuarter`	An integer between `1` and `92` that specifies the day of the quarter.
`ordinalDay`	An integer between `1` and `366` that specifies the ordinal day of the year.

Considerations
If no parameters are provided, `date()` must be invoked (`date({})` is invalid).
If no timezone is specified, the local timezone will be used.
The day of the month component will default to `1` if `day` is omitted.
The month component will default to `1` if `month` is omitted.
If `month` is omitted, `day` must also be omitted.
The day of the week component will default to `1` if `dayOfWeek` is omitted.
The week component will default to `1` if `week` is omitted.
If `week` is omitted, `dayOfWeek` must also be omitted.
The day of the quarter component will default to `1` if `dayOfQuarter` is omitted.
The quarter component will default to `1` if `quarter` is omitted.
If `quarter` is omitted, `dayOfQuarter` must also be omitted.
The ordinal day of the year component will default to `1` if `ordinalDay` is omitted.
String representations of temporal values must comply with the format defined for dates.
String representations of temporal values must denote a valid date; i.e. a temporal value denoting `30 February 2001` is invalid.
`date(null)` returns `null`.
If any of the optional parameters are provided, these will override the corresponding components of `date`.
`date(dd)` may be written instead of `date({date: dd})`.

Example 1. date() to get the current time (no parameters provided)

Query

RETURN date() AS currentDate

The current date is returned.

Result
currentDate
`2022-06-14`
Rows: 1

Example 2. date() with provided timezone

Query

RETURN date({timezone: 'America/Los Angeles'}) AS currentDateInLA

The current date in California is returned.

Result
currentDateInLA
`2022-06-14`
Rows: 1

Creating `DATE` values

Example 3. date() - Creating a calendar (Yeay-Month-Day) DATE

Query

UNWIND [
date({year: 1984, month: 10, day: 11}),
date({year: 1984, month: 10}),
date({year: 1984})
] AS theDate
RETURN theDate

Result
theDate
`1984-10-11`
`1984-10-01`
`1984-01-01`
Rows: 3

Example 4. date() - Creating a week (Year-Week-Day) DATE

Query

UNWIND [
date({year: 1984, week: 10, dayOfWeek: 3}),
date({year: 1984, week: 10}),
date({year: 1984})
] AS theDate
RETURN theDate

Result
theDate
`1984-03-07`
`1984-03-05`
`1984-01-01`
Rows: 3

Example 5. date() - Creating a quarter (Year-Quarter-Day) DATE

Query

UNWIND [
date({year: 1984, quarter: 3, dayOfQuarter: 45}),
date({year: 1984, quarter: 3}),
date({year: 1984})
] AS theDate
RETURN theDate

Result
theDate
`1984-08-14`
`1984-07-01`
`1984-01-01`
Rows: 3

Example 6. date() - Creating an ordinal (Year-Day) DATE

Query

UNWIND [
date({year: 1984, ordinalDay: 202}),
date({year: 1984})
] AS theDate
RETURN theDate

The date corresponding to 11 February 1984 is returned.

Result
theDate
`1984-07-20`
`1984-01-01`
Rows: 2

Example 7. date() - Creating a DATE using other temporal values as components

Query

UNWIND [
date({year: 1984, month: 11, day: 11}),
localdatetime({year: 1984, month: 11, day: 11, hour: 12, minute: 31, second: 14}),
datetime({year: 1984, month: 11, day: 11, hour: 12, timezone: '+01:00'})
] AS dd
RETURN date({date: dd}) AS dateOnly, date({date: dd, day: 28}) AS dateDay

Result
dateOnly	+dateDay
`1984-11-11`	`1984-11-28`
`1984-11-11`	`1984-11-28`
`1984-11-11`	`1984-11-28`
Rows: 3

Example 8. date() - Creating a DATE from a STRING

Query

UNWIND [
date('2015-07-21'),
date('2015-07'),
date('201507'),
date('2015-W30-2'),
date('2015202'),
date('2015')
] AS theDate
RETURN theDate

Result
theDate
`2015-07-21`
`2015-07-01`
`2015-07-01`
`2015-07-21`
`2015-07-21`
`2015-01-01`
Rows: 6

date.realtime()

Details
Syntax	`date.realtime([ timezone ])`
Description	Returns the current `DATE` instant using the realtime clock.
Arguments	Name	Type	Description
	`timezone`	`ANY`	A string value representing a timezone.
Returns	`DATE`

This returned DATE will be the live clock of the system.

Example 9. date.realtime()

Query

RETURN date.realtime() AS currentDate

Result
currentDate
`2022-06-14`
Rows: 1

Example 10. date.realtime()

Query

RETURN date.realtime('America/Los Angeles') AS currentDateInLA

Result
currentDateInLA
`2022-06-14`
Rows: 1

date.statement()

Details
Syntax	`date.statement([ timezone ])`
Description	Returns the current `DATE` instant using the statement clock.
Arguments	Name	Type	Description
	`timezone`	`ANY`	A string value representing a timezone.
Returns	`DATE`

This returned DATE 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.

Example 11. date.statement()

Query

RETURN date.statement() AS currentDate

Result
currentDate
`2022-06-14`
Rows: 1

date.transaction()

Details
Syntax	`date.transaction([ timezone ])`
Description	Returns the current `DATE` instant using the transaction clock.
Arguments	Name	Type	Description
	`timezone`	`ANY`	A string value representing a timezone.
Returns	`DATE`

The returned DATE will be the same for each invocation within the same transaction. However, a different value may be produced for different transactions.

Example 12. date.transaction()

Query

RETURN date.transaction() AS currentDate

Result
currentDate
`2022-06-14`
Rows: 1

date.truncate()

Details
Syntax	`date.truncate(unit [, input, fields])`
Description	Truncates the given temporal value to a `DATE` instant using the specified unit.
Arguments	Name	Type	Description
	`unit`	`STRING`	A string representing one of the following: 'day', 'week', 'month', 'weekYear', 'quarter', 'year', 'decade', 'century', 'millennium'.
	`input`	`ANY`	The date to be truncated using either `ZONED DATETIME`, `LOCAL DATETIME`, or `DATE`.
	`fields`	`MAP`	A list of time components smaller than those specified in `unit` to preserve during truncation.
Returns	`DATE`

date.truncate() returns the DATE 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 DATE returned will have all components that are smaller 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 smaller than the truncation unit. This will have the effect of overriding the default values which would otherwise have been set for these smaller components. For example, day — with some value x — may be provided when the truncation unit STRING is 'year' in order to ensure the returned value has the day set to x instead of the default day (which is 1).

Considerations
Any component that is provided in `fields` must be smaller than `unit`; i.e. if `unit` `STRING` is `'day'`, `fields` cannot contain information pertaining to a month.
Any component that is not contained in `fields` and which is smaller than `unit` will be set to its minimal value.
If `fields` is not provided, all components of the returned value which are smaller than `unit` will be set to their default values.
If `input` is not provided, it will be set to the current date, i.e. `date.truncate(unit)` is equivalent of `date.truncate(unit, date())`.

Example 13. date.truncate()

Query

WITH
  datetime({
    year: 2017, month: 11, day: 11,
    hour: 12, minute: 31, second: 14, nanosecond: 645876123,
    timezone: '+01:00'
  }) AS d
RETURN
  date.truncate('millennium', d) AS truncMillenium,
  date.truncate('century', d) AS truncCentury,
  date.truncate('decade', d) AS truncDecade,
  date.truncate('year', d, {day: 5}) AS truncYear,
  date.truncate('weekYear', d) AS truncWeekYear,
  date.truncate('quarter', d) AS truncQuarter,
  date.truncate('month', d) AS truncMonth,
  date.truncate('week', d, {dayOfWeek: 2}) AS truncWeek,
  date.truncate('day', d) AS truncDay

Result
truncMillenium	truncCentury	truncDecade	truncYear	truncWeekYear	truncQuarter	truncMonth	truncWeek	truncDay
`2000-01-01`	`2000-01-01`	`2010-01-01`	`2017-01-05`	`2017-01-02`	`2017-10-01`	`2017-11-01`	`2017-11-07`	`2017-11-11`
Rows: 1

datetime()

Details
Syntax	`datetime([ input ])`
Description	Creates a `ZONED DATETIME` instant.
Arguments	Name	Type	Description
	`input`	`ANY`	Either a string representation of a temporal value, a map containing the single key 'timezone', or a map containing temporal values ('year', 'month', 'day', 'hour', 'minute', 'second', 'millisecond', 'microsecond', 'nanosecond', 'timezone') as components.
Returns	`ZONED DATETIME`

Temporal components
Name	Description
`year`	An expression consisting of at least four digits that specifies the year.
`month`	An integer between `1` and `12` that specifies the month.
`day`	An integer between `1` and `31` that specifies the day of the month.
`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 timezone.
`epochSeconds`	A numeric value representing the number of seconds from the UNIX epoch in the UTC timezone.
`epochMillis`	A numeric value representing the number of milliseconds from the UNIX epoch in the UTC timezone.

Considerations
If no parameters are provided, `datetime()` must be invoked (`datetime({})` is invalid).
The month component will default to `1` if `month` is omitted.
The day of the month component will default to `1` if `day` is omitted.
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 timezone 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 smallest components in the set `year`, `month`, `day`, `hour`, `minute`, and `second` may be omitted; i.e. it is possible to specify only `year`, `month` and `day`, but specifying `year`, `month`, `day` and `minute` is not permitted.
One or more of `millisecond`, `microsecond` and `nanosecond` can only be specified as long as `second` is also specified.
String representations of temporal values must comply with the format defined for dates, times and time zones.
String representations of temporal values must denote a valid date; i.e. a temporal value denoting `30 February 2001` is invalid.
If any of the optional parameters are provided, these will override the corresponding components of `datetime`, `date` and/or `time`.
`datetime(dd)` may be written instead of `datetime({datetime: dd})`.
Selecting a `ZONED TIME` or `ZONED DATETIME` value as the `time` component also selects its timezone. If a `LOCAL TIME` or `LOCAL DATETIME` is selected instead, the default timezone is used. In any case, the timezone can be overridden explicitly.
Selecting a `ZONED DATETIME` as the `datetime` component and overwriting the timezone will adjust the local time to keep the same point in time.
Selecting a `ZONED DATETIME` or `ZONED TIME` as the `time` component and overwriting the timezone will adjust the local time to keep the same point in time.
`epochSeconds`/`epochMillis` may be used in conjunction with `nanosecond`.
`datetime(null)` returns null.

Example 14. .datetime() to get the current datetime (no parameters provided)

Query

RETURN datetime() AS currentDateTime

The current date and time using the local timezone is returned.

Result
currentDateTime
`2022-06-14T10:02:28.192Z`
Rows: 1

Example 15. datetime() with provided timezone

Query

RETURN datetime({timezone: 'America/Los Angeles'}) AS currentDateTimeInLA

The current date and time of day in California is returned.

Result
currentDateTimeInLA
`2022-06-14T03:02:28.238-07:00[America/Los_Angeles]`
Rows: 1

Creating `ZONED DATETIME` values

Example 16. datetime() - Creating a calendar (Year-Month-Day) ZONED DATETIME

Query

UNWIND [
datetime({year: 1984, month: 10, day: 11, hour: 12, minute: 31, second: 14, millisecond: 123, microsecond: 456, nanosecond: 789}),
datetime({year: 1984, month: 10, day: 11, hour: 12, minute: 31, second: 14, millisecond: 645, timezone: '+01:00'}),
datetime({year: 1984, month: 10, day: 11, hour: 12, minute: 31, second: 14, nanosecond: 645876123, timezone: 'Europe/Stockholm'}),
datetime({year: 1984, month: 10, day: 11, hour: 12, minute: 31, second: 14, timezone: '+01:00'}),
datetime({year: 1984, month: 10, day: 11, hour: 12, minute: 31, second: 14}),
datetime({year: 1984, month: 10, day: 11, hour: 12, minute: 31, timezone: 'Europe/Stockholm'}),
datetime({year: 1984, month: 10, day: 11, hour: 12, timezone: '+01:00'}),
datetime({year: 1984, month: 10, day: 11, timezone: 'Europe/Stockholm'})
] AS theDate
RETURN theDate

Result
theDate
`1984-10-11T12:31:14.123456789Z`
`1984-10-11T12:31:14.645+01:00`
`1984-10-11T12:31:14.645876123+01:00[Europe/Stockholm]`
`1984-10-11T12:31:14+01:00`
`1984-10-11T12:31:14Z`
`1984-10-11T12:31+01:00[Europe/Stockholm]`
`1984-10-11T12:00+01:00`
`1984-10-11T00:00+01:00[Europe/Stockholm]`
Rows: 8

Example 17. datetime() - Creating a week (Year-Week-Day) ZONED DATETIME

Query

UNWIND [
datetime({year: 1984, week: 10, dayOfWeek: 3, hour: 12, minute: 31, second: 14, millisecond: 645}),
datetime({year: 1984, week: 10, dayOfWeek: 3, hour: 12, minute: 31, second: 14, microsecond: 645876, timezone: '+01:00'}),
datetime({year: 1984, week: 10, dayOfWeek: 3, hour: 12, minute: 31, second: 14, nanosecond: 645876123, timezone: 'Europe/Stockholm'}),
datetime({year: 1984, week: 10, dayOfWeek: 3, hour: 12, minute: 31, second: 14, timezone: 'Europe/Stockholm'}),
datetime({year: 1984, week: 10, dayOfWeek: 3, hour: 12, minute: 31, second: 14}),
datetime({year: 1984, week: 10, dayOfWeek: 3, hour: 12, timezone: '+01:00'}),
datetime({year: 1984, week: 10, dayOfWeek: 3, timezone: 'Europe/Stockholm'})
] AS theDate
RETURN theDate

Result
theDate
`1984-03-07T12:31:14.645Z`
`1984-03-07T12:31:14.645876+01:00`
`1984-03-07T12:31:14.645876123+01:00[Europe/Stockholm]`
`1984-03-07T12:31:14+01:00[Europe/Stockholm]`
`1984-03-07T12:31:14Z`
`1984-03-07T12:00+01:00`
`1984-03-07T00:00+01:00[Europe/Stockholm]`
Rows: 7

Example 18. datetime() - Creating a quarter (Year-Quarter-Day) ZONED DATETIME

Query

UNWIND [
datetime({year: 1984, quarter: 3, dayOfQuarter: 45, hour: 12, minute: 31, second: 14, microsecond: 645876}),
datetime({year: 1984, quarter: 3, dayOfQuarter: 45, hour: 12, minute: 31, second: 14, timezone: '+01:00'}),
datetime({year: 1984, quarter: 3, dayOfQuarter: 45, hour: 12, timezone: 'Europe/Stockholm'}),
datetime({year: 1984, quarter: 3, dayOfQuarter: 45})
] AS theDate
RETURN theDate

Result
theDate
`1984-08-14T12:31:14.645876Z`
`1984-08-14T12:31:14+01:00`
`1984-08-14T12:00+02:00[Europe/Stockholm]`
`1984-08-14T00:00Z`
Rows: 4

Example 19. datetime() - Creating an ordinal (Year-Day) ZONED DATETIME

Query

UNWIND [
datetime({year: 1984, ordinalDay: 202, hour: 12, minute: 31, second: 14, millisecond: 645}),
datetime({year: 1984, ordinalDay: 202, hour: 12, minute: 31, second: 14, timezone: '+01:00'}),
datetime({year: 1984, ordinalDay: 202, timezone: 'Europe/Stockholm'}),
datetime({year: 1984, ordinalDay: 202})
] AS theDate
RETURN theDate

Result
theDate
`1984-07-20T12:31:14.645Z`
`1984-07-20T12:31:14+01:00`
`1984-07-20T00:00+02:00[Europe/Stockholm]`
`1984-07-20T00:00Z`
Rows: 4

Example 20. datetime() - Creating a ZONED DATETIME from a STRING

Query

UNWIND [
datetime('2015-07-21T21:40:32.142+0100'),
datetime('2015-W30-2T214032.142Z'),
datetime('2015T214032-0100'),
datetime('20150721T21:40-01:30'),
datetime('2015-W30T2140-02'),
datetime('2015202T21+18:00'),
datetime('2015-07-21T21:40:32.142[Europe/London]'),
datetime('2015-07-21T21:40:32.142-04[America/New_York]')
] AS theDate
RETURN theDate

Result
theDate
`2015-07-21T21:40:32.142+01:00`
`2015-07-21T21:40:32.142Z`
`2015-01-01T21:40:32-01:00`
`2015-07-21T21:40-01:30`
`2015-07-20T21:40-02:00`
`2015-07-21T21:00+18:00`
`2015-07-21T21:40:32.142+01:00[Europe/London]`
`2015-07-21T21:40:32.142-04:00[America/New_York]`
Rows: 8

Example 21. datetime() - Creating a ZONED DATETIME using other temporal values as components

The following query shows the various usages of datetime({date [, year, ..., timezone]}).

Query

WITH date({year: 1984, month: 10, day: 11}) AS dd
RETURN
  datetime({date: dd, hour: 10, minute: 10, second: 10}) AS dateHHMMSS,
  datetime({date: dd, hour: 10, minute: 10, second: 10, timezone:'+05:00'}) AS dateHHMMSSTimezone,
  datetime({date: dd, day: 28, hour: 10, minute: 10, second: 10}) AS dateDDHHMMSS,
  datetime({date: dd, day: 28, hour: 10, minute: 10, second: 10, timezone:'Pacific/Honolulu'}) AS dateDDHHMMSSTimezone

Result
dateHHMMSS	dateHHMMSSTimezone	dateDDHHMMSS	dateDDHHMMSSTimezone
`1984-10-11T10:10:10Z`	`1984-10-11T10:10:10+05:00`	`1984-10-28T10:10:10Z`	`1984-10-28T10:10:10-10:00[Pacific/Honolulu]`
Rows: 1

Example 22. datetime() - Creating a ZONED DATETIME using other temporal values as components

The following query shows the various usages of datetime({time [, year, …, timezone]}).

Query

WITH time({hour: 12, minute: 31, second: 14, microsecond: 645876, timezone: '+01:00'}) AS tt
RETURN
  datetime({year: 1984, month: 10, day: 11, time: tt}) AS YYYYMMDDTime,
  datetime({year: 1984, month: 10, day: 11, time: tt, timezone:'+05:00'}) AS YYYYMMDDTimeTimezone,
  datetime({year: 1984, month: 10, day: 11, time: tt, second: 42}) AS YYYYMMDDTimeSS,
  datetime({year: 1984, month: 10, day: 11, time: tt, second: 42, timezone: 'Pacific/Honolulu'}) AS YYYYMMDDTimeSSTimezone

Result
YYYYMMDDTime	+YYYYMMDDTimeTimezone	YYYYMMDDTimeSS	YYYYMMDDTimeSSTimezone
`1984-10-11T12:31:14.645876+01:00`	`1984-10-11T16:31:14.645876+05:00`	`1984-10-11T12:31:42.645876+01:00`	`1984-10-11T01:31:42.645876-10:00[Pacific/Honolulu]`
Rows: 1

Example 23. datetime() - Creating a ZONED DATETIME using other temporal values as components

The following query shows the various usages of datetime({date, time [, year, ..., timezone]}); i.e. combining a DATE and a ZONED TIME value to create a single ZONED DATETIME value.

Query

WITH
  date({year: 1984, month: 10, day: 11}) AS dd,
  localtime({hour: 12, minute: 31, second: 14, millisecond: 645}) AS tt
RETURN
  datetime({date: dd, time: tt}) AS dateTime,
  datetime({date: dd, time: tt, timezone: '+05:00'}) AS dateTimeTimezone,
  datetime({date: dd, time: tt, day: 28, second: 42}) AS dateTimeDDSS,
  datetime({date: dd, time: tt, day: 28, second: 42, timezone: 'Pacific/Honolulu'}) AS dateTimeDDSSTimezone

Result
dateTime	dateTimeTimezone	dateTimeDDSS	dateTimeDDSSTimezone
`1984-10-11T12:31:14.645Z`	`1984-10-11T12:31:14.645+05:00`	`1984-10-28T12:31:42.645Z`	`1984-10-28T12:31:42.645-10:00[Pacific/Honolulu]`
Rows: 1

Example 24. datetime() - Creating a ZONED DATETIME using other temporal values as components

The following query shows the various usages of datetime({datetime [, year, ..., timezone]}).

Query

WITH
  datetime({
    year: 1984, month: 10, day: 11,
    hour: 12,
    timezone: 'Europe/Stockholm'
  }) AS dd
RETURN
  datetime({datetime: dd}) AS dateTime,
  datetime({datetime: dd, timezone: '+05:00'}) AS dateTimeTimezone,
  datetime({datetime: dd, day: 28, second: 42}) AS dateTimeDDSS,
  datetime({datetime: dd, day: 28, second: 42, timezone: 'Pacific/Honolulu'}) AS dateTimeDDSSTimezone

Result
dateTime	dateTimeTimezone	dateTimeDDSS	dateTimeDDSSTimezone
`1984-10-11T12:00+01:00[Europe/Stockholm]`	`1984-10-11T16:00+05:00`	`1984-10-28T12:00:42+01:00[Europe/Stockholm]`	`1984-10-28T01:00:42-10:00[Pacific/Honolulu]`
Rows: 1

Example 25. datetime() - Creating a ZONED DATETIME from UNIX epoch (epocSeconds)

datetime() returns the ZONED DATETIME value at the specified number of seconds or milliseconds from the UNIX epoch in the UTC timezone.

Conversions to other temporal instant types from UNIX epoch representations can be achieved by transforming a ZONED DATETIME value to one of these types.

Query

RETURN datetime({epochSeconds: timestamp() / 1000, nanosecond: 23}) AS theDate

Result
theDate
`2022-06-14T10:02:30.000000023Z`
Rows: 1

Example 26. datetime() - Creating a ZONED DATETIME from UNIX epoch (epocMillis)

Query

RETURN datetime({epochMillis: 424797300000}) AS theDate

Result
theDate
`1983-06-18T15:15Z`
Rows: 1

datetime.fromEpoch()

Details
Syntax	`datetime.fromEpoch(seconds, nanoseconds)`
Description	Creates a `ZONED DATETIME` given the seconds and nanoseconds since the start of the epoch.
Arguments	Name	Type	Description
	`seconds`	`INTEGER \| FLOAT`	The number of seconds from the UNIX epoch in the UTC timezone.
	`nanoseconds`	`INTEGER \| FLOAT`	The number of nanoseconds from the UNIX epoch in the UTC timezone. This can be added to seconds.
Returns	`ZONED DATETIME`

Example 27. datetime.fromEpoch()

Query

WITH datetime.fromEpoch(1683000000, 123456789) AS dateTimeFromEpoch
RETURN dateTimeFromEpoch

Result
dateTimeFromEpoch
`2023-05-02T04:00:00.123456789Z`
Rows: 1

datetime.fromEpochMillis()

Details
Syntax	`datetime.fromEpochMillis(milliseconds)`
Description	Creates a `ZONED DATETIME` given the milliseconds since the start of the epoch.
Arguments	Name	Type	Description
	`milliseconds`	`INTEGER \| FLOAT`	The number of milliseconds from the UNIX epoch in the UTC timezone.
Returns	`ZONED DATETIME`

Example 28. datetime.fromEpochMillis()

Query

WITH datetime.fromEpochMillis(1724198400000) AS dateTimeFromMillis
RETURN dateTimeFromMillis

Result
dateTimeFromMillis
`2024-08-21T00:00Z`
Rows: 1

datetime.realtime()

Details
Syntax	`datetime.realtime([ timezone ])`
Description	Returns the current `ZONED DATETIME` instant using the realtime clock.
Arguments	Name	Type	Description
	`timezone`	`ANY`	A string value representing a timezone.
Returns	`ZONED DATETIME`

The returned ZONED DATETIME will be the live clock of the system.

Example 29. datetime.realtime()

Query

RETURN datetime.realtime() AS currentDateTime

Result
currentDateTime
`2022-06-14T10:02:28.494444Z`
Rows: 1

datetime.statement()

Details
Syntax	`datetime.statement([ timezone ])`
Description	Returns the current `ZONED DATETIME` instant using the statement clock.
Arguments	Name	Type	Description
	`timezone`	`ANY`	A string value representing a timezone.
Returns	`ZONED DATETIME`

This returned ZONED DATETIME 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.

Example 30. datetime.statement()

Query

RETURN datetime.statement() AS currentDateTime

Result
currentDateTime
`2022-06-14T10:02:28.395Z`
Rows: 1

datetime.transaction()

Details
Syntax	`datetime.transaction([ timezone ])`
Description	Returns the current `ZONED DATETIME` instant using the transaction clock.
Arguments	Name	Type	Description
	`timezone`	`ANY`	A string value representing a timezone.
Returns	`ZONED DATETIME`

The returned ZONED DATETIME value will be the same for each invocation within the same transaction. However, a different value may be produced for different transactions.

Example 31. datetime.transaction()

Query

RETURN datetime.transaction() AS currentDateTime

Result
currentDateTime
`2022-06-14T10:02:28.290Z`
Rows: 1

Example 32. datetime.transaction()

Query

RETURN datetime.transaction('America/Los Angeles') AS currentDateTimeInLA

Result
currentDateTimeInLA
`2022-06-14T03:02:28.338-07:00[America/Los_Angeles]`
Rows: 1

datetime.truncate()

Details
Syntax	`datetime.truncate(unit [, input, fields])`
Description	Truncates the given temporal value to a `ZONED DATETIME` instant using the specified unit.
Arguments	Name	Type	Description
	`unit`	`STRING`	A string representing one of the following: 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day', 'week', 'month', 'weekYear', 'quarter', 'year', 'decade', 'century', 'millennium'.
	`input`	`ANY`	The date to be truncated using either `ZONED DATETIME`, `LOCAL DATETIME`, or `DATE`.
	`fields`	`MAP`	A list of time components smaller than those specified in `unit` to preserve during truncation.
Returns	`ZONED DATETIME`

datetime.truncate() returns the ZONED DATETIME 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 ZONED DATETIME returned will have all components that are smaller than the specified truncation unit set to their default values.

Considerations
`input` cannot be a `DATE` value if `unit` is one of: `'hour'`, `'minute'`, `'second'`, `'millisecond'`, `'microsecond'`.
The timezone of `input` may be overridden; for example, `datetime.truncate('minute', input, {timezone: '+0200'})`.
If `input` is one of `ZONED TIME`, `ZONED DATETIME` — a value with a timezone — and the timezone is overridden, no time conversion occurs.
If `input` is one of `LOCAL DATETIME`, `DATE` — a value without a timezone — and the timezone is not overridden, the configured default timezone will be used.
Any component that is provided in `fields` must be smaller than `unit`; i.e. if `unit` is `'day'`, `fields` cannot contain information pertaining to a month.
Any component that is not contained in `fields` and which is smaller than `unit` will be set to its minimal value.
If `fields` is not provided, all components of the returned value which are smaller than `unit` will be set to their default values.
If `input` is not provided, it will be set to the current date, time and timezone, i.e. `datetime.truncate(unit)` is equivalent of `datetime.truncate(unit, datetime())`.

Example 33. datetime.truncate()

Query

WITH
  datetime({
    year:2017, month:11, day:11,
    hour:12, minute:31, second:14, nanosecond: 645876123,
    timezone: '+03:00'
  }) AS d
RETURN
  datetime.truncate('millennium', d, {timezone: 'Europe/Stockholm'}) AS truncMillenium,
  datetime.truncate('year', d, {day: 5}) AS truncYear,
  datetime.truncate('month', d) AS truncMonth,
  datetime.truncate('day', d, {millisecond: 2}) AS truncDay,
  datetime.truncate('hour', d) AS truncHour,
  datetime.truncate('second', d) AS truncSecond

Result
truncMillenium	truncYear	truncMonth	truncDay	truncHour	truncSecond
`2000-01-01T00:00+01:00[Europe/Stockholm]`	`2017-01-05T00:00+03:00`	`2017-11-01T00:00+03:00`	`2017-11-11T00:00:00.002+03:00`	`2017-11-11T12:00+03:00`	`2017-11-11T12:31:14+03:00`
Rows: 1

localdatetime()

Details
Syntax	`localdatetime([ input ])`
Description	Creates a `LOCAL DATETIME` instant.
Arguments	Name	Type	Description
	`input`	`ANY`	Either a string representation of a temporal value, a map containing the single key 'timezone', or a map containing temporal values ('year', 'month', 'day', 'hour', 'minute', 'second', 'millisecond', 'microsecond', 'nanosecond') as components.
Returns	`LOCAL DATETIME`

Temporal components
Name	Description
`A single map consisting of the following:`
`year`	An expression consisting of at least four digits that specifies the year.
`month`	An integer between `1` and `12` that specifies the month.
`day`	An integer between `1` and `31` that specifies the day of the month.
`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 no parameters are provided, `localdatetime()` must be invoked (localdatetime({}) is invalid).
The month component will default to `1` if `month` is omitted.
The day of the month component will default to `1` if `day` is omitted.
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 smallest components in the set `year`, `month`, `day`, `hour`, `minute`, and `second` may be omitted; i.e. it is possible to specify only `year`, `month` and `day`, but specifying `year`, `month`, `day` and `minute` is not permitted.
One or more of `millisecond`, `microsecond` and `nanosecond` can only be specified as long as `second` is also specified.
String representations of temporal values must comply with the format defined for dates and times.
String representations of temporal values must denote a valid date; i.e. a temporal value denoting `30 February 2001` is invalid.
`localdatetime(null)` returns null.
If any of the optional parameters are provided, these will override the corresponding components of `datetime`, `date` and/or `time`.
`localdatetime(dd)` may be written instead of `localdatetime({datetime: dd})`.

Example 34. localdatetime() - to get current local date and time (no parameters)

Query

RETURN localdatetime() AS now

The current local date and time (i.e. in the local timezone) is returned.

Result
now
`2022-06-14T10:02:30.447`
Rows: 1

Example 35. localdatetime() with timezone

Query

RETURN localdatetime({timezone: 'America/Los Angeles'}) AS now

The current local date and time in California is returned.

Result
now
`2022-06-14T03:02:30.482`
Rows: 1

Creating `LOCAL DATETIME` values

Example 36. localdatetime() - Creating a calendar (Year-Month-Day) LOCAL DATETIME

Query

RETURN
  localdatetime({
    year: 1984, month: 10, day: 11,
    hour: 12, minute: 31, second: 14, millisecond: 123, microsecond: 456, nanosecond: 789
  }) AS theDate

Result
theDate
`1984-10-11T12:31:14.123456789`
Rows: 1

Example 37. localdatetime() - Creating a week (Year-Week-Day) LOCAL DATETIME

Query

RETURN
  localdatetime({
    year: 1984, week: 10, dayOfWeek: 3,
    hour: 12, minute: 31, second: 14, millisecond: 645
  }) AS theDate

Result
theDate
`1984-03-07T12:31:14.645`
Rows: 1

Example 38. localdatetime() - Creating a quarter (Year-Quarter-Day) ZONED DATETIME

Query

RETURN
  localdatetime({
    year: 1984, quarter: 3, dayOfQuarter: 45,
    hour: 12, minute: 31, second: 14, nanosecond: 645876123
  }) AS theDate

Result
theDate
`1984-08-14T12:31:14.645876123`
Rows: 1

Example 39. localdatetime() - Creating an ordinal (Year-Day) LOCAL DATETIME

Query

RETURN
  localdatetime({
    year: 1984, ordinalDay: 202,
    hour: 12, minute: 31, second: 14, microsecond: 645876
  }) AS theDate

Result
theDate
`1984-07-20T12:31:14.645876`
Rows: 1

Example 40. localdatetime() - Creating a LOCAL DATETIME from a STRING

Query

UNWIND [
localdatetime('2015-07-21T21:40:32.142'),
localdatetime('2015-W30-2T214032.142'),
localdatetime('2015-202T21:40:32'),
localdatetime('2015202T21')
] AS theDate
RETURN theDate

Result
theDate
`2015-07-21T21:40:32.142`
`2015-07-21T21:40:32.142`
`2015-07-21T21:40:32`
`2015-07-21T21:00`
Rows: 4

Example 41. localdatetime() - Creating a LOCAL DATETIME using other temporal values as components

The following query shows the various usages of localdatetime({date [, year, ..., nanosecond]}).

Query

WITH date({year: 1984, month: 10, day: 11}) AS dd
RETURN
  localdatetime({date: dd, hour: 10, minute: 10, second: 10}) AS dateHHMMSS,
  localdatetime({date: dd, day: 28, hour: 10, minute: 10, second: 10}) AS dateDDHHMMSS

Result
dateHHMMSS	dateDDHHMMSS
`1984-10-11T10:10:10`	`1984-10-28T10:10:10`
Rows: 1

Example 42. localdatetime() - Creating a LOCAL DATETIME using other temporal values as components

The following query shows the various usages of localdatetime({time [, year, ..., nanosecond]}).

Query

WITH time({hour: 12, minute: 31, second: 14, microsecond: 645876, timezone: '+01:00'}) AS tt
RETURN
  localdatetime({year: 1984, month: 10, day: 11, time: tt}) AS YYYYMMDDTime,
  localdatetime({year: 1984, month: 10, day: 11, time: tt, second: 42}) AS YYYYMMDDTimeSS

Result
YYYYMMDDTime	YYYYMMDDTimeSS
`1984-10-11T12:31:14.645876`	`1984-10-11T12:31:42.645876`
Rows: 1

Example 43. localdatetime() - Creating a LOCAL DATETIME using other temporal values as components

The following query shows the various usages of localdatetime({date, time [, year, ..., nanosecond]}); i.e. combining a DATE and a ZONED TIME value to create a single LOCAL DATETIME value.

Query

WITH
  date({year: 1984, month: 10, day: 11}) AS dd,
  time({hour: 12, minute: 31, second: 14, microsecond: 645876, timezone: '+01:00'}) AS tt
RETURN
  localdatetime({date: dd, time: tt}) AS dateTime,
  localdatetime({date: dd, time: tt, day: 28, second: 42}) AS dateTimeDDSS

Result
dateTime	dateTimeDDSS
`1984-10-11T12:31:14.645876`	`1984-10-28T12:31:42.645876`
Rows: 1

Example 44. localdatetime() - Creating a LOCAL DATETIME using other temporal values as components

The following query shows the various usages of localdatetime({datetime [, year, ..., nanosecond]}).

Query

WITH
  datetime({
    year: 1984, month: 10, day: 11,
    hour: 12,
    timezone: '+01:00'
  }) AS dd
RETURN
  localdatetime({datetime: dd}) AS dateTime,
  localdatetime({datetime: dd, day: 28, second: 42}) AS dateTimeDDSS

Result
dateTime	dateTimeDDSS
`1984-10-11T12:00`	`1984-10-28T12:00:42`
Rows: 1

localdatetime.realtime()

Details
Syntax	`localdatetime.realtime([ timezone ])`
Description	Returns the current `LOCAL DATETIME` instant using the realtime clock.
Arguments	Name	Type	Description
	`timezone`	`ANY`	A string value representing a timezone.
Returns	`LOCAL DATETIME`

The returned LOCAL DATETIME will be the live clock of the system.

Example 45. localdatetime.realtime()

Query

RETURN localdatetime.realtime() AS now

Result
now
`2022-06-14T10:02:30.647817`
Rows: 1

Example 46. localdatetime.realtime()

Query

RETURN localdatetime.realtime('America/Los Angeles') AS nowInLA

Result
nowInLA
`2022-06-14T03:02:30.691099`
Rows: 1

localdatetime.statement()

Details
Syntax	`localdatetime.statement([ timezone ])`
Description	Returns the current `LOCAL DATETIME` instant using the statement clock.
Arguments	Name	Type	Description
	`timezone`	`ANY`	A string value representing a timezone.
Returns	`LOCAL DATETIME`

The returned LOCAL DATETIME 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.

Example 47. localdatetime.statement()

Query

RETURN localdatetime.statement() AS now

Result
now
`2022-06-14T10:02:30.570`
Rows: 1

localdatetime.transaction()

Details
Syntax	`localdatetime.transaction([ timezone ])`
Description	Returns the current `LOCAL DATETIME` instant using the transaction clock.
Arguments	Name	Type	Description
	`timezone`	`ANY`	A string value representing a timezone.
Returns	`LOCAL DATETIME`

The returned LOCAL DATETIME will be the same for each invocation within the same transaction. However, a different value may be produced for different transactions.

Example 48. localdatetime.transaction()

Query

RETURN localdatetime.transaction() AS now

Result
now
`2022-06-14T10:02:30.532`
Rows: 1

localdatetime.truncate()

Details
Syntax	`localdatetime.truncate(unit [, input, fields])`
Description	Truncates the given temporal value to a `LOCAL DATETIME` instant using the specified unit.
Arguments	Name	Type	Description
	`unit`	`STRING`	A string representing one of the following: 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day', 'week', 'month', 'weekYear', 'quarter', 'year', 'decade', 'century', 'millennium'.
	`input`	`ANY`	The date to be truncated using either `ZONED DATETIME`, `LOCAL DATETIME`, or `DATE`.
	`fields`	`MAP`	A list of time components smaller than those specified in `unit` to preserve during truncation.
Returns	`LOCAL DATETIME`

localdatetime.truncate() returns the LOCAL DATETIME 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 LOCAL DATETIME returned will have all components that are smaller than the specified truncation unit set to their default values.

Considerations
`input` cannot be a `DATE` value if `unit` is one of: `'hour'`, `'minute'`, `'second'`, `'millisecond'`, `'microsecond'`.
Any component that is provided in `fields` must be smaller than `input`; i.e. if `input` is `'day'`, `fields` cannot contain information pertaining to a month.
Any component that is not contained in `fields` and which is smaller than `unit` will be set to its minimal value.
If `fields` is not provided, all components of the returned value which are smaller than `unit` will be set to their default values.
If `input` is not provided, it will be set to the current date and time, i.e. `localdatetime.truncate(unit)` is equivalent of `localdatetime.truncate(unit, localdatetime())`.

Example 49. localdatetime.truncate()

Query

WITH
  localdatetime({
    year: 2017, month: 11, day: 11,
    hour: 12, minute: 31, second: 14, nanosecond: 645876123
  }) AS d
RETURN
  localdatetime.truncate('millennium', d) AS truncMillenium,
  localdatetime.truncate('year', d, {day: 2}) AS truncYear,
  localdatetime.truncate('month', d) AS truncMonth,
  localdatetime.truncate('day', d) AS truncDay,
  localdatetime.truncate('hour', d, {nanosecond: 2}) AS truncHour,
  localdatetime.truncate('second', d) AS truncSecond

Result
truncMillenium	truncYear	truncMonth	truncDay	truncHour	truncSecond
`2000-01-01T00:00`	`2017-01-02T00:00`	`2017-11-01T00:00`	`2017-11-11T00:00`	`2017-11-11T12:00:00.000000002`	`2017-11-11T12:31:14`
Rows: 1

localtime()

Details
Syntax	`localtime([ input ])`
Description	Creates a `LOCAL TIME` instant.
Arguments	Name	Type	Description
	`input`	`ANY`	Either a string representation of a temporal value, a map containing the single key 'timezone', or a map containing temporal values ('hour, 'minute', 'second', 'millisecond', 'microsecond', 'nanosecond' as components.
Returns	`LOCAL TIME`

Temporal components
Name	Description
`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 no parameters are provided, `localtime()` must be invoked (`localtime({})` is invalid).
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 smallest 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.
String representations of temporal values must comply with the format defined for times.
String representations of temporal values must denote a valid time; i.e. a temporal value denoting `13:46:64` is invalid.
`localtime(null)` returns null.
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})`.

Example 50. localtime() to get the current time (no parameters)

Query

RETURN localtime() AS now

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

Result
now
`10:02:31.596`
Rows: 1

Example 51. localtime() with timezone

Query

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

The current local time in California is returned.

Result
nowInLA
`03:02:31.629`
Rows: 1

Creating `LOCAL TIME` values

Example 52. localtime()

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

Result
theTime
`12:31:14.123456789`
`12:31:14`
`12:00`
Rows: 3

Example 53. localtime() - Creating a LOCAL TIME from a STRING

Query

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

Result
theTime
`21:40:32.142`
`21:40:32.142`
`21:40`
`21:00`
Rows: 4

Example 54. localtime() - Creating a LOCAL TIME using other temporal values as components

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

Result
timeOnly	timeSS
`12:31:14.645876`	`12:31:42.645876`
Rows: 1

localtime.realtime()

Details
Syntax	`localtime.realtime([ timezone ])`
Description	Returns the current `LOCAL TIME` instant using the realtime clock.
Arguments	Name	Type	Description
	`timezone`	`ANY`	A string value representing a timezone.
Returns	`LOCAL TIME`

The returned LOCAL TIME will be the live clock of the system.

Example 55. localtime.realtime()

Query

RETURN localtime.realtime() AS now

Result
now
`10:02:31.806895`
Rows: 1

localtime.statement()

Details
Syntax	`localtime.statement([ timezone ])`
Description	Returns the current `LOCAL TIME` instant using the statement clock.
Arguments	Name	Type	Description
	`timezone`	`ANY`	A string value representing a timezone.
Returns	`LOCAL TIME`

This returned LOCAL TIME 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.

Example 56. localtime.statement()

Query

RETURN localtime.statement() AS now

Result
now
`10:02:31.697`
Rows: 1

Example 57. localtime.statement()

Query

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

Result
nowInLA
`03:02:31.737`
Rows: 1

localtime.transaction()

Details
Syntax	`localtime.transaction([ timezone ])`
Description	Returns the current `LOCAL TIME` instant using the transaction clock.
Arguments	Name	Type	Description
	`timezone`	`ANY`	A string value representing a timezone.
Returns	`LOCAL TIME`

The returned LOCAL TIME will be the same for each invocation within the same transaction. However, a different value may be produced for different transactions.

Example 58. localtime.transaction()

Query

RETURN localtime.transaction() AS now

Result
now
`10:02:31.662`
Rows: 1

localtime.truncate()

Details
Syntax	`localtime.truncate(unit [, input, fields])`
Description	Truncates the given temporal value to a `LOCAL TIME` instant using the specified unit.
Arguments	Name	Type	Description
	`unit`	`STRING`	A string representing one of the following: 'day', 'week', 'month', 'weekYear', 'quarter', 'year', 'decade', 'century', 'millennium'.
	`input`	`ANY`	The date to be truncated using either `ZONED DATETIME`, `LOCAL DATETIME`, `LOCAL TIME`, or `DATE`.
	`fields`	`MAP`	A list of time components smaller than those specified in `unit` to preserve during truncation.
Returns	`LOCAL TIME`

localtime.truncate() returns the LOCAL 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 LOCAL TIME returned will have all components that are smaller 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 smaller than the truncation unit. This will have the effect of overriding the default values which would otherwise have been set for these smaller components. For example, minute — with some value x — may be provided when the truncation unit string is 'hour' in order to ensure the returned value has the minute set to x instead of the default minute (which is 1).

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 `input`. However, the timezone of `input` is retained.
Any component that is provided in `fields` must be smaller than `unit`; i.e. if `unit` is `'second'`, `fields` cannot contain information pertaining to a minute.
Any component that is not contained in `fields` and which is smaller than `unit` will be set to its minimal value.
If `fields` is not provided, all components of the returned value which are smaller than `unit` will be set to their default values.
If `input` is not provided, it will be set to the current time, i.e. `localtime.truncate(unit)` is equivalent of `localtime.truncate(unit, localtime())`.

Example 59. localtime.truncate()

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

Result
truncDay	truncHour	truncMinute	truncSecond	truncMillisecond	truncMicrosecond
`00:00:00`	`12:00:00`	`12:31:00.002000000`	`12:31:14`	`12:31:14.645000000`	`12:31:14.645876000`
Rows: 1

time()

Details
Syntax	`time([ input ])`
Description	Creates a `ZONED TIME` instant.
Arguments	Name	Type	Description
	`input`	`ANY`	Either a string representation of a temporal value, a map containing the single key 'timezone', or a map containing temporal values ('hour', 'minute', 'second', 'millisecond', 'microsecond', 'nanosecond', 'timezone') as components.
Returns	`ZONED TIME`

Temporal components
Name	Description
`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 timezone.

Considerations
If no parameters are provided, `time()` must be invoked (`time({})` is invalid).
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 timezone 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 smallest 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.
String representations of temporal values must comply with the format defined for times and time zones.
The timezone component will default to the configured default timezone if it is omitted.
String representations of temporal values must denote a valid time; i.e. a `temporalValue` denoting `15:67` is invalid.
`time(null)` returns `null`.
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 `ZONED TIME` or `ZONED DATETIME` value as the `time` component also selects its timezone. If a `LOCAL TIME` or `LOCAL DATETIME` is selected instead, the default timezone is used. In any case, the timezone can be overridden explicitly.
Selecting a `ZONED DATETIME` or `ZONED TIME` as the `time` component and overwriting the timezone will adjust the local time to keep the same point in time.

Example 60. time() to get the current time (no parameters)

Query

RETURN time() AS currentTime

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

Result
currentTime
`10:02:32.192Z`
Rows: 1

Example 61. time() with timezone

Query

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

The current time of day in California is returned.

Result
currentTimeInLA
`03:02:32.233-07:00`
Rows: 1

Creating `ZONED TIME` values

Example 62. time()

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

Result
theTime
`12:31:14.123456789Z`
`12:31:14.645876123Z`
`12:31:14.645876000+01:00`
`12:31:00+01:00`
`12:00:00+01:00`
Rows: 5

Example 63. time() - Creating a ZONED TIME from a STRING

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

Result
theTime
`21:40:32.142000000+01:00`
`21:40:32.142000000Z`
`21:40:32+01:00`
`21:40:32-01:00`
`21:40:00-01:30`
`21:40:00Z`
`21:40:00-02:00`
`22:00:00+18:00`
Rows: 8

Example 64. time() - Creating a ZONED TIME using other temporal values as components

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

Result
timeOnly	timeTimezone	timeSS	timeSSTimezone
`12:31:14.645876Z`	`12:31:14.645876+05:00`	`12:31:42.645876Z`	`12:31:42.645876+05:00`
Rows: 1

time.realtime()

Details
Syntax	`time.realtime([ timezone ])`
Description	Returns the current `ZONED TIME` instant using the realtime clock.
Arguments	Name	Type	Description
	`timezone`	`ANY`	A string value representing a timezone.
Returns	`ZONED TIME`

The returned ZONED TIME will be the live clock of the system.

Example 65. time.realtime()

Query

RETURN time.realtime() AS currentTime

Result
currentTime
`10:02:32.436948Z`
Rows: 1

time.statement()

Details
Syntax	`time.statement([ timezone ])`
Description	Returns the current `ZONED TIME` instant using the statement clock.
Arguments	Name	Type	Description
	`timezone`	`ANY`	A string value representing a timezone.
Returns	`ZONED TIME`

The returned ZONED TIME 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.

Example 66. time.statement()

Query

RETURN time.statement() AS currentTime

Result
currentTime
`10:02:32.317Z`
Rows: 1

Example 67. time.statement()

Query

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

Result
currentTimeInLA
`03:02:32.351-07:00`
Rows: 1

time.transaction()

Details
Syntax	`time.transaction([ timezone ])`
Description	Returns the current `ZONED TIME` instant using the transaction clock.
Arguments	Name	Type	Description
	`timezone`	`ANY`	A string value representing a timezone.
Returns	`ZONED TIME`

The returned ZONED TIME will be the same for each invocation within the same transaction. However, a different value may be produced for different transactions.

Example 68. time.transaction()

Query

RETURN time.transaction() AS currentTime

Result
currentTime
`10:02:32.276Z`
Rows: 1

time.truncate()

Details
Syntax	`time.truncate(unit [, input, fields])`
Description	Truncates the given temporal value to a `ZONED TIME` instant using the specified unit.
Arguments	Name	Type	Description
	`unit`	`STRING`	A string representing one of the following: 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day'.
	`input`	`ANY`	The date to be truncated using either `ZONED DATETIME`, `LOCAL DATETIME`, `ZONED TIME`, or `LOCAL TIME`.
	`fields`	`MAP`	A list of time components smaller than those specified in `unit` to preserve during truncation.
Returns	`ZONED TIME`

time.truncate() returns the ZONED 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 ZONED TIME returned will have all components that are smaller 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 smaller than the truncation unit. This will have the effect of overriding the default values which would otherwise have been set for these smaller components. For example, minute — with some value x — may be provided when the truncation unit STRING is 'hour' in order to ensure the returned value has the minute set to x instead of the default minute (which is 1).

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 `input`. However, the timezone of `input` is retained.
The timezone of `input` may be overridden; for example, `time.truncate('minute', input, {timezone: '+0200'})`.
If `input` is one of `ZONED TIME`, `ZONED DATETIME` — a value with a timezone — and the timezone is overridden, no time conversion occurs.
If `input` is one of `LOCAL TIME`, `LOCAL DATETIME`, `DATE` — a value without a timezone — and the timezone is not overridden, the configured default timezone will be used.
Any component that is provided in `fields` must be smaller than `unit`; i.e. if `unit` is `'second'`, `fields` cannot contain information pertaining to a minute.
Any component that is not contained in `fields` and which is smaller than `unit` will be set to its minimal value.
If `fields` is not provided, all components of the returned value which are smaller than `unit` will be set to their default values.
If `input` is not provided, it will be set to the current time and timezone, i.e. `time.truncate(unit)` is equivalent of `time.truncate(unit, time())`.

Example 69. time()

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

Result
truncDay	truncHour	truncMinute	truncSecond	truncMillisecond	truncMicrosecond
`00:00:00-01:00`	`12:00:00-01:00`	`12:31:00-01:00`	`12:31:14-01:00`	`12:31:14.645000002-01:00`	`12:31:14.645876000-01:00`
Rows: 1

Temporal functions - instant types

Temporal instant types

An overview of temporal instant type creation

Controlling which clock to use

Truncating temporal values

date()

Creating DATE values

date.realtime()

date.statement()

date.transaction()

date.truncate()

datetime()

Creating ZONED DATETIME values

datetime.fromEpoch()

datetime.fromEpochMillis()

datetime.realtime()

datetime.statement()

datetime.transaction()

datetime.truncate()

localdatetime()

Creating LOCAL DATETIME values

localdatetime.realtime()

localdatetime.statement()

localdatetime.transaction()

localdatetime.truncate()

localtime()

Creating LOCAL TIME values

localtime.realtime()

localtime.statement()

localtime.transaction()

localtime.truncate()

time()

Creating ZONED TIME values

time.realtime()

time.statement()

time.transaction()

time.truncate()

Creating `DATE` values

Creating `ZONED DATETIME` values

Creating `LOCAL DATETIME` values

Creating `LOCAL TIME` values

Creating `ZONED TIME` values