Source: https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/temporal/
Documentation version: v5.3.2

# 日期和时间函数

本文描述悦数图数据库开发版中的日期和时间函数用法，适用于持久图和临时图。

本文介绍如何使用日期和时间函数来创建和操作日期和时间类型的值。这些日期和时间类型包括`DATE`、`ZONED TIME`、`LOCAL TIME`、`ZONED DATETIME`、`LOCAL DATETIME`和`DURATION`。有关日期和时间类型的更多信息，请参见[日期和时间类型](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/temporal-type/)。

您可以在日期和时间函数中定义传入的日期和时间值格式。同时，可以使用默认格式传入值。查看日期和时间函数的默认格式，请参见 [SHOW CURRENT_SESSION TIME FORMATS](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-admin/show/show-current-session-time-formats/)。

## date()

将字符串解析为日期。

NULL 行为：默认

### 函数签名

````
date(s: STRING) -> DATE

````

### 示例

````
RETURN date('2022-01-02') AS `date`

````

返回：

````
+------------+
| date       |
+------------+
| 2022-01-02 |
+------------+

````

## local_datetime()

将字符串解析为本地的日期时间。

NULL 行为：默认

### 函数签名

````
local_datetime(datetime: str, format: str) -> LOCAL DATETIME

````

### 示例

#### 解析带有小数秒的本地的日期时间

````
RETURN local_datetime("2012-03-04T05:06:07.0890", "%Y-%m-%dT%H:%M:%S") AS localdatetime

````

上述示例使用格式`%Y-%m-%dT%H:%M:%S`格式化本地的日期时间。入参`2012-03-04T05:06:07.0890`被解析为`2012-03-04T05:06:07.089000`。

返回： 

````
+----------------------------+
| localdatetime              |
+----------------------------+
| 2012-03-04T05:06:07.089000 |
+----------------------------+

````

#### 解析不带小数秒的本地的日期时间

````
RETURN local_datetime("2012-03-04T05:06:07", "%Y-%m-%dT%H:%M:%S") AS localdatetime

````

上述示例使用格式`%Y-%m-%dT%H:%M:%S`格式化不带小数秒的本地的日期时间，小数秒将默认为`000000`。入参`2012-03-04T05:06:07`被解析为`2012-03-04T05:06:07.000000`。

返回：

````
+----------------------------+
| localdatetime              |
+----------------------------+
| 2012-03-04T05:06:07.000000 |
+----------------------------+

````

#### 插入和查询本地的日期时间

以下示例数据基于[示例数据集](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/overview/example-dataset/)。本示例将一个本地的日期时间插入到图中，并查询插入的日期时间。

插入本地的日期时间：

````
'''
// 定义具有本地日期时间属性的图类型
ALTER GRAPH TYPE movie_type {ADD NODE `local_datetime` ({id INT PRIMARY KEY, event LOCAL DATETIME})} 
'''
'''
// 插入本地的日期时间
USE movie INSERT (@`local_datetime`{id:1, event:local_datetime("2012-03-04T05:06:07", "%Y-%m-%dT%H:%M:%S")})
'''

````

查询插入的本地的日期时间：

````
USE movie MATCH (a@`local_datetime`{id:1}) RETURN a

````

返回：

````
+-----------------------------------------------------------------------------+
| a                                                                           |
+-----------------------------------------------------------------------------+
| (289670744974032900@local_datetime:{event:2012-03-04T05:06:07.000000,id:1}) |
+-----------------------------------------------------------------------------+

````

## zoned_datetime()

将字符串解析为带时区的日期时间，并返回带会话时区的日期时间。

NULL 行为：默认

### 函数签名

````
zoned_datetime(datetime: str, format: str) -> ZONED DATETIME

````

### 示例

#### 解析带有指定时区的日期时间

````
RETURN zoned_datetime("2012-03-04ZONE05:06:07.123 AT -02:00", "%Y-%m-%dZONE%H:%M:%S AT %Ez") AS zoneddatetime

````

上述示例使用格式`%Y-%m-%dZONE%H:%M:%S AT %Ez`指定带时区的日期时间。值`2012-03-04ZONE05:06:07 AT -02:00`（比 UTC 慢 2 小时）被解析为会话时间`2012-03-04T07:06:07.123000Z`（即 UTC 时间）。

返回：

