瞬时类型函数

时间函数允许为每种时间类型创建和操作值——DATE（日期）、ZONED TIME（带时区时间）、LOCAL TIME（本地时间）、ZONED DATETIME（带时区日期时间）和 LOCAL DATETIME（本地日期时间）。

本页面包含以下函数

DATE ZONED DATETIME LOCAL DATETIME LOCAL TIME ZONED TIME

date()

datetime()

localdatetime()

localtime()

time()

zoned_datetime()

local_datetime()

local_time()

zoned_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()

另请参阅 时间（日期/时间）值 和 时间运算符。

时间瞬时类型

时间瞬时类型创建概览

每个函数都与对应的类型同名，并以以下四种方式之一构造其对应的类型

  • 获取当前时间。

  • 组合该类型的组件。

  • 解析时间值的 STRING（字符串）表示形式。

  • 通过以下方式从另一个时间值中选择并组合组件：

    • 要么结合时间值（例如，结合 DATE 和 ZONED TIME 以创建 ZONED DATETIME），要么

    • 从时间值中选择部分（例如，从 ZONED DATETIME 中选择 DATE）；提取器（可以被选择的组件组）为：

      • date — 包含 DATE 的所有组件（概念上为年、月和日）。

      • time — 包含 ZONED TIME 的所有组件（时、分、秒和子秒；即毫秒、微秒和纳秒）。如果被创建的类型和提取时间组件的源类型都包含 timezone（且未明确指定 timezone），则 timezone 也会被选择。

      • datetime — 选择所有组件，适用于重写特定组件。与 time 类似，如果被创建的类型和提取时间组件的源类型都包含 timezone（且未明确指定 timezone），则 timezone 也会被选择。

    • 实际上，这允许在不同时间类型之间进行转换，并允许指定“缺失”的组件。

时间瞬时类型创建函数
函数 DATE ZONED TIME LOCAL TIME ZONED DATETIME LOCAL DATETIME

获取当前值。

创建基于日历（年-月-日）的值。

创建基于周（年-周-日）的值。

创建基于季度（年-季度-日）的值。

创建序数值（年-天）的值。

通过时间组件创建值。

使用提取器从其他时间值创建值（即在不同类型间转换）。

从 STRING 创建值。

从时间戳创建值。

所有时间瞬时类型——包括那些不包含时区信息支持的类型，如 DATE、LOCAL TIME 和 LOCAL DATETIME——都允许在获取当前瞬时的函数中指定时区。这允许在指定的时区中获取当前瞬时值。

控制使用的时钟

基于当前瞬时创建时间瞬时值的函数默认使用 statement 时钟。但是，有三种不同的时钟可用于更精细的控制：

  • transaction：同一事务内的每次调用都会产生相同的瞬时值。不同事务可能产生不同的时间。

  • statement：同一语句内的每次调用都会产生相同的瞬时值。同一事务内的不同语句可能产生不同的时间。

  • realtime：产生的瞬时值将是系统的实时时钟。

下表列出了在创建当前时间瞬时值时用于指定所用时钟的不同子函数

类型 默认 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()

截断时间值

可以通过在指定的组件边界（即截断单位）处截断另一个时间瞬时值来创建时间瞬时值。以这种方式创建的时间瞬时值，所有小于指定截断单位的组件都将被设置为其默认值。

可以通过提供包含小于截断单位的组件的映射来补充被截断的值。这会覆盖本应为这些较小组件设置的默认值。

下表列出了支持的截断单位及相应的子函数

截断单位 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)

date()

详细信息

语法

date([ input, pattern] )

描述

创建一个 DATE 瞬时值。

参数

名称

类型

描述

input

ANY

可以是时间值的字符串表示、包含键“timezone”的映射，或包含时间值组件（'date', 'year', 'month', 'day', 'week', 'dayOfWeek', 'quarter', 'dayOfQuarter', 'ordinalDay'）的映射。

pattern

STRING

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

返回

DATE
时间组件
名称 描述

date

一个 DATE 值。

year

由至少四位数字组成的年份表达式。

month

1 到 12 之间的整数，指定月份。

day

1 到 31 之间的整数，指定月份中的日期。

week

1 到 53 之间的整数，指定周数。

dayOfWeek

1 到 7 之间的整数，指定星期几。

quarter

1 到 4 之间的整数，指定季度。

dayOfQuarter

1 到 92 之间的整数，指定季度中的日期。

ordinalDay

1 到 366 之间的整数，指定一年中的序数日。
注意事项

如果不提供参数，必须调用 date()（date({}) 无效）。

如果未指定时区，将使用本地时区。

如果省略 day，月份中的日期组件默认设为 1。

如果省略 month，月份组件默认设为 1。

如果省略 month，则必须同时省略 day。

如果省略 dayOfWeek，星期几组件默认设为 1。

如果省略 week，周组件默认设为 1。

如果省略 week，则必须同时省略 dayOfWeek。

如果省略 dayOfQuarter，季度中的日期组件默认设为 1。

如果省略 quarter，季度组件默认设为 1。

如果省略 quarter，则必须同时省略 dayOfQuarter。

如果省略 ordinalDay，一年中的序数日组件默认设为 1。

时间值的字符串表示必须符合日期定义的格式。

时间值的字符串表示必须表示有效的日期；例如，表示 2001年2月30日 的时间值无效。

date(null) 返回 null。

如果提供了任何可选参数，这些参数将覆盖 date 的相应组件。

可以使用 date(dd) 来代替 date({date: dd})。

pattern 参数由实例类型的允许字符构造。
示例 1. date() 获取当前时间（不提供参数）
查询
RETURN date() AS currentDate

返回当前日期。

结果
currentDate

2022-06-14

行：1
示例 2. date() 提供时区
查询
RETURN date({timezone: 'America/Los Angeles'}) AS currentDateInLA

返回加利福尼亚的当前日期。

结果
currentDateInLA

2022-06-14

行：1

创建 DATE 值

示例 3. date() - 创建日历（年-月-日）DATE
查询
UNWIND [
date({year: 1984, month: 10, day: 11}),
date({year: 1984, month: 10}),
date({year: 1984})
] AS theDate
RETURN theDate
结果
theDate

1984-10-11

1984-10-01

1984-01-01

行：3
示例 4. date() - 创建周（年-周-日）DATE
查询
UNWIND [
date({year: 1984, week: 10, dayOfWeek: 3}),
date({year: 1984, week: 10}),
date({year: 1984})
] AS theDate
RETURN theDate
结果
theDate

