时间函数 - 时刻类型

时间时刻类型

时间时刻类型创建概述

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

  • 捕获当前时间。

  • 组合类型的组件。

  • 解析时间值的 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 和 ZONED DATETIME）都允许为检索当前时刻的函数指定时区。这允许在指定的时区中检索当前时刻。

控制使用哪个时钟

基于当前时刻创建时间时刻值的函数默认使用 statement 时钟。但是，有三个不同的时钟可用于更细粒度的控制

  • transaction：在同一事务中的每次调用中都会生成相同的时刻。对于不同的事务，可能会生成不同的时间。

  • statement：在同一语句中的每次调用中都会生成相同的时刻。对于同一事务中的不同语句，可能会生成不同的时间。

  • realtime：生成的时刻将是系统的实时时钟。

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

类型 默认 事务 语句 实时

日期

date()

date.transaction()

date.statement()

date.realtime()

时间

time()

time.transaction()

time.statement()

time.realtime()

本地时间

localtime()

localtime.transaction()

localtime.statement()

localtime.realtime()

日期时间

datetime()

datetime.transaction()

datetime.statement()

datetime.realtime()

本地日期时间

localdatetime()

localdatetime.transaction()

localdatetime.statement()

localdatetime.realtime()

截断时间值

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

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

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

截断单位 DATE ZONED TIME LOCAL TIME ZONED DATETIME LOCAL DATETIME

千年

date.truncate('millennium', input)

datetime.truncate('millennium', input)

localdatetime.truncate('millennium', input)

世纪

date.truncate('century', input)

datetime.truncate('century', input)

localdatetime.truncate('century', input)

十年

date.truncate('decade', input)

datetime.truncate('decade', input)

localdatetime.truncate('decade', input)

年

date.truncate('year', input)

datetime.truncate('year', input)

localdatetime.truncate('year', input)

年份

date.truncate('weekYear', input)

datetime.truncate('weekYear', input)

localdatetime.truncate('weekYear', input)

季度

date.truncate('quarter', input)

datetime.truncate('quarter', input)

localdatetime.truncate('quarter', input)

月份

date.truncate('month', input)

datetime.truncate('month', input)

localdatetime.truncate('month', input)

星期

date.truncate('week', input)

datetime.truncate('week', input)

localdatetime.truncate('week', input)

日期

date.truncate('day', input)

time.truncate('day', input)

localtime.truncate('day', input)

datetime.truncate('day', input)

localdatetime.truncate('day', input)

小时

time.truncate('hour', input)

localtime.truncate('hour', input)

datetime.truncate('hour', input)

localdatetime.truncate('hour',input)

分钟

time.truncate('minute', input)

localtime.truncate('minute', input)

datetime.truncate('minute', input)

localdatetime.truncate('minute', input)

秒

time.truncate('second', input)

localtime.truncate('second', input)

datetime.truncate('second', input)

localdatetime.truncate('second', input)

毫秒

time.truncate('millisecond', input)

localtime.truncate('millisecond', input)

datetime.truncate('millisecond', input)

localdatetime.truncate('millisecond', input)

微秒

time.truncate('microsecond', input)

localtime.truncate('microsecond', input)

datetime.truncate('microsecond', input)

localdatetime.truncate('microsecond', input)

date()

详情

语法

date( [input] )

描述

创建一个 DATE 实例。

参数

名称

类型

描述

input

任意类型

可以是时间值的字符串表示形式，包含单个键“timezone”的映射，或者包含时间值（“date”，“year”，“month”，“day”，“week”，“dayOfWeek”，“quarter”，“dayOfQuarter”，“ordinalDay”）作为组件的映射。

返回值

DATE
时间组件
名称 描述

date

一个 DATE 值。

年

一个由至少四位数字组成的表达式，指定年份。

月份

一个介于1和12之间的整数，指定月份。

日期

一个介于1和31之间的整数，指定月份中的日期。

星期

一个介于1和53之间的整数，指定星期。

dayOfWeek

一个介于1和7之间的整数，指定星期几。

季度

一个介于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})。
示例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')
] AS theDate
RETURN theDate
结果
theDate

2015-07-21

2015-07-01

2015-07-01

2015-07-21

2015-07-21

2015-01-01

行数：6

date.realtime()

详情

语法

date.realtime([ timezone ])

描述

使用实时时钟返回当前DATE实例。

参数

名称

