日期和时间函数¶
本文描述悦数图数据库开发版中的日期和时间函数用法，适用于持久图和临时图。
本文介绍如何使用日期和时间函数来创建和操作日期和时间类型的值。这些日期和时间类型包括DATE、ZONED TIME、LOCAL TIME、ZONED DATETIME、LOCAL DATETIME和DURATION。有关日期和时间类型的更多信息，请参见日期和时间类型。
您可以在日期和时间函数中定义传入的日期和时间值格式。同时，可以使用默认格式传入值。查看日期和时间函数的默认格式，请参见 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 |
+----------------------------+
插入和查询本地的日期时间¶
以下示例数据基于示例数据集。本示例将一个本地的日期时间插入到图中，并查询插入的日期时间。
插入本地的日期时间：
'''
// 定义具有本地日期时间属性的图类型
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。
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 标准的格式为P[nY][nM][nD]T[nH][nM][fS]的字符串，其中P是时间段的标识符，T是时间标识符。P标识符是必需的。方括号 ([]) 内的部分为可选项（值为零的选项可以省略），n可以为正整数、零或负整数，f可以为正、零或负的整数或小数。更多信息，请参见指定时间段。
函数签名¶
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 |
+------+
时间点和时间段之间的运算¶
关于支持的时间点和时间段之间的运算操作，请参见日期和时间类型。
示例¶
日期中添加时间段¶
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 |
+----------------------------+