1984-03-07

1984-03-05

1984-01-01

行：3
示例 5. date() - 创建季度（年-季度-日）DATE
查询
UNWIND [
date({year: 1984, quarter: 3, dayOfQuarter: 45}),
date({year: 1984, quarter: 3}),
date({year: 1984})
] AS theDate
RETURN theDate
结果
theDate

1984-08-14

1984-07-01

1984-01-01

行：3
示例 6. date() - 创建序数（年-日）DATE
查询
UNWIND [
date({year: 1984, ordinalDay: 202}),
date({year: 1984})
] AS theDate
RETURN theDate

返回对应于 1984年2月11日 的日期。

结果
theDate

1984-07-20

1984-01-01

行：2
示例 7. date() - 使用其他时间值作为组件创建 DATE
查询
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
结果
dateOnly +dateDay

1984-11-11

1984-11-28

1984-11-11

1984-11-28

1984-11-11

1984-11-28

行：3
示例 8. date() - 从 STRING 创建 DATE
查询
UNWIND [
date('2015-07-21'),
date('2015-07'),
date('201507'),
date('2015-W30-2'),
date('2015202'),
date('2015'),
date('11/18/1986', "MM/dd/yyyy")
] AS theDate
RETURN theDate
结果
theDate

2015-07-21

2015-07-01

2015-07-01

2015-07-21

2015-07-21

2015-01-01

1986-11-18

行：7

date.realtime()

详细信息

语法

date.realtime([ timezone ])

描述

使用实时时钟返回当前的 DATE 瞬时值。

参数

名称

类型

描述

timezone

ANY

表示时区的字符串值。

返回

DATE

返回的 DATE 将是系统的实时时钟。

示例 9. date.realtime()
查询
RETURN date.realtime() AS currentDate
结果
currentDate

2022-06-14

行：1
示例 10. date.realtime()
查询
RETURN date.realtime('America/Los Angeles') AS currentDateInLA
结果
currentDateInLA

2022-06-14

行：1

date.statement()

详细信息

语法

date.statement([ timezone ])

描述

使用语句时钟返回当前的 DATE 瞬时值。

参数

名称

类型

描述

timezone

ANY

表示时区的字符串值。

返回

DATE

返回的 DATE 在同一语句中的每次调用中都是相同的。但是，同一事务内的不同语句可能会产生不同的值。

示例 11. date.statement()
查询
RETURN date.statement() AS currentDate
结果
currentDate

2022-06-14

行：1

date.transaction()

详细信息

语法

date.transaction([ timezone ])

描述

使用事务时钟返回当前的 DATE 瞬时值。

参数

名称

类型

描述

timezone

ANY

表示时区的字符串值。

返回

DATE

返回的 DATE 在同一事务中的每次调用中都是相同的。但是，不同的事务可能会产生不同的值。

示例 12. date.transaction()
查询
RETURN date.transaction() AS currentDate
结果
currentDate

2022-06-14

行：1

date.truncate()

详细信息

语法

date.truncate(unit [, input, fields])

描述

使用指定的单位将给定的时间值截断为 DATE 瞬时值。

参数

名称

类型

描述

unit

STRING

表示以下之一的字符串：'day', 'week', 'month', 'weekYear', 'quarter', 'year', 'decade', 'century', 'millennium'。

input

ANY

要使用 ZONED DATETIME、LOCAL DATETIME 或 DATE 进行截断的日期。

fields

MAP

在截断期间需要保留的小于 unit 指定的时间组件列表。

返回

DATE

date.truncate() 返回通过在指定的时间组件边界（由作为参数传递给函数的截断单位表示）处截断指定的时间瞬时值而获得的 DATE 值。换句话说，返回的 DATE 中所有小于指定截断单位的组件都将被设置为其默认值。

可以通过提供包含小于截断单位的组件的映射来补充被截断的值。这会产生覆盖本应为这些较小组件设置的默认值的效果。例如，当截断单位 STRING 为 'year' 时，可以提供 day（带有某个值 x），以确保返回的值将 day 设置为 x 而不是默认的 day（即 1）。

注意事项

fields 中提供的任何组件必须小于 unit；例如，如果 unit STRING 为 'day'，则 fields 不能包含与 month 相关的信息。

任何未包含在 fields 中且小于 unit 的组件都将被设置为其最小值。

如果未提供 fields，则返回值的、小于 unit 的所有组件都将设置为其默认值。

如果未提供 input，则将其设置为当前日期，即 date.truncate(unit) 等同于 date.truncate(unit, date())。
示例 13. date.truncate()
查询
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
结果
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

行：1

datetime()

详细信息

语法

datetime([ input, pattern ])

描述

创建一个 ZONED DATETIME 瞬时值。

参数

名称

类型

描述

input

ANY

可以是时间值的字符串表示、包含键“timezone”的映射，或包含时间值组件（'year', 'month', 'day', 'hour', 'minute', 'second', 'millisecond', 'microsecond', 'nanosecond', 'timezone'）的映射。

pattern

STRING

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

返回

ZONED DATETIME
时间组件
名称 描述

year

由至少四位数字组成的年份表达式。

month

1 到 12 之间的整数，指定月份。

day

1 到 31 之间的整数，指定月份中的日期。

hour

0 到 23 之间的整数，指定一天中的小时。

minute

0 到 59 之间的整数，指定分钟数。

second

0 到 59 之间的整数，指定秒数。

millisecond

0 到 999 之间的整数，指定毫秒数。

microsecond

0 到 999,999 之间的整数，指定微秒数。

nanosecond

0 到 999,999,999 之间的整数，指定纳秒数。

timezone

指定时区的表达式。

epochSeconds

表示 UTC 时区中 UNIX 纪元秒数的数值。

epochMillis

表示 UTC 时区中 UNIX 纪元毫秒数的数值。
注意事项

如果不提供参数，必须调用 datetime()（datetime({}) 无效）。

如果省略 month，月份组件默认设为 1。

如果省略 day，月份中的日期组件默认设为 1。

如果省略 hour，小时组件默认设为 0。

如果省略 minute，分钟组件默认设为 0。

如果省略 second，秒组件默认设为 0。

任何缺失的 millisecond、microsecond 或 nanosecond 值默认设为 0。

