Duration functions

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

See also Temporal values and Temporal operators.

duration()

Details
Syntax	`duration(input[, pattern])`
Description	Creates a `DURATION` value.
Arguments	Name	Type	Description
	`input`	`ANY`	Either a string representation of a duration value or a map optionally containing the following keys: 'years', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds', 'milliseconds', 'microseconds', or 'nanoseconds'.
	`pattern`	`STRING`	A pattern used to parse the input. If a pattern is provided, `input` must be `STRING`.
Returns	`DURATION`

Considerations
If `input` is not a string, at least one component must be provided (`duration()` and `duration({})` are invalid).
There is no constraint on how many components 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 components may be expressed as decimal fractions.
The values of components may be arbitrarily large.
The values of components may be negative.
The components of `DURATION` objects are individually accessible.
The `pattern` argument is constructed from Allowed characters for duration types.

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"),
duration("5 hours 6 minutes", "h 'hours' m 'minutes'")
] AS aDuration
RETURN aDuration

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

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