类型

描述

timezone

任意类型

表示时区的字符串值。

返回值

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

任意类型

表示时区的字符串值。

返回值

DATE

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

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

2022-06-14

行数：1

date.transaction()

详情

语法

date.transaction([ timezone ])

描述

使用事务时钟返回当前DATE实例。

参数

名称

类型

描述

timezone

任意类型

表示时区的字符串值。

返回值

DATE

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

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

2022-06-14

行数：1

date.truncate()

详情

语法

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

描述

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

参数

名称

类型

描述

unit

字符串

表示以下其中之一的字符串：“day”，“week”，“month”，“weekYear”，“quarter”，“year”，“decade”，“century”，“millennium”。

input

任意类型

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

fields

映射

在截断期间保留的时间组件列表，这些组件小于unit中指定的组件。

返回值

DATE

date.truncate()返回通过在指定组件边界（由传递给函数的参数中的截断单位表示）的最近前一时间点截断指定时间实例值获得的DATE值。换句话说，返回的DATE将具有所有小于指定截断单位的组件，这些组件设置为其默认值。

可以通过提供包含小于截断单位的组件的映射来补充截断值。这将具有覆盖否则将为这些较小组件设置的默认值的效果。例如，当截断单位STRING为'year'时，可以提供day（具有一定值x），以确保返回的值将day设置为x而不是默认day（为1）。

注意事项

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

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 ])

描述

创建一个 ZONED DATETIME 实例。

参数

名称

类型

描述

input

任意类型

可以是时间值的字符串表示形式，包含单个键“timezone”的映射，或者包含时间值（“year”，“month”，“day”，“hour”，“minute”，“second”，“millisecond”，“microsecond”，“nanosecond”，“timezone”）作为组件的映射。

返回值

ZONED DATETIME
时间组件
名称 描述

年

一个由至少四位数字组成的表达式，指定年份。

月份

一个介于1和12之间的整数，指定月份。

日期

一个介于1和31之间的整数，指定月份中的日期。

小时

一个介于0和23之间的整数，指定一天中的小时。

分钟

一个介于0和59之间的整数，指定分钟数。

秒

一个介于0和59之间的整数，指定秒数。

毫秒

一个介于0和999之间的整数，指定毫秒数。

微秒

一个介于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，则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。
示例 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]')
] 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]

行数：8
示例 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值。

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

查询
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

datetime.fromEpoch()

详情

语法

datetime.fromepoch(seconds, nanoseconds)

描述

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

参数

名称

类型

描述

秒

INTEGER | FLOAT

UTC 时区中自 UNIX 纪元以来的秒数。

纳秒

INTEGER | FLOAT

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

返回值

ZONED DATETIME
示例 27. 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。

参数

名称

类型

描述

毫秒

INTEGER | FLOAT

UTC 时区中自 UNIX 纪元以来的毫秒数。

返回值

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

2024-08-21T00:00Z

行数：1

datetime.realtime()

详情

语法

datetime.realtime([ timezone ])

描述

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

参数

名称

类型

描述

timezone

任意类型

表示时区的字符串值。

返回值

ZONED DATETIME

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

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

2022-06-14T10:02:28.494444Z

行数：1

datetime.statement()

详情

语法

datetime.statement([ timezone ])

描述

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

参数

名称

类型

描述

timezone

任意类型

表示时区的字符串值。

返回值

ZONED DATETIME

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

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

2022-06-14T10:02:28.395Z

行数：1

datetime.transaction()

详情

语法

datetime.transaction([ timezone ])

描述

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

参数

名称

类型

描述

timezone

任意类型

表示时区的字符串值。

返回值

ZONED DATETIME

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

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

2022-06-14T10:02:28.290Z

行数：1
示例 32. 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

字符串

表示以下之一的字符串：“微秒”、“毫秒”、“秒”、“分钟”、“小时”、“天”、“周”、“月”、“周年度”、“季度”、“年”、“十年”、“百年”、“千年”。

input

任意类型

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

fields

映射

在截断期间保留的时间组件列表，这些组件小于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不能包含与月相关的信息。

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

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

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

描述

创建一个LOCAL DATETIME瞬间。

参数

名称

类型

描述

input

任意类型

时间值的字符串表示、包含单个键“timezone”的映射或包含时间值（“year”、“month”、“day”、“hour”、“minute”、“second”、“millisecond”、“microsecond”、“nanosecond”）作为组件的映射。