如果省略 timezone，时区组件默认设为配置的默认时区。

如果组合提供了 millisecond、microsecond 和 nanosecond（作为同一组参数的一部分），则各个值必须在 0 到 999 的范围内。

year、month、day、hour、minute 和 second 集合中的最小组件可以省略；即可以仅指定 year、month 和 day，但不允许指定 year、month、 day 和 minute。

仅当同时指定了 second 时，才能指定 millisecond、microsecond 和 nanosecond 中的一个或多个。

时间值的字符串表示必须符合日期、时间和时区定义的格式。

时间值的字符串表示必须表示有效的日期；例如，表示 2001年2月30日 的时间值无效。

如果提供了任何可选参数，这些参数将覆盖 datetime、date 和/或 time 的相应组件。

可以使用 datetime(dd) 来代替 datetime({datetime: dd})。

选择 ZONED TIME 或 ZONED DATETIME 值作为 time 组件也会选择其时区。如果选择 LOCAL TIME 或 LOCAL DATETIME，则使用默认时区。在任何情况下，都可以显式覆盖时区。

将 ZONED DATETIME 作为 datetime 组件选择并覆盖时区，将调整本地时间以保持相同的时间点。

将 ZONED DATETIME 或 ZONED TIME 作为 time 组件选择并覆盖时区，将调整本地时间以保持相同的时间点。

epochSeconds/epochMillis 可与 nanosecond 结合使用。

datetime(null) 返回 null。

pattern 参数由实例类型的允许字符构造。
示例 14. .datetime() 获取当前日期时间（不提供参数）
查询
RETURN datetime() AS currentDateTime

返回使用本地时区的当前日期和时间。

结果
currentDateTime

2022-06-14T10:02:28.192Z

行：1
示例 15. datetime() 提供时区
查询
RETURN datetime({timezone: 'America/Los Angeles'}) AS currentDateTimeInLA

返回加利福尼亚的当前日期和时间。

结果
currentDateTimeInLA

2022-06-14T03:02:28.238-07:00[America/Los_Angeles]

行：1

创建 ZONED DATETIME 值

示例 16. datetime() - 创建日历（年-月-日）ZONED DATETIME
查询
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
结果
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]

行：8
示例 17. datetime() - 创建周（年-周-日）ZONED DATETIME
查询
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
结果
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]

行：7
示例 18. datetime() - 创建季度（年-季度-日）ZONED DATETIME
查询
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
结果
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

行：4
示例 19. datetime() - 创建序数（年-日）ZONED DATETIME
查询
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
结果
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

行：4
示例 20. datetime() - 从 STRING 创建 ZONED DATETIME
查询
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]'),
datetime('Tuesday, November 18, AD 1986', 'EEEE, MMMM d, G uuuu')
] AS theDate
RETURN theDate
结果
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]

1986-11-18T00:00Z

行：9
示例 21. datetime() - 使用其他时间值作为组件创建 ZONED DATETIME

以下查询显示了 datetime({date [, year, ..., timezone]}) 的各种用法。

查询
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
结果
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]

行：1
示例 22. datetime() - 使用其他时间值作为组件创建 ZONED DATETIME

以下查询显示了 datetime({time [, year, …​, timezone]}) 的各种用法。

查询
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
结果
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]

行：1
示例 23. datetime() - 使用其他时间值作为组件创建 ZONED DATETIME

以下查询显示了 datetime({date, time [, year, ..., timezone]}) 的各种用法；即结合 DATE 和 ZONED TIME 值以创建一个 ZONED DATETIME 值。

查询
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
结果
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]

行：1
示例 24. datetime() - 使用其他时间值作为组件创建 ZONED DATETIME

以下查询显示了 datetime({datetime [, year, ..., timezone]}) 的各种用法。

查询
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
结果
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]

行：1
示例 25. datetime() - 从 UNIX 纪元 (epocSeconds) 创建 ZONED DATETIME

datetime() 返回 UTC 时区中 UNIX 纪元之后的指定秒数或毫秒数对应的 ZONED DATETIME 值。

通过将 ZONED DATETIME 值转换为这些类型，可以实现从 UNIX 纪元表示形式到其他时间瞬时类型的转换。

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

2022-06-14T10:02:30.000000023Z

行：1
示例 26. datetime() - 从 UNIX 纪元 (epocMillis) 创建 ZONED DATETIME
查询
RETURN datetime({epochMillis: 424797300000}) AS theDate
结果
theDate

1983-06-18T15:15Z

行：1

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

详细信息

语法

zoned_datetime([ input, pattern ])

描述

创建一个 ZONED DATETIME 瞬时值。

参数

名称

类型

描述

input

ANY

时间值或包含时间组件的映射。

pattern

STRING

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

返回

ZONED DATETIME

此函数是 datetime() 函数的别名，它是作为 Cypher® GQL 一致性的一部分引入的。有关支持的组件和解析行为的详细信息，请参阅 datetime()。

与 GQL 的差异

在 GQL 中，无效的日期时间（或时区）字段名称集会引发数据异常 (22G05)；Cypher 使用同等严重程度的错误 (22007/22N12)。Cypher 还允许使用可选的 pattern 参数进行解析；此别名也支持它。GQL 关键字 CURRENT_TIMESTAMP 没有在 Cypher 中作为保留关键字引入，因为这会破坏现有的使用该名称作为变量的查询。

示例 27. zoned_datetime()
查询
RETURN zoned_datetime('2022-06-14T10:02:30Z') AS theDateTime
结果
theDateTime

2022-06-14T10:02:30Z

行：1

datetime.fromEpoch()

详细信息

语法

datetime.fromEpoch(seconds, nanoseconds)

描述

给定纪元开始后的秒数和纳秒数，创建一个 ZONED DATETIME。

参数

名称

类型

描述

seconds

INTEGER | FLOAT

UTC 时区中 UNIX 纪元后的秒数。

nanoseconds

INTEGER | FLOAT

UTC 时区中 UNIX 纪元后的纳秒数。这可以加到秒数中。

返回

ZONED DATETIME
示例 28. datetime.fromEpoch()
查询
WITH datetime.fromEpoch(1683000000, 123456789) AS dateTimeFromEpoch
RETURN dateTimeFromEpoch
结果
dateTimeFromEpoch

2023-05-02T04:00:00.123456789Z

行：1

datetime.fromEpochMillis()

详细信息

语法

datetime.fromEpochMillis(milliseconds)

