持续时间函数

时长函数允许创建和操作时间 DURATION 值。

另请参阅 时间值 和 时间运算符。

duration()

详细信息

语法

duration(input[, pattern])

描述

创建一个 DURATION 值。

参数

名称

类型

描述

input

ANY

输入可以是表示时长值的字符串，或者包含以下可选键的映射：'years'（年）、'months'（月）、'weeks'（周）、'days'（天）、'hours'（小时）、'minutes'（分钟）、'seconds'（秒）、'milliseconds'（毫秒）、'microseconds'（微秒）或 'nanoseconds'（纳秒）。

pattern

STRING

用于解析输入的模式。如果提供了模式，则 input 必须是 STRING。

返回

DURATION（持续时间）
注意事项

如果 input 不是字符串，则必须至少提供一个组件（duration() 和 duration({}) 是无效的）。

对于提供的组件数量没有限制。

DURATION 允许较小单位（例如 seconds）的数量超过较大单位（例如 days）的阈值。

组件的值可以用十进制小数表示。

组件的值可以是任意大的。

组件的值可以是负数。

DURATION 对象的各个组件是可以单独访问的。

pattern 参数由时长类型允许的字符构建而成。
示例 1. 使用时长组件的 duration()
查询
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
结果
aDuration

P14DT16H12M

P5M1DT12H

P22DT19H51M49.5S

P17DT12H

PT1M31.123456789S

PT1M31.123456789S

行数: 6
示例 2. 使用 STRING 值的 duration()
查询
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
结果
aDuration

P14DT16H12M

P5M1DT12H

P22DT19H51M49.5S

PT45S

P2012Y2M2DT14H37M21.545S

PT5H6M

行数: 6

duration.between()

详细信息

语法

duration.between(from, to)

描述

计算 from 时刻（包含）和 to 时刻（不包含）之间以逻辑单位表示的 DURATION。

参数

名称

类型

描述

从 (from)

ANY

表示起始时刻的时间瞬间类型（DATE, LOCAL TIME, ZONED TIME, LOCAL DATETIME, ZONED DATETIME）。

转换为

ANY

表示结束时刻的时间瞬间类型（DATE, LOCAL TIME, ZONED TIME, LOCAL DATETIME, ZONED DATETIME）。

返回

DURATION（持续时间）
注意事项

如果 to 早于 from，则结果 DURATION 将为负数。

如果 from 包含时间组件而 to 不包含，则 to 的时间组件被假定为午夜，反之亦然。

如果 from 包含时区组件而 to 不包含，则 to 的时区组件被假定为与 from 相同，反之亦然。

如果 to 包含日期组件而 from 不包含，则 from 的日期组件被假定为与 to 相同，反之亦然。
示例 3. duration.between()
查询
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
结果
aDuration

P1Y1M14D

P-1Y-1M-14D

P1DT21H40M32.142S

PT14H30M

PT2H

P1YT4M50S

PT1H

行：7

duration_between()
仅限 Cypher 25在 Neo4j 2026.02 中引入

详细信息

语法

duration_between(from, to)

描述

计算 from 时刻（包含）和 to 时刻（不包含）之间以逻辑单位表示的 DURATION。

参数

名称

类型

描述

从 (from)

ANY

表示起始时刻的时间瞬间类型（DATE, LOCAL TIME, ZONED TIME, LOCAL DATETIME, ZONED DATETIME）。

转换为

ANY

表示结束时刻的时间瞬间类型（DATE, LOCAL TIME, ZONED TIME, LOCAL DATETIME, ZONED DATETIME）。

返回

DURATION（持续时间）

此函数是 duration.between() 函数的别名，它是作为 Cypher® GQL 合规性的一部分引入的。

与 GQL 的差异

在 GQL 中，如果任一参数不是时间瞬间类型，则会引发数据异常 (22G03)。在 Cypher 中，可能会报告不同的错误（例如无效的调用签名），但严重程度相同。Cypher 的 duration.between() 以年、月、日返回日期差；GQL 的 duration_between() 仅以天数返回日期差。因此，对于相同的两个日期，结果可能会有所不同（例如，对于 2026-02-01 到 2026-03-02，Cypher 返回 P1M1D，而 GQL 返回 P29D）。每当跨度包含一个月或多个完整月份时，Cypher 的结果可能与 GQL 的结果不同。

注意事项

如果 to 早于 from，则结果 DURATION 将为负数。

