From b2a4714a691078e4a461b818009ed41996df2cd4 Mon Sep 17 00:00:00 2001 From: cooper-lzy <78672629+cooper-lzy@users.noreply.github.com> Date: Tue, 21 Dec 2021 14:18:26 +0800 Subject: [PATCH 1/7] add duration --- .../3.data-types/4.date-and-time.md | 36 ++++++++++++++----- .../3.date-and-time.md | 13 +++---- 2 files changed, 32 insertions(+), 17 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 index fab8026c024..7b2b086fc17 100644 --- 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,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 | ++------------+------------+ ``` 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 index 9e95ecc7266..62ce6c8e50a 100644 --- 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 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 | +------------+-------------+------------+-----------------+----------------------------+ ``` From c0bf31e086e224a0f65fdb02b1eca49c65038cd7 Mon Sep 17 00:00:00 2001 From: cooper-lzy <78672629+cooper-lzy@users.noreply.github.com> Date: Tue, 21 Dec 2021 14:28:38 +0800 Subject: [PATCH 2/7] Update 4.date-and-time.md --- docs-2.0/3.ngql-guide/3.data-types/4.date-and-time.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 7b2b086fc17..20385ebb1eb 100644 --- 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 @@ -4,7 +4,7 @@ This topic will describe the `DATE`, `TIME`, `DATETIME`, `TIMESTAMP`, and `DURAT ## Precautions -- 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. +- 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). !!! note From 84cb021c72f520fa1ed4ddaac6c4fd2c67d6dc3a Mon Sep 17 00:00:00 2001 From: cooper-lzy <78672629+cooper-lzy@users.noreply.github.com> Date: Tue, 21 Dec 2021 14:56:05 +0800 Subject: [PATCH 3/7] Update docs-2.0/3.ngql-guide/3.data-types/4.date-and-time.md Co-authored-by: max.zhu@vesoft.com <86282370+izhuxiaoqing@users.noreply.github.com> --- docs-2.0/3.ngql-guide/3.data-types/4.date-and-time.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 20385ebb1eb..efda339de89 100644 --- 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 @@ -8,7 +8,7 @@ This topic will describe the `DATE`, `TIME`, `DATETIME`, `TIMESTAMP`, and `DURAT !!! note - To change the time zone, modify the `timezone_name` value in the configuration files of all Nebula Graph services. + To change the timezone, 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]")`. From dec80bbed3c27ebf26698ce0c82bc9fcbe480f2c Mon Sep 17 00:00:00 2001 From: cooper-lzy <78672629+cooper-lzy@users.noreply.github.com> Date: Tue, 21 Dec 2021 14:56:11 +0800 Subject: [PATCH 4/7] Update docs-2.0/3.ngql-guide/3.data-types/4.date-and-time.md Co-authored-by: max.zhu@vesoft.com <86282370+izhuxiaoqing@users.noreply.github.com> --- docs-2.0/3.ngql-guide/3.data-types/4.date-and-time.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index efda339de89..2eb01242bcf 100644 --- 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 @@ -10,7 +10,7 @@ This topic will describe the `DATE`, `TIME`, `DATETIME`, `TIMESTAMP`, and `DURAT To change the timezone, 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()`, and `datetime()` can transform a time-type property with a specified timezone. 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. From 18d15fab3402ddfdf355d441c552ac43f252b383 Mon Sep 17 00:00:00 2001 From: cooper-lzy <78672629+cooper-lzy@users.noreply.github.com> Date: Tue, 21 Dec 2021 14:56:35 +0800 Subject: [PATCH 5/7] Update docs-2.0/3.ngql-guide/3.data-types/4.date-and-time.md Co-authored-by: max.zhu@vesoft.com <86282370+izhuxiaoqing@users.noreply.github.com> --- docs-2.0/3.ngql-guide/3.data-types/4.date-and-time.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 2eb01242bcf..b182d077afe 100644 --- 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 @@ -81,7 +81,7 @@ The `TIMESTAMP` data type is used for values that contain both date and time par ## 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`. +The `DURATION` data type is used to indicate 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: From 8cd5b9bac3415f69b96b445d1b57917663714c38 Mon Sep 17 00:00:00 2001 From: cooper-lzy <78672629+cooper-lzy@users.noreply.github.com> Date: Tue, 21 Dec 2021 14:59:31 +0800 Subject: [PATCH 6/7] Update 4.date-and-time.md --- docs-2.0/3.ngql-guide/3.data-types/4.date-and-time.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index b182d077afe..9a72404c5e9 100644 --- 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 @@ -10,7 +10,7 @@ This topic will describe the `DATE`, `TIME`, `DATETIME`, `TIMESTAMP`, and `DURAT To change the timezone, 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 timezone. For example, `datetime("2017-03-04 22:30:40.003000+08:00")` or `datetime("2017-03-04T22:30:40.003000[Asia/Shanghai]")`. +- `date()`, `time()`, and `datetime()` can convert a time-type property with a specified timezone. 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. From 38258e44acfea16139709ae3687b0596ca70e9ca Mon Sep 17 00:00:00 2001 From: "max.zhu@vesoft.com" <86282370+izhuxiaoqing@users.noreply.github.com> Date: Wed, 22 Dec 2021 11:18:59 +0800 Subject: [PATCH 7/7] Update 4.date-and-time.md --- docs-2.0/3.ngql-guide/3.data-types/4.date-and-time.md | 4 ++-- 1 file changed, 2 insertions(+), 2 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 index 9a72404c5e9..5249dd35322 100644 --- 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 @@ -4,7 +4,7 @@ This topic will describe the `DATE`, `TIME`, `DATETIME`, `TIMESTAMP`, and `DURAT ## Precautions -- 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). +- While inserting time-type property values with `DATE`, `TIME`, and `DATETIME`, Nebula Graph transforms them to a UTC time according to the timezone specified with the `timezone_name` parameter in the [configuration files](../../5.configurations-and-logs/1.configurations/1.configurations.md). !!! note @@ -57,7 +57,7 @@ The `TIMESTAMP` data type is used for values that contain both date and time par - Supported `TIMESTAMP` inserting methods: timestamp, `timestamp()` function, and `now()` function. -- `timestamp()` function accepts empty parameters to get the timestamp of the current time zone and also accepts a string type parameter. +- `timestamp()` function accepts empty parameters to get the timestamp of the current timezone and also accepts a string type parameter. ```ngql # Return the current time.