描述

给定纪元开始后的毫秒数，创建一个 ZONED DATETIME。

参数

名称

类型

描述

milliseconds

INTEGER | FLOAT

UTC 时区中 UNIX 纪元后的毫秒数。

返回

ZONED DATETIME
示例 29. datetime.fromEpochMillis()
查询
WITH datetime.fromEpochMillis(1724198400000) AS dateTimeFromMillis
RETURN dateTimeFromMillis
结果
dateTimeFromMillis

2024-08-21T00:00Z

行：1

datetime.realtime()

详细信息

语法

datetime.realtime([ timezone ])

描述

使用实时时钟返回当前的 ZONED DATETIME 瞬时值。

参数

名称

类型

描述

timezone

ANY

表示时区的字符串值。

返回

ZONED DATETIME

返回的 ZONED DATETIME 将是系统的实时时钟。

示例 30. datetime.realtime()
查询
RETURN datetime.realtime() AS currentDateTime
结果
currentDateTime

2022-06-14T10:02:28.494444Z

行：1

datetime.statement()

详细信息

语法

datetime.statement([ timezone ])

描述

使用语句时钟返回当前的 ZONED DATETIME 瞬时值。

参数

名称

类型

描述

timezone

ANY

表示时区的字符串值。

返回

ZONED DATETIME

此返回的 ZONED DATETIME 在同一语句中的每次调用中都是相同的。但是，同一事务内的不同语句可能会产生不同的值。

示例 31. datetime.statement()
查询
RETURN datetime.statement() AS currentDateTime
结果
currentDateTime

2022-06-14T10:02:28.395Z

行：1

datetime.transaction()

详细信息

语法

datetime.transaction([ timezone ])

描述

使用事务时钟返回当前的 ZONED DATETIME 瞬时值。

参数

名称

类型

描述

timezone

ANY

表示时区的字符串值。

返回

ZONED DATETIME

返回的 ZONED DATETIME 值在同一事务中的每次调用中都是相同的。但是，不同的事务可能会产生不同的值。

示例 32. datetime.transaction()
查询
RETURN datetime.transaction() AS currentDateTime
结果
currentDateTime

2022-06-14T10:02:28.290Z

行：1
示例 33. datetime.transaction()
查询
RETURN datetime.transaction('America/Los Angeles') AS currentDateTimeInLA
结果
currentDateTimeInLA

2022-06-14T03:02:28.338-07:00[America/Los_Angeles]

行：1

datetime.truncate()

详细信息

语法

datetime.truncate(unit [, input, fields])

描述

使用指定的单位将给定的时间值截断为 ZONED DATETIME 瞬时值。

参数

名称

类型

描述

unit

STRING

表示以下之一的字符串：'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day', 'week', 'month', 'weekYear', 'quarter', 'year', 'decade', 'century', 'millennium'。

input

ANY

要使用 ZONED DATETIME、LOCAL DATETIME 或 DATE 进行截断的日期。

fields

MAP

在截断期间需要保留的小于 unit 指定的时间组件列表。

返回

ZONED DATETIME

datetime.truncate() 返回通过在指定的时间组件边界（由作为参数传递给函数的截断单位表示）处截断指定的时间瞬时值而获得的 ZONED DATETIME 值。换句话说，返回的 ZONED DATETIME 中所有小于指定截断单位的组件都将被设置为其默认值。

可以通过提供包含小于截断单位的组件的映射来补充被截断的值。这会产生覆盖本应为这些较小组件设置的默认值的效果。例如，当截断单位 STRING 为 'year' 时，可以提供 day（带有某个值 x），以确保返回的值将 day 设置为 x 而不是默认的 day（即 1）。

注意事项

如果 unit 是 'hour'、'minute'、'second'、'millisecond'、'microsecond' 中的一个，则 input 不能是 DATE 值。

input 的时区可以被覆盖；例如，datetime.truncate('minute', input, {timezone: '+0200'})。

如果 input 是 ZONED TIME、ZONED DATETIME（具有时区的值）之一，且时区被覆盖，则不会发生时间转换。

如果 input 是 LOCAL DATETIME、DATE（不具有时区的值）之一，且时区未被覆盖，则将使用配置的默认时区。

fields 中提供的任何组件必须小于 unit；例如，如果 unit 为 'day'，则 fields 不能包含与 month 相关的信息。

任何未包含在 fields 中且小于 unit 的组件都将被设置为其最小值。

如果未提供 fields，则返回值的、小于 unit 的所有组件都将设置为其默认值。

如果未提供 input，则将其设置为当前的日期、时间和时区，即 datetime.truncate(unit) 等同于 datetime.truncate(unit, datetime())。
示例 34. datetime.truncate()
查询
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
结果
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

行：1

localdatetime()

详细信息

语法

localdatetime([ input, pattern ])

描述

创建一个 LOCAL DATETIME 瞬时值。

参数

名称

类型

描述

input

ANY

可以是时间值的字符串表示、包含键“timezone”的映射，或包含时间值组件（'year', 'month', 'day', 'hour', 'minute', 'second', 'millisecond', 'microsecond', 'nanosecond'）的映射。

pattern

STRING

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

返回

LOCAL DATETIME
时间组件
名称 描述

一个包含以下内容的映射

year

由至少四位数字组成的年份表达式。

month

1 到 12 之间的整数，指定月份。

day

1 到 31 之间的整数，指定月份中的日期。

hour

0 到 23 之间的整数，指定一天中的小时。

minute

0 到 59 之间的整数，指定分钟数。

second

0 到 59 之间的整数，指定秒数。

millisecond

0 到 999 之间的整数，指定毫秒数。

microsecond

0 到 999,999 之间的整数，指定微秒数。

nanosecond

0 到 999,999,999 之间的整数，指定纳秒数。
注意事项

如果不提供参数，必须调用 localdatetime()（localdatetime({}) 无效）。

如果省略 month，月份组件默认设为 1。

如果省略 day，月份中的日期组件默认设为 1。

如果省略 hour，小时组件默认设为 0。

如果省略 minute，分钟组件默认设为 0。

如果省略 second，秒组件默认设为 0。

任何缺失的 millisecond、microsecond 或 nanosecond 值默认设为 0。

如果组合提供了 millisecond、microsecond 和 nanosecond（作为同一组参数的一部分），则各个值必须在 0 到 999 的范围内。