如果 from 包含时间组件而 to 不包含，则 to 的时间组件被假定为午夜，反之亦然。

如果 from 包含时区组件而 to 不包含，则 to 的时区组件被假定为与 from 相同，反之亦然。

如果 to 包含日期组件而 from 不包含，则 from 的日期组件被假定为与 to 相同，反之亦然。
示例 4. duration_between()
查询
RETURN duration_between(date("1984-10-11"), date("1985-11-25")) AS aDuration
结果
aDuration

P1Y1M14D

行：1

duration.inDays()

详细信息

语法

duration.inDays(from, to)

描述

以天为单位计算 from 时刻（含）和 to 时刻（不含）之间的 DURATION。

参数

名称

类型

描述

从 (from)

ANY

表示起始时刻的时间瞬间类型（DATE, LOCAL TIME, ZONED TIME, LOCAL DATETIME, ZONED DATETIME）。

转换为

ANY

表示结束时刻的时间瞬间类型（DATE, LOCAL TIME, ZONED TIME, LOCAL DATETIME, ZONED DATETIME）。

返回

DURATION（持续时间）
注意事项

如果 to 早于 from，则结果 DURATION 将为负数。

如果 from 包含时间组件而 to 不包含，则 to 的时间组件被假定为午夜，反之亦然。

如果 from 包含时区组件而 to 不包含，则 to 的时区组件被假定为与 from 相同，反之亦然。

如果 from 包含日期组件而 to 不包含，则 to 的日期组件被假定为与 from 相同，反之亦然。

小于一整天的任何差异都将被忽略。

通过返回 days 组件来获取 DURATION 中的总天数。有关更多信息，请参阅 时长组件。
示例 5. duration.inDays()
查询
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
结果
aDuration

P410D

P-410D

P1D

PT0S

P366D

PT0S

行数: 6

duration.inMonths()

详细信息

语法

duration.inMonths(from, to)

描述

以月为单位计算 from 时刻（含）和 to 时刻（不含）之间的 DURATION。

参数

名称

类型

描述

从 (from)

ANY

表示起始时刻的时间瞬间类型（DATE, LOCAL TIME, ZONED TIME, LOCAL DATETIME, ZONED DATETIME）。

转换为

ANY

表示结束时刻的时间瞬间类型（DATE, LOCAL TIME, ZONED TIME, LOCAL DATETIME, ZONED DATETIME）。

返回

DURATION（持续时间）
注意事项

如果 to 早于 from，则结果 DURATION 将为负数。

如果 from 包含时间组件而 to 不包含，则 to 的时间组件被假定为午夜，反之亦然。

如果 from 包含时区组件而 to 不包含，则 to 的时区组件被假定为与 from 相同，反之亦然。

如果 from 包含日期组件而 to 不包含，则 to 的日期组件被假定为与 from 相同，反之亦然。

小于一整月的任何差异都将被忽略。

通过返回 months 组件来获取 DURATION 中的总月数。有关更多信息，请参阅 时长组件。
示例 6. duration.inMonths()
查询
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
结果
aDuration

P1Y1M

P-1Y-1M

PT0S

PT0S

P1Y

PT0S

行数: 6

duration.inSeconds()

详细信息

语法

duration.inSeconds(from, to)

描述

以秒为单位计算 from 时刻（含）和 to 时刻（不含）之间的 DURATION。

参数

名称

类型

描述

从 (from)

ANY

表示起始时刻的时间瞬间类型（DATE, LOCAL TIME, ZONED TIME, LOCAL DATETIME, ZONED DATETIME）。

转换为

ANY

表示结束时刻的时间瞬间类型（DATE, LOCAL TIME, ZONED TIME, LOCAL DATETIME, ZONED DATETIME）。

返回

DURATION（持续时间）
注意事项

如果 to 早于 from，则结果 DURATION 将为负数。

如果 from 包含时间组件而 to 不包含，则 to 的时间组件被假定为午夜，反之亦然。

如果 from 包含时区组件而 to 不包含，则 to 的时区组件被假定为与 from 相同，反之亦然。

如果 from 包含日期组件而 to 不包含，则 to 的日期组件被假定为与 from 相同，反之亦然。

通过返回 seconds 组件来获取 DURATION 中的总秒数。有关更多信息，请参阅 时长组件。
示例 7. duration.inSeconds()
查询
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
结果
aDuration

PT24H

PT-24H

PT25H32.142S

PT14H30M

PT1H

行：5