时间函数 - 即时类型

时间函数允许创建和操作每种时间类型 — `DATE`、`ZONED TIME`、`LOCAL TIME`、`ZONED DATETIME` 和 `LOCAL DATETIME` 的值。

本页面包含以下函数

DATE ZONED DATETIME LOCAL DATETIME LOCAL TIME ZONED TIME

`DATE`	`ZONED DATETIME`	`LOCAL DATETIME`	`LOCAL TIME`	`ZONED TIME`
date()	datetime()	localdatetime()	localtime()	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()

datetime.fromEpochMillis()

date.realtime()

datetime.realtime()

localdatetime.realtime()

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 和 ZONED DATETIME — 都允许为检索当前即时值的函数指定时区。这允许在指定时区中检索当前即时值。

控制使用哪个时钟

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

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

Time

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

截断单位	`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.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`	`ANY`	可以是时间值的字符串表示形式，包含单个键 '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`	`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' 时，可以提供具有某个值 x 的 day，以确保返回值的*日*被设置为 x，而不是默认的*日*（即 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`	`ANY`	可以是时间值的字符串表示形式，包含单个键 '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`	表示从 UNIX 纪元开始在 UTC 时区的秒数的数值。
`epochMillis`	表示从 UNIX 纪元开始在 UTC 时区的毫秒数的数值。

注意事项
如果未提供参数，则必须调用 `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。

示例 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() 返回从 UNIX 纪元开始在 UTC 时区以指定*秒*数或*毫秒*数表示的 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`。
参数	名称	类型	描述
	`seconds`	`INTEGER \| FLOAT`	从 UNIX 纪元开始在 UTC 时区的秒数。
	`nanoseconds`	`INTEGER \| FLOAT`	从 UNIX 纪元开始在 UTC 时区的纳秒数。此值可以添加到秒数中。
返回	`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`。
参数	名称	类型	描述
	`milliseconds`	`INTEGER \| FLOAT`	从 UNIX 纪元开始在 UTC 时区的毫秒数。
返回	`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`	`ANY`	表示时区的字符串值。
返回	`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`	`ANY`	表示时区的字符串值。
返回	`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`	`ANY`	表示时区的字符串值。
返回	`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`	`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 的所有小于指定截断单位的组件都将设置为其默认值。

注意事项
如果 `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`	`ANY`	可以是时间值的字符串表示形式，包含单个键 '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`	`ANY`	表示时区的字符串值。
返回	`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`	`ANY`	表示时区的字符串值。
返回	`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`	`ANY`	表示时区的字符串值。
返回	`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`	`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 的所有小于指定截断单位的组件都将设置为其默认值。

注意事项
如果 `unit` 是以下之一：`'hour'`、`'minute'`、`'second'`、`'millisecond'`、`'microsecond'`，则 `input` 不能是 `DATE` 值。
`fields` 中提供的任何组件都必须小于 `input`；即，如果 `input` 是 `'day'`，则 `fields` 不能包含有关月份的信息。
任何未包含在 `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`	`ANY`	可以是时间值的字符串表示形式，包含单个键 '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`。
时间值的字符串表示形式必须符合为时间定义的格式。
时间值的字符串表示形式必须表示有效时间；即表示 `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`	`ANY`	表示时区的字符串值。
返回	`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`	`ANY`	表示时区的字符串值。
返回	`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`	`ANY`	表示时区的字符串值。
返回	`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`	`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' 时，可以提供具有某个值 x 的 minute，以确保返回值的*分钟*被设置为 x，而不是默认的*分钟*（即 1）。

注意事项
支持将时间截断到日 — 即 `unit` 为 `'day'` — 无论 `input` 的值如何，都会生成当天的午夜 (`00:00`)。但是，`input` 的时区会保留。
`fields` 中提供的任何组件都必须小于 `unit`；即，如果 `unit` 是 `'second'`，则 `fields` 不能包含有关分钟的信息。
任何未包含在 `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`	`ANY`	可以是时间值的字符串表示形式，包含单个键 '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`，则时区组件将默认为配置的默认时区。
如果 `millisecond`、`microsecond` 和 `nanosecond` 组合提供（作为同一组参数的一部分），则每个值必须在 `0` 到 `999` 范围内。
集合 `hour`、`minute` 和 `second` 中最小的组件可以省略；即，可以只指定 `hour` 和 `minute`，但不能指定 `hour` 和 `second`。
只有在也指定了 `second` 的情况下，才能指定一个或多个 `millisecond`、`microsecond` 和 `nanosecond`。
时间值的字符串表示形式必须符合为时间和时区定义的格式。
如果省略时区组件，则将默认为配置的默认时区。
时间值的字符串表示形式必须表示有效时间；即表示 `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`	`ANY`	表示时区的字符串值。
返回	`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`	`ANY`	表示时区的字符串值。
返回	`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`	`ANY`	表示时区的字符串值。
返回	`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`	`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' 时，可以提供具有某个值 x 的 minute，以确保返回值的*分钟*被设置为 x，而不是默认的*分钟*（即 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` 不能包含有关分钟的信息。
任何未包含在 `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

时间函数 - 即时类型

时间即时类型

时间即时类型创建概述

控制使用哪个时钟

截断时间值

date()

创建 DATE 值

date.realtime()

date.statement()

date.transaction()

date.truncate()

datetime()

创建 ZONED DATETIME 值

datetime.fromEpoch()

datetime.fromEpochMillis()

datetime.realtime()

datetime.statement()

datetime.transaction()

datetime.truncate()

localdatetime()

创建 LOCAL DATETIME 值

localdatetime.realtime()

localdatetime.statement()

localdatetime.transaction()

localdatetime.truncate()

localtime()

创建 LOCAL TIME 值

localtime.realtime()

localtime.statement()

localtime.transaction()

localtime.truncate()

time()

创建 ZONED TIME 值

time.realtime()

time.statement()

time.transaction()

time.truncate()

创建 `DATE` 值

创建 `ZONED DATETIME` 值

创建 `LOCAL DATETIME` 值

创建 `LOCAL TIME` 值

创建 `ZONED TIME` 值