返回值

LOCAL DATETIME
时间组件
名称 描述

一个包含以下内容的单个映射

年

一个由至少四位数字组成的表达式，指定年份。

月份

一个介于1和12之间的整数，指定月份。

日期

一个介于1和31之间的整数，指定月份中的日期。

小时

一个介于0和23之间的整数，指定一天中的小时。

分钟

一个介于0和59之间的整数，指定分钟数。

秒

一个介于0和59之间的整数，指定秒数。

毫秒

一个介于0和999之间的整数，指定毫秒数。

微秒

一个介于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})。
示例 34. localdatetime() - 获取当前本地日期和时间（无参数）
查询
RETURN localdatetime() AS now

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

结果
now

2022-06-14T10:02:30.447

行数：1
示例 35. 带有时区的 localdatetime()
查询
RETURN localdatetime({timezone: 'America/Los Angeles'}) AS now

返回加州的当前本地日期和时间。

结果
now

2022-06-14T03:02:30.482

行数：1

创建LOCAL DATETIME值

示例 36. 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
示例 37. 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
示例 38. 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
示例 39. 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
示例 40. localdatetime() - 从STRING创建LOCAL DATETIME
查询
UNWIND [
localdatetime('2015-07-21T21:40:32.142'),
localdatetime('2015-W30-2T214032.142'),
localdatetime('2015-202T21:40:32'),
localdatetime('2015202T21')
] 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

行数：4
示例 41. 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
示例 42. 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
示例 43. 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
示例 44. 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

localdatetime.realtime()

详情

语法

localdatetime.realtime([ timezone ])

描述

使用实时时钟返回当前LOCAL DATETIME实例。

参数

名称

类型

描述

timezone

任意类型

表示时区的字符串值。

返回值

LOCAL DATETIME

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

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

2022-06-14T10:02:30.647817

行数：1
示例 46. 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

任意类型

表示时区的字符串值。

返回值

LOCAL DATETIME

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

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

2022-06-14T10:02:30.570

行数：1

localdatetime.transaction()

详情

语法

localdatetime.transaction([ timezone ])

描述

使用事务时钟返回当前LOCAL DATETIME实例。

参数

名称

类型

描述

timezone

任意类型

表示时区的字符串值。

返回值

LOCAL DATETIME

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

示例 48. 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

字符串

表示以下之一的字符串：“微秒”、“毫秒”、“秒”、“分钟”、“小时”、“天”、“周”、“月”、“周年度”、“季度”、“年”、“十年”、“百年”、“千年”。

input

任意类型

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

fields

映射

在截断期间保留的时间组件列表，这些组件小于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())。
示例 49. 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 ])

描述

创建一个LOCAL TIME实例。

参数

名称

类型

描述

input

任意类型

时间值的字符串表示形式、包含单个键“timezone”的映射或包含时间值（“hour”、“minute”、“second”、“millisecond”、“microsecond”、“nanosecond”作为组件）的映射。

返回值

LOCAL TIME
时间组件
名称 描述

小时

一个介于0和23之间的整数，指定一天中的小时。

分钟

一个介于0和59之间的整数，指定分钟数。

秒

一个介于0和59之间的整数，指定秒数。

毫秒

一个介于0和999之间的整数，指定毫秒数。

微秒

一个介于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中的一个或多个。

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

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

localtime(null)返回null。

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

可以将localtime(tt)写成localtime({time: tt})。
示例 50. localtime() 获取当前时间（无参数）
查询
RETURN localtime() AS now

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

结果
now

10:02:31.596

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

返回加州的当前本地时间。

结果
nowInLA

03:02:31.629

行数：1

创建LOCAL TIME值

示例 52. 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
示例 53. localtime() - 从STRING创建LOCAL TIME
查询
UNWIND [
localtime('21:40:32.142'),
localtime('214032.142'),
localtime('21:40'),
localtime('21')
] AS theTime
RETURN theTime
结果
theTime

21:40:32.142

21:40:32.142

21:40

21:00

行数：4
示例 54. 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

localtime.realtime()

详情

语法

localtime.realtime([ timezone ])

描述

使用实时时钟返回当前LOCAL TIME实例。

参数

名称

类型

描述

timezone

任意类型

表示时区的字符串值。

返回值

LOCAL TIME

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

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

10:02:31.806895

行数：1