year、month、day、hour、minute 和 second 集合中的最小组件可以省略；即可以仅指定 year、month 和 day，但不允许指定 year、month、 day 和 minute。

仅当同时指定了 second 时，才能指定 millisecond、microsecond 和 nanosecond 中的一个或多个。

时间值的字符串表示必须符合日期和时间定义的格式。

时间值的字符串表示必须表示有效的日期；例如，表示 2001年2月30日 的时间值无效。

localdatetime(null) 返回 null。

如果提供了任何可选参数，这些参数将覆盖 datetime、date 和/或 time 的相应组件。

可以使用 localdatetime(dd) 来代替 localdatetime({datetime: dd})。

pattern 参数由实例类型的允许字符构造。
示例 35. localdatetime() - 获取当前本地日期和时间（不提供参数）
查询
RETURN localdatetime() AS now

返回当前的本地日期和时间（即在本地时区）。

结果
now

2022-06-14T10:02:30.447

行：1
示例 36. localdatetime() 提供时区
查询
RETURN localdatetime({timezone: 'America/Los Angeles'}) AS now

返回加利福尼亚的当前本地日期和时间。

结果
now

2022-06-14T03:02:30.482

行：1

创建 LOCAL DATETIME 值

示例 37. localdatetime() - 创建日历（年-月-日）LOCAL DATETIME
查询
RETURN
  localdatetime({
    year: 1984, month: 10, day: 11,
    hour: 12, minute: 31, second: 14, millisecond: 123, microsecond: 456, nanosecond: 789
  }) AS theDate
结果
theDate

1984-10-11T12:31:14.123456789

行：1
示例 38. localdatetime() - 创建周（年-周-日）LOCAL DATETIME
查询
RETURN
  localdatetime({
    year: 1984, week: 10, dayOfWeek: 3,
    hour: 12, minute: 31, second: 14, millisecond: 645
  }) AS theDate
结果
theDate

1984-03-07T12:31:14.645

行：1
示例 39. localdatetime() - 创建季度（年-季度-日）ZONED DATETIME
查询
RETURN
  localdatetime({
    year: 1984, quarter: 3, dayOfQuarter: 45,
    hour: 12, minute: 31, second: 14, nanosecond: 645876123
  }) AS theDate
结果
theDate

1984-08-14T12:31:14.645876123

行：1
示例 40. localdatetime() - 创建序数（年-日）LOCAL DATETIME
查询
RETURN
  localdatetime({
    year: 1984, ordinalDay: 202,
    hour: 12, minute: 31, second: 14, microsecond: 645876
  }) AS theDate
结果
theDate

1984-07-20T12:31:14.645876

行：1
示例 41. localdatetime() - 从 STRING 创建 LOCAL DATETIME
查询
UNWIND [
localdatetime('2015-07-21T21:40:32.142'),
localdatetime('2015-W30-2T214032.142'),
localdatetime('2015-202T21:40:32'),
localdatetime('2015202T21'),
localdatetime('Tuesday, November 18, AD 1986', 'EEEE, MMMM d, G uuuu')
] AS theDate
RETURN theDate
结果
theDate

2015-07-21T21:40:32.142

2015-07-21T21:40:32.142

2015-07-21T21:40:32

2015-07-21T21:00

1986-11-18T00:00Z

行：5
示例 42. localdatetime() - 使用其他时间值作为组件创建 LOCAL DATETIME

以下查询显示了 localdatetime({date [, year, ..., nanosecond]}) 的各种用法。

查询
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
结果
dateHHMMSS dateDDHHMMSS

1984-10-11T10:10:10

1984-10-28T10:10:10

行：1
示例 43. localdatetime() - 使用其他时间值作为组件创建 LOCAL DATETIME

以下查询显示了 localdatetime({time [, year, ..., nanosecond]}) 的各种用法。

查询
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
结果
YYYYMMDDTime YYYYMMDDTimeSS

1984-10-11T12:31:14.645876

1984-10-11T12:31:42.645876

行：1
示例 44. localdatetime() - 使用其他时间值作为组件创建 LOCAL DATETIME

以下查询显示了 localdatetime({date, time [, year, ..., nanosecond]}) 的各种用法；即结合 DATE 和 ZONED TIME 值以创建一个 LOCAL DATETIME 值。

查询
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
结果
dateTime dateTimeDDSS

1984-10-11T12:31:14.645876

1984-10-28T12:31:42.645876

行：1
示例 45. localdatetime() - 使用其他时间值作为组件创建 LOCAL DATETIME

以下查询显示了 localdatetime({datetime [, year, ..., nanosecond]}) 的各种用法。

查询
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
结果
dateTime dateTimeDDSS

1984-10-11T12:00

1984-10-28T12:00:42

行：1

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

详细信息

语法

local_datetime([ input, pattern ])

描述

创建一个 LOCAL DATETIME 瞬时值。

参数

名称

类型

描述

input

ANY

时间值或包含时间组件的映射。

pattern

STRING

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

返回

LOCAL DATETIME

此函数是 localdatetime() 函数的别名，它是作为 Cypher GQL 一致性的一部分引入的。有关支持的组件和解析行为的详细信息，请参阅 localdatetime()。

与 GQL 的差异

在 GQL 中，无效的日期时间字段名称集会引发数据异常 (22G05)；Cypher 使用同等严重程度的错误 (22007/22N12)。Cypher 还允许使用可选的 pattern 参数进行解析；此别名也支持它。GQL 关键字 LOCAL_TIMESTAMP 没有在 Cypher 中作为保留关键字引入，因为这会破坏现有的使用该名称作为变量的查询。

示例 46. local_datetime()
查询
RETURN local_datetime('2015-07-21T21:40:32.142') AS theDateTime
结果
theDateTime

2015-07-21T21:40:32.142

行：1

localdatetime.realtime()

详细信息

语法

localdatetime.realtime([ timezone ])

描述

使用实时时钟返回当前的 LOCAL DATETIME 瞬时值。

参数

名称

类型

描述

timezone

ANY

表示时区的字符串值。

返回

LOCAL DATETIME

返回的 LOCAL DATETIME 将是系统的实时时钟。

示例 47. localdatetime.realtime()
查询
RETURN localdatetime.realtime() AS now
结果
now

2022-06-14T10:02:30.647817

行：1
示例 48. localdatetime.realtime()
查询
RETURN localdatetime.realtime('America/Los Angeles') AS nowInLA
结果
nowInLA

