add duration (#1335)

* add duration * Update 4.date-and-time.md * Update docs-2.0/3.ngql-guide/3.data-types/4.date-and-time.md Co-authored-by: randomJoe211 <[email protected]> Co-authored-by: randomJoe211 <[email protected]>
vesoft-inc · Dec 22, 2021 · 7894294 · 7894294
1 parent edd47a1
commit 7894294
Show file tree

Hide file tree

Showing 2 changed files with 33 additions and 18 deletions.
diff --git a/docs-2.0/3.ngql-guide/3.data-types/4.date-and-time.md b/docs-2.0/3.ngql-guide/3.data-types/4.date-and-time.md
@@ -1,24 +1,26 @@
 # 日期和时间类型
 
-本文介绍日期和时间的类型，包括`DATE`、`TIME`、`DATETIME`和`TIMESTAMP`。
+本文介绍日期和时间的类型，包括`DATE`、`TIME`、`DATETIME`、`TIMESTAMP`和`DURATION`。
 
-在插入时间类型的属性值时，Nebula Graph 会根据[配置文件](../../5.configurations-and-logs/1.configurations/1.configurations.md)中`timezone_name`参数指定的时区，将该时间值（`TIMESTAMP`类型例外）转换成相应的世界协调时间（UTC）时间。在查询中返回的时间类型值为 UTC 时间。
+## 注意事项
 
-!!! Note
+- 在插入时间类型的属性值时，Nebula Graph 会根据[配置文件](../../5.configurations-and-logs/1.configurations/1.configurations.md)中`timezone_name`参数指定的时区，将该`DATE`、`TIME`、`DATETIME`转换成相应的世界协调时间（UTC）时间。
 
-    如需修改当前时区，请同时修改所有服务的配置文件中的`timezone_name`参数。
+  !!! Note
 
-- 函数`date()`、`time()`、`datetime()`和`timestamp()`可以用空值获取当前的日期或时间。
-
-- 函数`date()`、`time()`和`datetime()`可以用属性名称获取自身的某一个具体属性值，例如`date().month`获取当前月份、`time("02:59:40").minute`获取传入时间的分钟数。
+        如需修改当前时区，请同时修改所有服务的配置文件中的`timezone_name`参数。
 
 - 函数`date()`、`time()`和`datetime()`可以指定时区进行转换，例如`datetime("2017-03-04 22:30:40.003000+08:00")`或`datetime("2017-03-04T22:30:40.003000[Asia/Shanghai]")`。
 
+- 函数`date()`、`time()`、`datetime()`和`timestamp()`可以用空值获取当前的日期或时间。
+
+- 函数`date()`、`time()`、`datetime()`和`duration()`可以用属性名称获取自身的某一个具体属性值，例如`date().month`获取当前月份、`time("02:59:40").minute`获取传入时间的分钟数。
+
 ## openCypher 兼容性
 
 - 支持年、月、日、时、分、秒、毫秒、微秒，不支持纳秒。
 
-- 不支持函数`localdatetime()`和`duration()`。
+- 不支持函数`localdatetime()`。
 
 - 不支持大部分字符串时间格式，支持`YYYY-MM-DDThh:mm:ss`和`YYYY-MM-DD hh:mm:ss`。
 
@@ -76,6 +78,16 @@
 
 - 底层存储的数据格式为** 64 位 int**。
 
+## DURATION
+
+`DURATION`是一段连续的时间，由`years`、`months`、`days`、`hours`、`minutes`、`seconds`六个Key自由组合成的Map类型数据表示。例如`duration({years: 12, months: 5, days: 14, hours: 16, minutes: 12, seconds: 70})`。
+
+`DURATION`还有以下特点：
+
+- 不支持为`DURATION`类型数据创建索引。
+
+- 可以用于对指定时间进行计算。
+
 ## 示例
 
 1. 创建 Tag，名称为`date1`，包含`DATE`、`TIME`和`DATETIME`三种类型。
@@ -129,7 +141,7 @@
     nebula> INSERT VERTEX school(name, found_time) VALUES "dut":("dut", timestamp());
     ```
 
-还可以使用`WITH`语句设置具体日期和时间，例如：
+还可以使用`WITH`语句设置具体日期时间或进行计算，例如：
 
 ```ngql
 nebula> WITH time({hour: 12, minute: 31, second: 14, millisecond:111, microsecond: 222}) AS d RETURN d;
@@ -145,4 +157,12 @@ nebula> WITH date({year: 1984, month: 10, day: 11}) AS x RETURN x + 1;
 +------------+
 | 1984-10-12 |
 +------------+
+
+nebula> WITH date('1984-10-11') as x, duration({years: 12, days: 14, hours: 99, minutes: 12}) as d \
+        RETURN x + d AS sum, x - d AS diff;
++------------+------------+
+| sum        | diff       |
++------------+------------+
+| 1996-10-29 | 1972-09-23 |
++------------+------------+
 ```
diff --git a/docs-2.0/3.ngql-guide/6.functions-and-expressions/3.date-and-time.md b/docs-2.0/3.ngql-guide/6.functions-and-expressions/3.date-and-time.md
@@ -9,22 +9,17 @@ Nebula Graph 支持以下内置日期时间函数。
 |date date() | 根据当前系统返回当前日期（UTC 时间）。 |
 |time time() | 根据当前系统返回当前时间（UTC 时间）。 |
 |datetime datetime() | 根据当前系统返回当前日期和时间（UTC 时间）。 |
+|map duration()  | 持续时间。可以用于对指定时间进行计算。   |
 
-`date()`、`time()`和`datetime()`函数除了传入空值获取当前时间或日期，还接受 string 和 map 类型的参数。`timestamp()`函数除了传入空值获取当前时区的时间戳，还接受 string 类型的参数。
-
-## openCypher 兼容性
-
-- 在 openCypher 中，时间精确到毫秒。
-
-- 在 nGQL 中，时间精确到毫秒。微秒数显示为`000`。
+详细信息参见[日期和时间类型](../3.data-types/4.date-and-time.md)。
 
 ## 示例
 
 ```ngql
-> RETURN now(), timestamp(), date(), time(), datetime();
+nebula>  RETURN now(), timestamp(), date(), time(), datetime();
 +------------+-------------+------------+-----------------+----------------------------+
 | now()      | timestamp() | date()     | time()          | datetime()                 |
 +------------+-------------+------------+-----------------+----------------------------+
-| 1625470028 | 1625470028  | 2021-07-05 | 07:27:07.944000 | 2021-07-05T07:27:07.944000 |
+| 1640057560 | 1640057560  | 2021-12-21 | 03:32:40.351000 | 2021-12-21T03:32:40.351000 |
 +------------+-------------+------------+-----------------+----------------------------+
 ```