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_between()
Cypher 25 onlyIntroduced in Neo4j 2026.02

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

This function is an alias to the duration.between() function, and it was introduced as part of Cypher®'s GQL conformance.

Differences from GQL

In GQL, if either argument is not a temporal instant type, a data exception is raised (22G03). In Cypher®, a different error (e.g. invalid call signature) may be reported, but with the same severity. Cypher®'s duration.between() returns the date difference in years, months, and days; GQL’s duration_between() returns the date difference in days only. For the same two dates the results can therefore differ (e.g. for 2026-02-01 to 2026-03-02, Cypher® returns P1M1D and GQL returns P29D). Whenever the span includes one or more full months, the Cypher® result may differ from the GQL result.

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 4. duration_between()
Query
RETURN duration_between(date("1984-10-11"), date("1985-11-25")) AS aDuration
Result
aDuration

P1Y1M14D

Rows: 1

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 5. 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 6. 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 7. 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