2022-06-14T03:02:30.691099

行：1

localdatetime.statement()

详细信息

语法

localdatetime.statement([ timezone ])

描述

使用语句时钟返回当前的 LOCAL DATETIME 瞬时值。

参数

名称

类型

描述

timezone

ANY

表示时区的字符串值。

返回

LOCAL DATETIME

此返回的 LOCAL DATETIME 在同一语句中的每次调用中都是相同的。但是，同一事务内的不同语句可能会产生不同的值。

示例 49. localdatetime.statement()
查询
RETURN localdatetime.statement() AS now
结果
now

2022-06-14T10:02:30.570

行：1

localdatetime.transaction()

详细信息

语法

localdatetime.transaction([ timezone ])

描述

使用事务时钟返回当前的 LOCAL DATETIME 瞬时值。

参数

名称

类型

描述

timezone

ANY

表示时区的字符串值。

返回

LOCAL DATETIME

返回的 LOCAL DATETIME 在同一事务中的每次调用中都是相同的。但是，不同的事务可能会产生不同的值。

示例 50. localdatetime.transaction()
查询
RETURN localdatetime.transaction() AS now
结果
now

2022-06-14T10:02:30.532

行：1

localdatetime.truncate()

详细信息

语法

localdatetime.truncate(unit [, input, fields])

描述

使用指定的单位将给定的时间值截断为 LOCAL DATETIME 瞬时值。

参数

名称

类型

描述

unit

STRING

表示以下之一的字符串：'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day', 'week', 'month', 'weekYear', 'quarter', 'year', 'decade', 'century', 'millennium'。

input

ANY

要使用 ZONED DATETIME、LOCAL DATETIME 或 DATE 进行截断的日期。

fields

MAP

在截断期间需要保留的小于 unit 指定的时间组件列表。

返回

LOCAL DATETIME

localdatetime.truncate() 返回通过在指定的时间组件边界（由作为参数传递给函数的截断单位表示）处截断指定的时间瞬时值而获得的 LOCAL DATETIME 值。换句话说，返回的 LOCAL DATETIME 中所有小于指定截断单位的组件都将被设置为其默认值。

可以通过提供包含小于截断单位的组件的映射来补充被截断的值。这会产生覆盖本应为这些较小组件设置的默认值的效果。例如，当截断单位 STRING 为 'year' 时，可以提供 day（带有某个值 x），以确保返回的值将 day 设置为 x 而不是默认的 day（即 1）。

注意事项

如果 unit 是 'hour'、'minute'、'second'、'millisecond'、'microsecond' 中的一个，则 input 不能是 DATE 值。

fields 中提供的任何组件必须小于 input；例如，如果 input 为 'day'，则 fields 不能包含与 month 相关的信息。

任何未包含在 fields 中且小于 unit 的组件都将被设置为其最小值。

如果未提供 fields，则返回值的、小于 unit 的所有组件都将设置为其默认值。

如果未提供 input，则将其设置为当前的日期和时间，即 localdatetime.truncate(unit) 等同于 localdatetime.truncate(unit, localdatetime())。
示例 51. localdatetime.truncate()
查询
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
结果
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

行：1

localtime()

详细信息

语法

localtime([ input, pattern ])

描述

创建一个 LOCAL TIME 瞬时值。

参数

名称

类型

描述

input

ANY

可以是时间值的字符串表示、包含键“timezone”的映射，或包含时间值组件（'hour', 'minute', 'second', 'millisecond', 'microsecond', 'nanosecond'）的映射。

pattern

STRING

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

返回

LOCAL TIME
时间组件
名称 描述

hour

0 到 23 之间的整数，指定一天中的小时。

minute

0 到 59 之间的整数，指定分钟数。

second

0 到 59 之间的整数，指定秒数。

millisecond

0 到 999 之间的整数，指定毫秒数。

microsecond

0 到 999,999 之间的整数，指定微秒数。

nanosecond

0 到 999,999,999 之间的整数，指定纳秒数。
注意事项

如果不提供参数，必须调用 localtime()（localtime({}) 无效）。

如果省略 hour，小时组件默认设为 0。

如果省略 minute，分钟组件默认设为 0。

如果省略 second，秒组件默认设为 0。

任何缺失的 millisecond、microsecond 或 nanosecond 值默认设为 0。

如果组合提供了 millisecond、microsecond 和 nanosecond（作为同一组参数的一部分），则各个值必须在 0 到 999 的范围内。

hour、minute 和 second 集合中的最小组件可以省略；即可以仅指定 hour 和 minute，但不允许指定 hour 和 second。

仅当同时指定了 second 时，才能指定 millisecond、microsecond 和 nanosecond 中的一个或多个。

时间值的字符串表示必须符合时间定义的格式。

时间值的字符串表示必须表示有效的时间；例如，表示 13:46:64 的时间值无效。

localtime(null) 返回 null。

如果提供了任何可选参数，这些参数将覆盖 time 的相应组件。

可以使用 localtime(tt) 来代替 localtime({time: tt})。

pattern 参数由实例类型的允许字符构造。
示例 52. localtime() 获取当前时间（不提供参数）
查询
RETURN localtime() AS now

返回当前的本地时间（即在本地时区）。

结果
now

10:02:31.596

行：1
示例 53. localtime() 提供时区
查询
RETURN localtime({timezone: 'America/Los Angeles'}) AS nowInLA

返回加利福尼亚的当前本地时间。

结果
nowInLA

03:02:31.629

行：1

创建 LOCAL TIME 值

示例 54. localtime()
查询
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
结果
theTime

12:31:14.123456789

12:31:14

12:00

行：3
示例 55. localtime() - 从 STRING 创建 LOCAL TIME
查询
UNWIND [
localtime('21:40:32.142'),
localtime('214032.142'),
localtime('21:40'),
localtime('21'),
localtime('6:04', 'k:mm')
] AS theTime
RETURN theTime
结果
theTime

21:40:32.142

21:40:32.142

21:40

21:00

06:04

行：5
示例 56. localtime() - 使用其他时间值作为组件创建 LOCAL TIME
查询
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
结果
timeOnly timeSS

12:31:14.645876

12:31:42.645876

行：1

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

详细信息

语法

local_time([ input, pattern ])

描述

创建一个 LOCAL TIME 瞬时值。

参数

名称

类型

描述

input

ANY