````
+-----------------------------+
| zoneddatetime               |
+-----------------------------+
| 2012-03-04T07:06:07.123000Z |
+-----------------------------+

````

#### 解析带默认时区的日期时间

````
RETURN zoned_datetime("2012-03-04T05:06:07.0890", "%Y-%m-%dT%H:%M:%S") AS zoneddatetime

````

上述示例使用格式`%Y-%m-%dT%H:%M:%S`格式化日期时间，时区默认为`+00:00`。值`2012-03-04T05:06:07.0890`被解析为会话时间`2012-03-04T05:06:07.089000Z`。

返回：

````
+-----------------------------+
| zoneddatetime               |
+-----------------------------+
| 2012-03-04T05:06:07.089000Z |
+-----------------------------+

````

## zoned_time()

将字符串解析为带时区的时间，并返回带会话时区的时间。

NULL 行为：默认

### 函数签名

````
zoned_time(time: str, format: str) -> ZONED TIME

````

### 示例

#### 解析带有指定时区的时间

````
RETURN zoned_time("05:06:07.123 AT -02:00", "%H:%M:%S AT %Ez") AS zonedtime

````

返回：

````
+------------------+
| zonedtime        |
+------------------+
| 07:06:07.123000Z |
+------------------+

````

## local_time()

将字符串解析为本地的时间。

NULL 行为：默认

### 函数签名

````
local_time(time: str, format: str) -> LOCAL TIME

````

### 示例

#### 解析带有小数秒的本地的时间

````
RETURN local_time("05:06:07.123", "%H:%M:%S") AS localtime

````

返回：

````
+-----------------+
| localtime       |
+-----------------+
| 05:06:07.123000 |
+-----------------+

````

## CURRENT_TIME / CURRENT_TIMESTAMP

`CURRENT_TIME`和`CURRENT_TIMESTAMP`是关键字形式的零参函数，用于返回当前会话时间。

- `CURRENT_TIME`：返回当前会话时区下的当前带时区的时间。
- `CURRENT_TIMESTAMP`：返回当前会话时区下的当前带时区的日期时间。

NULL 行为：不涉及（无入参）。

### 示例

查询当前会话时间：

````
RETURN CURRENT_TIME AS now_time, CURRENT_TIMESTAMP AS now_ts

````

先设置会话时区，再查询当前时间：

````
SESSION SET timezone = "Asia/Shanghai"
RETURN CURRENT_TIME AS sh_time, CURRENT_TIMESTAMP AS sh_ts

````

如需查看当前会话时区，请参见 [SHOW CURRENT_SESSION](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-admin/show/show-current-session/)。

## from_epoch()

将微秒级 Unix 时间戳转换为带时区的日期时间。

NULL 行为：默认

### 函数签名

````
from_epoch(unix timestamp: INT64) -> ZONEDDATETIME

````

### 示例

#### 将 Unix 时间戳转换为带时区的日期时间

````
RETURN from_epoch(1333670400000*1000) AS dt

````

返回：

````
+-----------------------------+
| dt                          |
+-----------------------------+
| 2012-04-06T00:00:00.000000Z |
+-----------------------------+

````

#### 将 Unix 时间戳转换为本地的时间

````
'''
LET zd = from_epoch(1333670400000*1000)
RETURN CAST(zd AS LOCAL DATETIME) AS ld
'''

````

返回：

````
+----------------------------+
| ld                         |
+----------------------------+
| 2012-04-06T00:00:00.000000 |
+----------------------------+

````

## to_epoch()

将带时区的日期时间转化为微秒级 Unix 时间戳。

NULL 行为：默认

### 函数签名

````
to_epoch(time: ZONEDDATETIME) -> INT64

````

### 示例

#### 将带时区的日期时间转换为 Unix 时间戳

````
RETURN to_epoch(zoned_datetime("2012-04-06T08:00:00.000+08")) AS epoch

````

返回：

````
+------------------+
| epoch            |
+------------------+
| 1333670400000000 |
+------------------+

````

#### 将本地的日期时间转换为 Unix 时间戳

````
'''
LET zd = CAST(local_time("05:06:07.123", "%H:%M:%S") AS ZONED DATETIME) 
RETURN to_epoch(zd) AS epoch
'''

````

返回：

````
+------------------+
| epoch            |
+------------------+
| 1749704767123000 |
+------------------+

````

## duration()

