日期和时间¶
日期和时间类型的值用于存储、操作和检索日期和时间信息。GQL 内置支持日期和时间类型，可以将其存储为点和边上的属性值。本文介绍日期和时间类型及其用法。
日期和时间值的分类¶
日期和时间值分为两类：时间点和时间段。
- 时间点：表示特定的时间点，例如日期或时间。
- 时间段：表示两个时间点之间的时间差。
时间点¶
时间点可以通过日期、时间、和时区指定。这些元素可以以各种方式组合来创建时间点。时间点类型包括时区日期时间、本地日期时间、日期、时区时间和本地时间。
- 时区日期时间：包括时间、日期和时区。它是最具体的，因为它表示全球范围内的精确时间点。
- 本地日期时间：包括时间和日期，但不包括时区。它表示一个时间点，但仅适用于本地，而非全球。
- 日期：表示日历日期（年、月、日），与时区无关。
- 时区时间：包括时间和时区。它表示在特定时区内的相同时间，但可能在不同的日期出现。
- 本地时间：仅包含时间。这是最不具体的时间类型，只表示一天中的某个时间点，没有任何日期或时区的背景信息。
下表列出了时间点类型、声明关键字及其值范围。
| 类型 | 声明关键字 | 支持日期 | 支持时间 | 支持时区 | 取值范围 |
|---|---|---|---|---|---|
| 时区日期时间 | ZONED DATETIME |
是 | 是 | 是 | -9999-01-01T00:00:00.000000+1400 ~ 9999-12-31T23:59:59.999999-1200 |
| 本地日期时间 | LOCAL DATETIME |
是 | 是 | 否 | -9999-01-01T00:00:00.000000 ~ 9999-12-31T23:59:59.999999 |
| 日期 | DATE |
是 | 否 | 否 | -9999-01-01 ~ 9999-12-31 |
| 时区时间 | ZONED TIME |
否 | 是 | 是 | 00:00:00.000000+1400 ~ 23:59:59.999999-1200 |
| 本地时间 | LOCAL TIME |
否 | 是 | 否 | 00:00:00.000000 ~ 23:59:59.999999 |
- 声明关键字用于在创建属性时指定时间点类型。
- 范围中展示的格式是一个示例。您可以按照自定义的格式指定时间点值。更多信息，请参见日期和时间值的格式。
时间段¶
时间段可以通过年、月、日、小时、分钟、秒、毫秒和微秒这些元素指定。这些元素可以以各种方式组合来创建一个时间段。时间段通过关键字DURATION来声明。时间段值可以是正数、零或负数。更多关于如何指定时间段的信息，请参见指定时间段。
日期和时间值的格式¶
您可以灵活定义表示这些日期和时间类型的值的格式，然而，所选格式必须遵循 ISO 8601 标准。 一旦指定了所需的格式，您应按照该格式提供时间值。
在以下示例中，%Y-%m-%dT%H:%M:%S是您定义的时间值格式，而2012-03-04T05:06:07.0890是按照该格式指定的值。
local_datetime("2012-03-04T05:06:07.0890", "%Y-%m-%dT%H:%M:%S") AS localdatetime
Note
- 在 GQL 中，您需要使用时间函数插入时间类型的属性值。
- 若按照默认时间值格式指定时间值，可以省略时间值格式。例如，上述示例中可以直接使用
local_datetime("2012-03-04T05:06:07.0890")而不需要指定格式。
时间值格式是由以下元素组成的字符串：
| 元素 | 描述 | 取值范围 |
|---|---|---|
%Y |
年 | -9999 ~ 9999 |
%y |
两位数的年份 | 00 ~ 99 |
%m |
两位数的月份 | 01 ~ 12 |
%d |
两位数的日期 | 01 ~ 31 |
%H |
24 小时制的小时 | 00 ~ 23 |
%I |
12 小时制的小时 | 01 ~ 12 |
%M |
两位数的分钟 | 00 ~ 59 |
%S |
两位数的秒。 包括小数秒，最多支持小数点后六位。 如果未指定小数秒，则在小数点右侧填充零。 |
00 ~ 59.999999 |
%f |
小数秒 | 000000 ~ 999999 |
%a |
缩写的星期名称 | Mon, Tue, Wed, Thu, Fri, Sat, Sun |
%A |
完整的星期名称 | Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday |
%b |
缩写的月份名称 | Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec |
%B |
完整的月份名称 | January, February, March, April, May, June, July, August, September, October, November, December |
%z |
相对于 UTC 的时区偏移。例如，-0430表示比 UTC 慢 4 小时 30 分钟。如果偏移为零，则使用+0000。 |
-1200 ~ +1400 |
%Ez |
类似于%z，区别在于小时和分钟之间需要一个冒号，例如：-04:30。如果偏移为零，则使用+00:00。 |
-12:00 ~ +14:00 |
指定时间¶
使用%H/%I、%M、%S和%z/%Ez元素来指定时间格式，例如，05:06:07.089是以%H:%M:%S格式指定的时间。格式中必须包含%H/%I元素。
时间可以是时区时间（默认格式：%H:%M:%S %z）或本地时间（默认格式：%H:%M:%S）。如果指定了时区，则为时区时间；否则为本地时间。例如：
-
本地时间：
local_time("05:06:07.089", "%H:%M:%S") AS localtime
-
时区时间：
zoned_time("05:06:07.089 +08:00", "%H:%M:%S %Ez") AS zonetime
小数秒的尾随零可以省略。例如，05:06:07.089000可以表示为05:06:07.089。注意，如果小数秒的位数少于最大位数，将在末尾填充零以达到所需长度。
如果未指定时间元素，则时间默认为00:00:00.000000。
指定时区¶
时区是全球范围内在法律、商业和社会活动中使用统一标准时间的区域。它通过时区偏移来表示本地时间与世界标准时间（UTC）之间的差异。
使用%z或%Ez元素可以指定时区格式。当时区偏移与本地时间一起使用时，结果会转换为 UTC 时间。关于全球各个地区的时区标识及其偏移，请参见时区列表。
在指定 UTC 时区偏移时，请遵循以下准则：
- 偏移应解析为四位数字，如
HHMM，其中HH表示小时，MM表示分钟。小时和分钟之间可以使用冒号（:）分隔，例如+08:00。- 当使用
%z时格式化时区时，值必须是四位数字。 - 当使用
%Ez时格式化时区时，值必须是四位数字，且小时和分钟之间必须使用冒号分隔。
- 当使用
- 如果本地时间早于 UTC，偏移为正，用
+号表示或无符号表示。 - 如果本地时间晚于 UTC，偏移为负，用
-号表示。 - 如果在时区日期时间和时区时间中未指定时区的元素和对应的值，则当偏移量为零时，时区默认为
+00:00。
以下示例展示了如何使用%z元素指定时区偏移。2016-09-20T01:01:01.123456是本地时间，+0800是时区偏移。返回值2016-09-20T01:01:01.123456+08:00是转换后的世界标准时间。
zoned_datetime("2016-09-20T01:01:01.123456 +0800", "%Y-%m-%dT%H:%M:%S %z") AS zoneddatetime
指定日期¶
使用%Y/%y、%m/%b/%B、%d和%a/%A元素可以指定日期格式。例如，Tue, 2016-09-20是格式为%a, %Y-%m-%d的日期值。格式中必须包含%Y/%y、%m/%b/%B和%d元素。
日期的默认格式为%Y-%m-%d。如果同时指定了日期和对应的星期几，返回结果中星期几会被忽略。例如：
date("Tue, 2016-09-20", "%a, %Y-%m-%d") AS d
上述例子中，Tue, 2016-09-20T01:01:01等同于2016-09-20T01:01:01。如果日期和星期几不匹配，则会返回解析错误。
指定日期和时间¶
日期时间是日期和时间的组合。您可以使用日期和时间元素来指定日期时间。日期和时间元素之间需使用分隔符，如T。例如，2016-09-20T01:01:01是格式为%Y-%m-%dT%H:%M:%S的日期时间的值。格式中必须包含%Y/%y、%m/%b/%B和%d元素。
日期时间可以是带时区的日期时间（默认格式：%Y-%m-%dT%H:%M:%S %z）或本地日期时间（默认格式：%Y-%m-%dT%H:%M:%S）。如果指定了时区，则日期时间是带时区的日期时间；否则，它是本地日期时间。例如：
-
不指定时区的日期时间：
local_datetime("2016-09-20T01:01:01.123456", "%Y-%m-%dT%H:%M:%S") AS localdatetime
-
指定时区的日期时间：
zoned_datetime("2016-09-20T01:01:01.123456 +08:00", "%Y-%m-%dT%H:%M:%S %Ez") AS zoneddatetime
指定时间段¶
指定时间段格式时，支持使用以下时间段单位组：
- 基于年和月的时间段单位组：
years和months，例如duration({years: 100, months: 1})。 - 基于天和时间的时间段单位组：
days、hours、minutes、seconds、milliseconds和microseconds，例如duration({days: 1, hours: 2, minutes: 3, seconds: 4, milliseconds: 4, microseconds: 5})。
对于每个单位组，单位值以映射的形式指定。单位值可以是正整数、零或负整数。可以通过多种方式组合单位值来创建时间段。映射中的单位是可选的。如果未指定单位，则该值默认为零。有关指定时间段的示例，请参见时间函数 duration()。
日期和时间值的运算¶
支持使用以下运算符或函数对日期和时间值进行运算。运算示例，请参见时间点和时间段之间的运算。
| 运算对象 1 | 函数/运算符 | 运算对象 2 | 结果 |
|---|---|---|---|
| 时间点 | duration_between() |
时间点 | 时间段 |
| 时间点 | +或者- |
时间段 | 时间点 |
| 时间段 | + |
时间点 | 时间点 |
| 时间段 | +或者- |
时间段 | 时间段 |
| 时间段 | *或者/ |
数字 | 时间段 |
| 数字 | * |
时间段 | 时间段 |
时间点的组成部分¶
时间点支持通过点号（.）运算符来访问其组成部分。下表列出了支持的组成部分并提供了访问示例。
| 组成部分 | 描述 | 日期和时间函数示例 | 日期和时间字面量示例 |
|---|---|---|---|
year |
时间点的年份 | RETURN zoned_datetime("2016-09-20T01:01:01 +08:00", "%Y-%m-%dT%H:%M:%S %Ez").year AS year |
RETURN DATETIME "2016-09-20T01:01:01+0800".year AS year |
month |
时间点的月份 | RETURN date("Tue, 2016-09-20", "%a, %Y-%m-%d").month AS month |
RETURN DATE "2016-09-20".month AS month |
day |
时间点的日期 | RETURN local_datetime("2016-09-20T01:01:01", "%Y-%m-%dT%H:%M:%S").day AS day |
RETURN DATETIME "2016-09-20T01:01:01".day AS day |
hour |
时间点的小时数 | RETURN zoned_time("05:06:07.089 +08:00", "%H:%M:%S %Ez").hour AS hour |
RETURN TIME "05:06:07.089+0800".hour AS hour |
minute |
时间点的分钟数 | RETURN zoned_time("05:06:07.089 +08:00", "%H:%M:%S %Ez").minute AS minute |
RETURN TIME "05:06:07.089+0800".minute AS minute |
second |
时间点的秒数 | RETURN local_time("05:06:07.089", "%H:%M:%S").second AS second |
RETURN TIME "05:06:07.089".second AS second |
当访问时间点中不包含的组成部分时，遵循以下规则：
- 当访问时区时间（
ZONED TIME）或本地时间（LOCAL TIME）的year、month或day时，返回当前日期的相应值。 - 当访问日期（
DATE）的hour、minute或second时，返回值统一为0。