时间值或包含时间组件的映射。

pattern

STRING

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

返回

LOCAL TIME

此函数是 localtime() 函数的别名，它是作为 Cypher GQL 一致性的一部分引入的。有关支持的组件和解析行为的详细信息，请参阅 localtime()。

与 GQL 的差异

在 GQL 中，无效的时间字段名称集会引发数据异常 (22G05)；Cypher 使用同等严重程度的错误 (22007/22N12)。Cypher 还允许使用可选的 pattern 参数进行解析；此别名也支持它。GQL 关键字 LOCAL_TIME（无参数）没有在 Cypher 中作为保留关键字引入，因为这会破坏现有的使用 LOCAL_TIME 作为变量名的查询。

示例 57. local_time()
查询
RETURN local_time('21:40:32.142') AS theTime
结果
theTime

21:40:32.142

行：1

localtime.realtime()

详细信息

语法

localtime.realtime([ timezone ])

描述

使用实时时钟返回当前的 LOCAL TIME 瞬时值。

参数

名称

类型

描述

timezone

ANY

表示时区的字符串值。

返回

LOCAL TIME

返回的 LOCAL TIME 将是系统的实时时钟。

示例 58. localtime.realtime()
查询
RETURN localtime.realtime() AS now
结果
now

10:02:31.806895

行：1

localtime.statement()

详细信息

语法

localtime.statement([ timezone ])

描述

使用语句时钟返回当前的 LOCAL TIME 瞬时值。

参数

名称

类型

描述

timezone

ANY

表示时区的字符串值。

返回

LOCAL TIME

此返回的 LOCAL TIME 在同一语句中的每次调用中都是相同的。但是，同一事务内的不同语句可能会产生不同的值。

示例 59. localtime.statement()
查询
RETURN localtime.statement() AS now
结果
now

10:02:31.697

行：1
示例 60. localtime.statement()
查询
RETURN localtime.statement('America/Los Angeles') AS nowInLA
结果
nowInLA

03:02:31.737

行：1

localtime.transaction()

详细信息

语法

localtime.transaction([ timezone ])

描述

使用事务时钟返回当前的 LOCAL TIME 瞬时值。

参数

名称

类型

描述

timezone

ANY

表示时区的字符串值。

返回

LOCAL TIME

返回的 LOCAL TIME 在同一事务中的每次调用中都是相同的。但是，不同的事务可能会产生不同的值。

示例 61. localtime.transaction()
查询
RETURN localtime.transaction() AS now
结果
now

10:02:31.662

行：1

localtime.truncate()

详细信息

语法

localtime.truncate(unit [, input, fields])

描述

使用指定的单位将给定的时间值截断为 LOCAL TIME 瞬时值。

参数

名称

类型

描述

unit

STRING

表示以下之一的字符串：'day', 'week', 'month', 'weekYear', 'quarter', 'year', 'decade', 'century', 'millennium'。

input

ANY

要使用 ZONED DATETIME、LOCAL DATETIME、LOCAL TIME 或 DATE 进行截断的日期。

fields

MAP

在截断期间需要保留的小于 unit 指定的时间组件列表。

返回

LOCAL TIME

localtime.truncate() 返回通过在指定的时间组件边界（由作为参数传递给函数的截断单位表示）处截断指定的时间瞬时值而获得的 LOCAL TIME 值。换句话说，返回的 LOCAL TIME 中所有小于指定截断单位的组件都将被设置为其默认值。

可以通过提供包含小于截断单位的组件的映射来补充被截断的值。这会产生覆盖本应为这些较小组件设置的默认值的效果。例如，当截断单位字符串为 'hour' 时，可以提供 minute（带有某个值 x），以确保返回的值将 minute 设置为 x 而不是默认的 minute（即 1）。

注意事项

支持将时间截断为天（即 unit 为 'day'），并返回当天开始时的午夜 (00:00)，无论 input 的值如何。但是，会保留 input 的时区。

fields 中提供的任何组件必须小于 unit；例如，如果 unit 为 'second'，则 fields 不能包含与 minute 相关的信息。

任何未包含在 fields 中且小于 unit 的组件都将被设置为其最小值。

如果未提供 fields，则返回值的、小于 unit 的所有组件都将设置为其默认值。

如果未提供 input，则将其设置为当前时间，即 localtime.truncate(unit) 等同于 localtime.truncate(unit, localtime())。
示例 62. localtime.truncate()
查询
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
结果
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

行：1

time()

详细信息

语法

time([ input, pattern ])

描述

创建一个 ZONED TIME 瞬时值。

参数

名称

类型

描述

input

ANY

可以是时间值的字符串表示、包含键“timezone”的映射，或包含时间值组件（'hour', 'minute', 'second', 'millisecond', 'microsecond', 'nanosecond', 'timezone'）的映射。

pattern

STRING

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

返回

ZONED TIME
时间组件
名称 描述

hour

0 到 23 之间的整数，指定一天中的小时。

minute

0 到 59 之间的整数，指定分钟数。

second

0 到 59 之间的整数，指定秒数。

millisecond

0 到 999 之间的整数，指定毫秒数。

microsecond

0 到 999,999 之间的整数，指定微秒数。

nanosecond

0 到 999,999,999 之间的整数，指定纳秒数。

timezone

指定时区的表达式。
注意事项

如果不提供参数，必须调用 time()（time({}) 无效）。

如果省略 hour，小时组件默认设为 0。

如果省略 minute，分钟组件默认设为 0。

如果省略 second，秒组件默认设为 0。

任何缺失的 millisecond、microsecond 或 nanosecond 值默认设为 0。

如果省略 timezone，时区组件默认设为配置的默认时区。

如果组合提供了 millisecond、microsecond 和 nanosecond（作为同一组参数的一部分），则各个值必须在 0 到 999 的范围内。

hour、minute 和 second 集合中的最小组件可以省略；即可以仅指定 hour 和 minute，但不允许指定 hour 和 second。

仅当同时指定了 second 时，才能指定 millisecond、microsecond 和 nanosecond 中的一个或多个。

时间值的字符串表示必须符合时间和时区定义的格式。

如果省略 timezone，其组件默认设为配置的默认时区。

时间值的字符串表示必须表示有效的时间；例如，表示 15:67 的 temporalValue 无效。

time(null) 返回 null。

如果提供了任何可选参数，这些参数将覆盖 time 的相应组件。