将指定的映射类型的值解析为时间段，并返回符合 [ISO 8601 标准](https://www.iso.org/iso-8601-date-and-time-format.html)的格式为`P[nY][nM][nD]T[nH][nM][fS]`的字符串，其中`P`是时间段的标识符，`T`是时间标识符。`P`标识符是必需的。方括号 (`[]`) 内的部分为可选项（值为零的选项可以省略），`n`可以为正整数、零或负整数，`f`可以为正、零或负的整数或小数。更多信息，请参见[指定时间段](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/temporal-type/#_10)。

### 函数签名

````
duration({years: int = 0, months: int = 0, days: int = 0, hours: int = 0, minutes: int = 0, seconds: int = 0, milliseconds: int = 0, microseconds: int = 0}) -> str

````

### 示例

#### 解析包含年份和月份的时间段

````
RETURN duration({years:1, months:2}) AS a

````

返回：

````
+-------+
| a     |
+-------+
| P1Y2M |
+-------+

````

#### 解析包含天、小时、分钟、秒、毫秒和微秒的时间段

````
RETURN duration({days:1, hours:2, minutes:3, seconds:4, milliseconds:5, microseconds:6}) AS a

````

返回：

````
+-------------------+
| a                 |
+-------------------+
| P1DT2H3M4.005006S |
+-------------------+

````

#### 解析仅包含年份的时间段

````
RETURN duration({years:1}) AS a

````

返回：

````
+-----+
| a   |
+-----+
| P1Y |
+-----+

````

#### 解析包含天和小时的时间段

````
RETURN duration({days:1, hours:2}) AS a

````

返回：

````
+--------+
| a      |
+--------+
| P1DT2H |
+--------+

````

## duration_between()

计算两个时间点之间的时间段，并以字符串形式返回时间段。该函数的两个参数的时间类型必须相同。

### 函数签名

````
duration_between(start: TEMPORAL_INSTANT, end: TEMPORAL_INSTANT) [ DAY TO SECOND | YEAR TO MONTH ] -> str

````

#### 参数

- `start`：开始时间点。
- `end`：结束时间点。
- `DAY TO SECOND`：以天、小时、分钟和秒的格式返回时间段。此为默认值。
- `YEAR TO MONTH`：以年和月的格式返回时间段。

### 示例

#### 计算两个本地日期时间之间的时间段

````
RETURN duration_between(local_datetime("2024-05-31T06:07:08.0900"), local_datetime("2024-5-1T01:02:03.0400")) AS a

````

返回：

````
+----------------+
| a              |
+----------------+
| P30DT5H5M5.05S |
+----------------+

````

#### 计算两个日期之间的时间段

````
RETURN duration_between(date("2024-5-30"), date("2024-6-30")) YEAR TO MONTH AS a

````

返回：

````
+------+
| a    |
+------+
| P-1M |
+------+

````

## 时间点和时间段之间的运算

关于支持的时间点和时间段之间的运算操作，请参见[日期和时间类型](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/data-types/temporal-type/)。

### 示例

#### 日期中添加时间段

````
RETURN date("2024-5-30") + duration({years:1000, months:10}) AS a

````

返回：

````
+------------+
| a          |
+------------+
| 3025-03-30 |
+------------+

````

#### 日期中减去时间段

````
RETURN date("2022-4-30") - duration({years:2, months:2}) AS a

````

返回：

````
+------------+
| a          |
+------------+
| 2020-02-29 |
+------------+

````

#### 本地时间中添加时间段

````
RETURN local_time("01:02:03.0400") + duration({hours:3, minutes:3, seconds:3, microseconds:30000}) AS a

````

返回：

````
+-----------------+
| a               |
+-----------------+
| 04:05:06.070000 |
+-----------------+

````

#### 本地日期时间中减去时间段（小于一天）

````
RETURN local_datetime("2024-5-31T01:05:05.0500") - duration({hours:3, minutes:3, seconds:3, microseconds:30000}) AS a

````

返回：

````
+----------------------------+
| a                          |
+----------------------------+
| 2024-05-30T22:02:02.020000 |
+----------------------------+

````

#### 本地日期时间中减去时间段（大于一天）

````
RETURN local_datetime("2021-2-28T03:03:03.0000") - duration({days:365}) AS a

````

返回：

````
+----------------------------+
| a                          |
+----------------------------+
| 2020-02-29T03:03:03.000000 |
+----------------------------+

````