add duration

docs-2.0/3.ngql-guide/3.data-types/4.date-and-time.md

@@ -1,26 +1,28 @@
 # Date and time types
 
-This topic will describe the `DATE`, `TIME`, `DATETIME`, and `TIMESTAMP` types.
+This topic will describe the `DATE`, `TIME`, `DATETIME`, `TIMESTAMP`, and `DURATION` types.
 
-While inserting time-type property values, except for `TIMESTAMP`, Nebula Graph transforms them to a UTC time according to the time zone specified with the `timezone_name` parameter in the [configuration files](../../5.configurations-and-logs/1.configurations/1.configurations.md). The time-type values returned by nGQL queries are all UTC time.
+## Precautions
 
-!!! note
+- While inserting time-type property values with `DATE`, `TIME`, and `DATETIME`, Nebula Graph transforms them to a UTC time according to the time zone specified with the `timezone_name` parameter in the [configuration files](../../5.configurations-and-logs/1.configurations/1.configurations.md). The time-type values returned by nGQL queries are all UTC time.
 
-    To change the time zone, modify the `timezone_name` value in the configuration files of all Nebula Graph services.
+  !!! note
+
+        To change the time zone, modify the `timezone_name` value in the configuration files of all Nebula Graph services.
+
+- `date()`, `time()`, and `datetime()` can transform a time-type property with a specified time zone. For example, `datetime("2017-03-04 22:30:40.003000+08:00")` or `datetime("2017-03-04T22:30:40.003000[Asia/Shanghai]")`.
 
 - `date()`, `time()`, `datetime()`, and `timestamp()` all accept empty parameters to return the current date, time, and datetime.
 
 - `date()`, `time()`, and `datetime()` all accept the property name to return a specific property value of itself. For example, `date().month` returns the current month, while `time("02:59:40").minute` returns the minutes of the importing time.
 
-- `date()`, `time()`, and `datetime()` can transform a time-type property with a specified time zone. For example, `datetime("2017-03-04 22:30:40.003000+08:00")` or `datetime("2017-03-04T22:30:40.003000[Asia/Shanghai]")`.
-
 ## OpenCypher Compatibility
 
 In nGQL:
 
 - Year, month, day, hour, minute, second, millisecond, and microsecond are supported, while the nanosecond is not supported.
 
-- `localdatetime()` and `duration()` are not supported.
+- `localdatetime()` is not supported.
 
 - Most string time formats are not supported. The exceptions are `YYYY-MM-DDThh:mm:ss` and `YYYY-MM-DD hh:mm:ss`.
 
@@ -77,6 +79,16 @@ The `TIMESTAMP` data type is used for values that contain both date and time par
 
 - The underlying storage data type is **int64**.
 
+## DURATION
+
+The `DURATION` data type is used for indicates a period of time. Map data that are freely combined by `years`, `months`, `days`, `hours`, `minutes`, and `seconds` indicates the `DURATION`.
+
+`DURATION` has the following features:
+
+- Creating indexes for `DURATION` is not supported.
+
+- `DURATION` can be used to calculate the specified time.
+
 ## Examples
 
 1. Create a tag named `date1` with three properties: `DATE`, `TIME`, and `DATETIME`.
@@ -130,7 +142,7 @@ The `TIMESTAMP` data type is used for values that contain both date and time par
     nebula> INSERT VERTEX school(name, found_time) VALUES "dut":("dut", timestamp());
     ```
 
-You can also use `WITH` statement to set a specific date and time. For example:
+You can also use `WITH` statement to set a specific date and time, or to perform calculations. For example:
 
 ```ngql
 nebula> WITH time({hour: 12, minute: 31, second: 14, millisecond:111, microsecond: 222}) AS d RETURN d;
@@ -146,4 +158,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 |
++------------+------------+
 ```

docs-2.0/3.ngql-guide/6.functions-and-expressions/3.date-and-time.md

@@ -9,22 +9,17 @@ Nebula Graph supports the following built-in date and time functions:
 | date date()           | Returns the current UTC date based on the current system.          |
 | time time()           | Returns the current UTC time based on the current system.          |
 | datetime datetime()   | Returns the current UTC date and time based on the current system. |
+| map duration()        | Returns the period of time. It can be used to calculate the specified time. |
 
-The `date()`, `time()`, and `datetime()` functions accept three kind of parameters, namely empty, string, and map. The `timestamp()` function accepts two kind of parameters, namely empty and string.
-
-## OpenCypher compatibility
-
-* Time in openCypher is measured in milliseconds.
-
-* Time in nGQL is measured in seconds. The milliseconds are displayed in `000`.
+For more information, see [Date and time types](../3.data-types/4.date-and-time.md).
 
 ## Examples
 
 ```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 |
 +------------+-------------+------------+-----------------+----------------------------+
 ```