可以使用 time(tt) 来代替 time({time: tt})。

选择 ZONED TIME 或 ZONED DATETIME 值作为 time 组件也会选择其时区。如果选择 LOCAL TIME 或 LOCAL DATETIME，则使用默认时区。在任何情况下，都可以显式覆盖时区。

将 ZONED DATETIME 或 ZONED TIME 作为 time 组件选择并覆盖时区，将调整本地时间以保持相同的时间点。

pattern 参数由实例类型的允许字符构造。
示例 63. time() 获取当前时间（不提供参数）
查询
RETURN time() AS currentTime

返回使用本地时区的当前时间。

结果
currentTime

10:02:32.192Z

行：1
示例 64. time() 提供时区
查询
RETURN time({timezone: 'America/Los Angeles'}) AS currentTimeInLA

返回加利福尼亚的当前时间。

结果
currentTimeInLA

03:02:32.233-07:00

行：1

创建 ZONED TIME 值

示例 65. time()
查询
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
结果
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

行：5
示例 66. time() - 从 STRING 创建 ZONED TIME
查询
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'),
time('6:04', 'k:mm')
] AS theTime
RETURN theTime
结果
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

06:04:00Z

行：9
示例 67. time() - 使用其他时间值作为组件创建 ZONED TIME
查询
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
结果
timeOnly timeTimezone timeSS timeSSTimezone

12:31:14.645876Z

12:31:14.645876+05:00

12:31:42.645876Z

12:31:42.645876+05:00

行：1

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

详细信息

语法

zoned_time([ input, pattern ])

描述

创建一个 ZONED TIME 瞬时值。

参数

名称

类型

描述

input

ANY

时间值或包含时间组件的映射。

pattern

STRING

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

返回

ZONED TIME

此函数是 time() 函数的别名，它是作为 Cypher GQL 一致性的一部分引入的。有关支持的组件和解析行为的详细信息，请参阅 time()。

与 GQL 的差异

在 GQL 中，无效的时间（或时区）字段名称集会引发数据异常 (22G05)；Cypher 使用同等严重程度的错误 (22007/22N12)。Cypher 还允许使用可选的 pattern 参数进行解析；此别名也支持它。GQL 关键字 CURRENT_TIME 没有在 Cypher 中作为保留关键字引入，因为这会破坏现有的使用该名称作为变量的查询。

示例 68. zoned_time()
查询
RETURN zoned_time('21:40:32.142+01:00') AS theTime
结果
theTime

21:40:32.142+01:00

行：1

time.realtime()

详细信息

语法

time.realtime([ timezone ])

描述

使用实时时钟返回当前的 ZONED TIME 瞬时值。

参数

名称

类型

描述

timezone

ANY

表示时区的字符串值。

返回

ZONED TIME

返回的 ZONED TIME 将是系统的实时时钟。

示例 69. time.realtime()
查询
RETURN time.realtime() AS currentTime
结果
currentTime

10:02:32.436948Z

行：1

time.statement()

详细信息

语法

time.statement([ timezone ])

描述

使用语句时钟返回当前的 ZONED TIME 瞬时值。

参数

名称

类型

描述

timezone

ANY

表示时区的字符串值。

返回

ZONED TIME

此返回的 ZONED TIME 在同一语句中的每次调用中都是相同的。但是，同一事务内的不同语句可能会产生不同的值。

示例 70. time.statement()
查询
RETURN time.statement() AS currentTime
结果
currentTime

10:02:32.317Z

行：1
示例 71. time.statement()
查询
RETURN time.statement('America/Los Angeles') AS currentTimeInLA
结果
currentTimeInLA

03:02:32.351-07:00

行：1

time.transaction()

详细信息

语法

time.transaction([ timezone ])

描述

使用事务时钟返回当前的 ZONED TIME 瞬时值。

参数

名称

类型

描述

timezone

ANY

表示时区的字符串值。

返回

ZONED TIME

返回的 ZONED TIME 在同一事务中的每次调用中都是相同的。但是，不同的事务可能会产生不同的值。

示例 72. time.transaction()
查询
RETURN time.transaction() AS currentTime
结果
currentTime

10:02:32.276Z

行：1

time.truncate()

详细信息

语法

time.truncate(unit [, input, fields])

描述

使用指定的单位将给定的时间值截断为 ZONED TIME 瞬时值。

参数

名称

类型

描述

unit

STRING

表示以下之一的字符串：'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day'。

input

ANY

要使用 ZONED DATETIME、LOCAL DATETIME、ZONED TIME 或 LOCAL TIME 进行截断的日期。

fields

MAP

在截断期间需要保留的小于 unit 指定的时间组件列表。

返回

ZONED TIME

time.truncate() 返回通过在指定的时间组件边界（由作为参数传递给函数的截断单位表示）处截断指定的时间瞬时值而获得的 ZONED TIME 值。换句话说，返回的 ZONED TIME 中所有小于指定截断单位的组件都将被设置为其默认值。

可以通过提供包含小于截断单位的组件的映射来补充被截断的值。这会产生覆盖本应为这些较小组件设置的默认值的效果。例如，当截断单位 STRING 为 'hour' 时，可以提供 minute（带有某个值 x），以确保返回的值将 minute 设置为 x 而不是默认的 minute（即 1）。

注意事项

支持将时间截断为天（即 unit 为 'day'），并返回当天开始时的午夜 (00:00)，无论 input 的值如何。但是，会保留 input 的时区。

input 的时区可以被覆盖；例如，time.truncate('minute', input, {timezone: '+0200'})。

如果 input 是 ZONED TIME、ZONED DATETIME（具有时区的值）之一，且时区被覆盖，则不会发生时间转换。

如果 input 是 LOCAL TIME、LOCAL DATETIME、DATE（不具有时区的值）之一，且时区未被覆盖，则将使用配置的默认时区。

fields 中提供的任何组件必须小于 unit；例如，如果 unit 为 'second'，则 fields 不能包含与 minute 相关的信息。

任何未包含在 fields 中且小于 unit 的组件都将被设置为其最小值。

如果未提供 fields，则返回值的、小于 unit 的所有组件都将设置为其默认值。

如果未提供 input，则将其设置为当前时间和时区，即 time.truncate(unit) 等同于 time.truncate(unit, time())。
示例 73. time()
查询
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
结果
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

行：1
© . This site is unofficial and not affiliated with Neo4j, Inc.