localtime.statement()

详情

语法

localtime.statement([ timezone ])

描述

使用语句时钟返回当前LOCAL TIME实例。

参数

名称

类型

描述

timezone

任意类型

表示时区的字符串值。

返回值

LOCAL TIME

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

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

10:02:31.697

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

03:02:31.737

行数：1

localtime.transaction()

详情

语法

localtime.transaction([ timezone ])

描述

使用事务时钟返回当前LOCAL TIME实例。

参数

名称

类型

描述

timezone

任意类型

表示时区的字符串值。

返回值

LOCAL TIME

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

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

10:02:31.662

行数：1

localtime.truncate()

详情

语法

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

描述

使用指定的单位将给定的时间值截断到LOCAL TIME实例。

参数

名称

类型

描述

unit

字符串

表示以下其中之一的字符串：“day”，“week”，“month”，“weekYear”，“quarter”，“year”，“decade”，“century”，“millennium”。

input

任意类型

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

fields

映射

在截断期间保留的时间组件列表，这些组件小于unit中指定的组件。

返回值

LOCAL TIME

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

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

注意事项

将时间截断到天（即unit为'day'）是受支持的，并且无论input的值如何，都会产生当天开始时的午夜（00:00）。但是，将保留input的时区。

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

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

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

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

描述

创建一个ZONED TIME实例。

参数

名称

类型

描述

input

任意类型

时间值的字符串表示形式、包含单个键“timezone”的映射或包含时间值（“hour”、“minute”、“second”、“millisecond”、“microsecond”、“nanosecond”、“timezone”作为组件）的映射。

返回值

ZONED TIME
时间组件
名称 描述

小时

一个介于0和23之间的整数，指定一天中的小时。

分钟

一个介于0和59之间的整数，指定分钟数。

秒

一个介于0和59之间的整数，指定秒数。

毫秒

一个介于0和999之间的整数，指定毫秒数。

微秒

一个介于0和999,999之间的整数，指定微秒数。

nanosecond

一个介于0和999,999,999之间的整数，指定纳秒数。

timezone

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

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

如果省略了hour，则小时组件将默认为0。

如果省略了minute，则分钟组件将默认为0。

如果省略了second，则秒组件将默认为0。

任何缺少的millisecond、microsecond或nanosecond值都将默认为0。

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

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

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

只有在也指定了second的情况下，才能指定millisecond、microsecond和nanosecond中的一个或多个。

时间值的字符串表示形式必须符合为times和time zones定义的格式。

如果省略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组件并覆盖时区将调整本地时间以保持相同的时间点。
示例 60. time() 获取当前时间（无参数）
查询
RETURN time() AS currentTime

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

结果
currentTime

10:02:32.192Z

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

返回加州的当前时间。

结果
currentTimeInLA

03:02:32.233-07:00

行数：1

创建ZONED TIME值

示例 62. 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
示例 63. 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')
] 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

行数：8
示例 64. 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

time.realtime()

详情

语法

time.realtime([ timezone ])

描述

使用实时时钟返回当前ZONED TIME实例。

参数

名称

类型

描述

timezone

任意类型

表示时区的字符串值。

返回值

ZONED TIME

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

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

10:02:32.436948Z

行数：1

time.statement()

详情

语法

time.statement([ timezone ])

描述

使用语句时钟返回当前ZONED TIME实例。

参数

名称

类型

描述

timezone

任意类型

表示时区的字符串值。

返回值

ZONED TIME

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

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

10:02:32.317Z

行数：1
示例 67. 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

任意类型

表示时区的字符串值。

返回值

ZONED TIME

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

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

10:02:32.276Z

行数：1

time.truncate()

详情

语法

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

描述

使用指定的单位将给定的时间值截断到ZONED TIME实例。

参数

名称

类型

描述

unit

字符串

表示以下内容之一的字符串：“microsecond”、“millisecond”、“second”、“minute”、“hour”、“day”。

input

任意类型

要截断的日期，可以使用ZONED DATETIME、LOCAL DATETIME、ZONED TIME或LOCAL TIME。

fields

映射

在截断期间保留的时间组件列表，这些组件小于unit中指定的组件。

返回值

ZONED TIME

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

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

注意事项

将时间截断到天（即unit为'day'）是受支持的，并且无论input的值如何，都会产生当天开始时的午夜（00:00）。但是，将保留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())。
示例 69. 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