Temporal functions - duration

Duration functions allow for the creation and manipulation of temporal DURATION values.

See also Temporal values and Temporal operators.

duration()

Details
Syntax	`duration(input)`
Description	Creates a `DURATION` value.
Arguments	Name	Type	Description
	`input`	`ANY`	A map optionally containing the following keys: 'years', 'quarters', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds', 'milliseconds', 'microseconds', or 'nanoseconds'.
Returns	`DURATION`

Considerations
At least one parameter must be provided (`duration()` and `duration({})` are invalid).
There is no constraint on how many of the parameters are provided.
It is possible to have a `DURATION` where the amount of a smaller unit (e.g. `seconds`) exceeds the threshold of a larger unit (e.g. `days`).
The values of the parameters may be expressed as decimal fractions.
The values of the parameters may be arbitrarily large.
The values of the parameters may be negative.
The components of `DURATION` objects are individually accessible.

Example 1. duration() using duration components

Query

UNWIND [
duration({days: 14, hours:16, minutes: 12}),
duration({months: 5, days: 1.5}),
duration({months: 0.75}),
duration({weeks: 2.5}),
duration({minutes: 1.5, seconds: 1, milliseconds: 123, microseconds: 456, nanoseconds: 789}),
duration({minutes: 1.5, seconds: 1, nanoseconds: 123456789})
] AS aDuration
RETURN aDuration

Result
aDuration
`P14DT16H12M`
`P5M1DT12H`
`P22DT19H51M49.5S`
`P17DT12H`
`PT1M31.123456789S`
`PT1M31.123456789S`
Rows: 6

Example 2. duration() using STRING values

Query

UNWIND [
duration("P14DT16H12M"),
duration("P5M1.5D"),
duration("P0.75M"),
duration("PT0.75M"),
duration("P2012-02-02T14:37:21.545")
] AS aDuration
RETURN aDuration

Result
aDuration
`P14DT16H12M`
`P5M1DT12H`
`P22DT19H51M49.5S`
`PT45S`
`P2012Y2M2DT14H37M21.545S`
Rows: 5

duration.between()

Details
Syntax	`duration.between(from, to)`
Description	Computes the `DURATION` between the `from` instant (inclusive) and the `to` instant (exclusive) in logical units.
Arguments	Name	Type	Description
	`from`	`ANY`	A temporal instant type (`DATE`, `LOCAL TIME`, `ZONED TIME`, `LOCAL DATETIME`, `ZONED DATETIME`) representing the starting instant.
	`to`	`ANY`	A temporal instant type (`DATE`, `LOCAL TIME`, `ZONED TIME`, `LOCAL DATETIME`, `ZONED DATETIME`) representing the ending instant.
Returns	`DURATION`

Considerations
If `to` occurs earlier than `from`, the resulting `DURATION` will be negative.
If `from` has a time component and `to` does not, the time component of `to` is assumed to be midnight, and vice versa.
If `from` has a time zone component and `to` does not, the time zone component of `to` is assumed to be the same as that of `from`, and vice versa.
If `to` has a date component and `from` does not, the date component of `from` is assumed to be the same as that of `to`, and vice versa.

Example 3. duration.between()

Query

UNWIND [
duration.between(date("1984-10-11"), date("1985-11-25")),
duration.between(date("1985-11-25"), date("1984-10-11")),
duration.between(date("1984-10-11"), datetime("1984-10-12T21:40:32.142+0100")),
duration.between(date("2015-06-24"), localtime("14:30")),
duration.between(localtime("14:30"), time("16:30+0100")),
duration.between(localdatetime("2015-07-21T21:40:32.142"), localdatetime("2016-07-21T21:45:22.142")),
duration.between(datetime({year: 2017, month: 10, day: 29, hour: 0, timezone: 'Europe/Stockholm'}), datetime({year: 2017, month: 10, day: 29, hour: 0, timezone: 'Europe/London'}))
] AS aDuration
RETURN aDuration

Result
aDuration
`P1Y1M14D`
`P-1Y-1M-14D`
`P1DT21H40M32.142S`
`PT14H30M`
`PT2H`
`P1YT4M50S`
`PT1H`
Rows: 7

duration.inDays()

Details
Syntax	`duration.inDays(from, to)`
Description	Computes the `DURATION` between the `from` instant (inclusive) and the `to` instant (exclusive) in days.
Arguments	Name	Type	Description
	`from`	`ANY`	A temporal instant type (`DATE`, `LOCAL TIME`, `ZONED TIME`, `LOCAL DATETIME`, `ZONED DATETIME`) representing the starting instant.
	`to`	`ANY`	A temporal instant type (`DATE`, `LOCAL TIME`, `ZONED TIME`, `LOCAL DATETIME`, `ZONED DATETIME`) representing the ending instant.
Returns	`DURATION`

Considerations
If `to` occurs earlier than `from`, the resulting `DURATION` will be negative.
If `from` has a time component and `to` does not, the time component of `to` is assumed to be midnight, and vice versa.
If `from` has a time zone component and `to` does not, the time zone component of `to` is assumed to be the same as that of `from`, and vice versa.
If `from` has a date component and `to` does not, the date component of `to` is assumed to be the same as that of `from`, and vice versa.
Any difference smaller than a whole day is disregarded.
Get the total number of days in a `DURATION` by returning the `days` component. For more information, see Components of durations.

