Source: https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/temporal-type/ Documentation version: v5.3.2 # 日期和时间 日期和时间类型的值用于存储、操作和检索日期和时间信息。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 - 声明关键字用于在创建属性时指定时间点类型。 - 范围中展示的格式是一个示例。您可以按照自定义的格式指定时间点值。更多信息，请参见[日期和时间值的格式](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/temporal-type/#_5)。 ### 时间段 时间段可以通过年、月、日、小时、分钟、秒、毫秒和微秒这些元素指定。这些元素可以以各种方式组合来创建一个时间段。时间段通过关键字`DURATION`来声明。时间段值可以是正数、零或负数。更多关于如何指定时间段的信息，请参见[指定时间段](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/temporal-type/#_10)。 ## 日期和时间值的格式 您可以灵活定义表示这些日期和时间类型的值的格式，然而，所选格式必须遵循 [ISO 8601 标准](https://www.iso.org/iso-8601-date-and-time-format.html)。 一旦指定了所需的格式，您应按照该格式提供时间值。 在以下示例中，`%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 中，您需要使用[时间函数](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/temporal/)插入时间类型的属性值。 - 若按照默认时间值格式指定时间值，可以省略时间值格式。例如，上述示例中可以直接使用`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 时间。关于全球各个地区的时区标识及其偏移，请参见[时区列表](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)。 在指定 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()](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/temporal/#duration)。 ## 日期和时间值的运算 支持使用以下运算符或函数对日期和时间值进行运算。运算示例，请参见[时间点和时间段之间的运算](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/temporal/#_34)。 | 运算对象 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`。 ## 更多信息 - [日期和时间函数](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/temporal/) - [日期和时间字面量](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/literals/#_13)