Example 4. duration.inDays()

Query

UNWIND [
duration.inDays(date("1984-10-11"), date("1985-11-25")),
duration.inDays(date("1985-11-25"), date("1984-10-11")),
duration.inDays(date("1984-10-11"), datetime("1984-10-12T21:40:32.142+0100")),
duration.inDays(date("2015-06-24"), localtime("14:30")),
duration.inDays(localdatetime("2015-07-21T21:40:32.142"), localdatetime("2016-07-21T21:45:22.142")),
duration.inDays(datetime({year: 2017, month: 10, day: 29, hour: 0, timezone: 'Europe/Stockholm'}), datetime({year: 2017, month: 10, day: 29, hour: 0, timezone: 'Europe/London'}))
] AS aDuration
RETURN aDuration

Result
aDuration
`P410D`
`P-410D`
`P1D`
`PT0S`
`P366D`
`PT0S`
Rows: 6

duration.inMonths()

Details
Syntax	`duration.inMonths(from, to)`
Description	Computes the `DURATION` between the `from` instant (inclusive) and the `to` instant (exclusive) in months.
Arguments	Name	Type	Description
	`from`	`ANY`	A temporal instant type (`DATE`, `LOCAL TIME`, `ZONED TIME`, `LOCAL DATETIME`, `ZONED DATETIME`) representing the starting instant.
	`to`	`ANY`	A temporal instant type (`DATE`, `LOCAL TIME`, `ZONED TIME`, `LOCAL DATETIME`, `ZONED DATETIME`) representing the ending instant.
Returns	`DURATION`

Considerations
If `to` occurs earlier than `from`, the resulting `DURATION` will be negative.
If `from` has a time component and `to` does not, the time component of `to` is assumed to be midnight, and vice versa.
If `from` has a time zone component and `to` does not, the time zone component of `to` is assumed to be the same as that of `from`, and vice versa.
If `from` has a date component and `to` does not, the date component of `to` is assumed to be the same as that of `from`, and vice versa.
Any difference smaller than a whole month is disregarded.
Get the total number of months in a `DURATION` by returning the `months` component. For more information, see Components of durations.

Example 5. duration.inMonths()

Query

UNWIND [
duration.inMonths(date("1984-10-11"), date("1985-11-25")),
duration.inMonths(date("1985-11-25"), date("1984-10-11")),
duration.inMonths(date("1984-10-11"), datetime("1984-10-12T21:40:32.142+0100")),
duration.inMonths(date("2015-06-24"), localtime("14:30")),
duration.inMonths(localdatetime("2015-07-21T21:40:32.142"), localdatetime("2016-07-21T21:45:22.142")),
duration.inMonths(datetime({year: 2017, month: 10, day: 29, hour: 0, timezone: 'Europe/Stockholm'}), datetime({year: 2017, month: 10, day: 29, hour: 0, timezone: 'Europe/London'}))
] AS aDuration
RETURN aDuration

Result
aDuration
`P1Y1M`
`P-1Y-1M`
`PT0S`
`PT0S`
`P1Y`
`PT0S`
Rows: 6

duration.inSeconds()

Details
Syntax	`duration.inSeconds(from, to)`
Description	Computes the `DURATION` between the `from` instant (inclusive) and the `to` instant (exclusive) in seconds.
Arguments	Name	Type	Description
	`from`	`ANY`	A temporal instant type (`DATE`, `LOCAL TIME`, `ZONED TIME`, `LOCAL DATETIME`, `ZONED DATETIME`) representing the starting instant.
	`to`	`ANY`	A temporal instant type (`DATE`, `LOCAL TIME`, `ZONED TIME`, `LOCAL DATETIME`, `ZONED DATETIME`) representing the ending instant.
Returns	`DURATION`

Considerations
If `to` occurs earlier than `from`, the resulting `DURATION` will be negative.
If `from` has a time component and `to` does not, the time component of `to` is assumed to be midnight, and vice versa.
If `from` has a time zone component and `to` does not, the time zone component of `to` is assumed to be the same as that of `from`, and vice versa.
If `from` has a date component and `to` does not, the date component of `to` is assumed to be the same as that of `from`, and vice versa.
Get the total seconds of days in a `DURATION` by returning the `seconds` component. For more information, see Components of durations.

Example 6. duration.inSeconds()

Query

UNWIND [
duration.inSeconds(date("1984-10-11"), date("1984-10-12")),
duration.inSeconds(date("1984-10-12"), date("1984-10-11")),
duration.inSeconds(date("1984-10-11"), datetime("1984-10-12T01:00:32.142+0100")),
duration.inSeconds(date("2015-06-24"), localtime("14:30")),
duration.inSeconds(datetime({year: 2017, month: 10, day: 29, hour: 0, timezone: 'Europe/Stockholm'}), datetime({year: 2017, month: 10, day: 29, hour: 0, timezone: 'Europe/London'}))
] AS aDuration
RETURN aDuration

Result
aDuration
`PT24H`
`PT-24H`
`PT25H32.142S`
`PT14H30M`
`PT1H`
Rows: 5