data types

docs-2.0/3.ngql-guide/3.data-types/1.numeric.md

@@ -2,15 +2,12 @@
 
 ## Integer
 
-An integer is declared with keyword `int` , which is 64-bit *signed*. The supported range is [-9223372036854775808, 9223372036854775807]. Integer constants support multiple formats:
+An integer is declared with the keyword `int`, which is 64-bit *signed*. The supported range is [-9223372036854775808, 9223372036854775807]. Integer constants support multiple formats:
 
-1. Decimal, for example `123456`.
-2. Hexadecimal, for example `0xdeadbeaf`.
-3. Octal, for example `01234567`.
+1. Decimal, such as `123456`.
+2. Hexadecimal, such as `0x1e240`.
+3. Octal, such as `0361100`.
 
 ## Double-precision floating-point
 
-double-precision floating-point values is used for storing double precision floating point values. E.g., 1.2, -3.0000001.
-The keyword used for double floating point data type is `double`.
-
-Scientific notation is also supported. For example, `1e2, 1.1e2, .3e4, 1.e4, -1234E-10`.
+Double-precision floating-point values are declared with the keyword `double`, such as `1.2` and `-3.0000001`. Scientific notation is also supported, such as `1e2`, `1.1e2`, `.3e4`, `1.e4` and `-1234E-10`.

docs-2.0/3.ngql-guide/3.data-types/3.string.md

@@ -1,26 +1,37 @@
 # String
 
-The string type is used to store a sequence of characters (text). The literal constant is a sequence of characters of any length surrounded by double or single quotes. For example `"Shaquille O'Neal"` or `'"This is a double-quoted literal string"'`. Line breaks are not allowed in a string. Embedded escape sequences are supported within strings, for example:
+The string type is declared with the keywords of `string` or `fixed_string(<length>)`. A string type is used to store a sequence of characters (text). The literal constant is a sequence of characters of any length surrounded by double or single quotes. For example `"Shaquille O'Neal"` or `'This is a double-quoted literal string'`.
 
-- `"\n\t\r\b\f"`
-- `"\110ello world"`
+## String types
 
-Nebula Graph supports two kind of strings: fixed length string and variable length string. For example:
+Nebula Graph supports two string types as follows:
 
-```ngql
-nebula> CREATE TAG t1 (p1 FIXED_STRING(10)); -- Fixed length string type
+- Fixed-length string type
 
-nebula> CREATE TAG t2 (p2 string); -- Variable length string type
-```
+    ```ngql
+    nebula> CREATE TAG t1 (p1 fixed_string(10)); 
+    ```
 
-## OpenCypher Compatibility
+- Variable-length string type
+
+    ```ngql
+    nebula> CREATE TAG t2 (p2 string); 
+    ```
+
+## Escape Characters
 
-Here is a tiny difference between openCypher and Cypher, as well as nGQL.
+Line breaks are not allowed in a string. Escape characters are supported within strings, for example:
+
+- `"\n\t\r\b\f"`
+
+- `"\110ello world"`
+
+## OpenCypher Compatibility
 
-The following is what openCypher requires. Single-quotes can't be converted to double-quotes.
+There is some tiny differences between openCypher and Cypher, as well as nGQL. The following is what openCypher requires. Single quotes cannot be converted to double quotes.
 
 ```ngql
- #File: Literals.feature
+# File: Literals.feature
 Feature: Literals
 
 Background:
@@ -36,7 +47,7 @@ Background:
     And no side effects
 ```
 
-While Cypher accepts both single-quotes and double quotes as the return results. nGQL follows the Cypher way.
+While Cypher accepts both single quotes and double quotes as the return results. nGQL follows the Cypher way.
 
 ```ngql
 nebula > YIELD '' AS quote1, "" AS quote2, "'" AS quote3, '"' AS quote4

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

@@ -1,80 +1,112 @@
 # Date and time types
 
-This document describes the `DATE`, `TIME`, `DATETIME`, and `TIMESTAMP` types. Nebula Graph converts the `DATE`, `TIME`, `DATETIME`, and `TIMESTAMP` values from the current time zone to **UTC** for storage. Nebula Graph converts back from UTC to the current time zone for retrieval.
+This topic will describe the `DATE`, `TIME`, `DATETIME`, and `TIMESTAMP` types.
 
-While inserting time-type property values, except for timestamps, 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, 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.
 
 !!! note
 
     To change the time zone, modify the `timezone_name` value in the configuration files of all Nebula Graph services.
 
-Combined with `RETURN`, functions `date()`, `time()`, `datetime()` all accept empty parameters to return the current date, time and datetime.
+Combined with `RETURN` clauses, `date()`, `time()`, and `datetime()` all accept empty parameters to return the current date, time and datetime.
 
 ## OpenCypher Compatibility
 
 In nGQL:
 
-- Year, month, day, hour, minute, and second are supported. The millisecond field is displayed in `000`.
+- Year, month, day, hour, minute, and second are supported, while the millisecond is not supported.
 
-- `localdatetime()`, `duration()` are not supported.
+- `localdatetime()` and `duration()` are not supported.
 
-- Most string time formats are not supported. The only exception is `2017-03-04T22:30:40`.
+- Most string time formats are not supported. The only exception is `YYYY-MM-DDThh:mm:ss`.
 
 ## DATE
 
 The `DATE` type is used for values with a date part but no time part. Nebula Graph retrieves and displays `DATE` values in the `YYYY-MM-DD` format. The supported range is `-32768-01-01` to `32767-12-31`.
 
 ## TIME
 
-The `TIME` type is used for values with a time part but no date part. Nebula Graph retrieves and displays `TIME` values in `hh:mm:ss:usus` format. The supported range is `0:0:0:0` to `23:59:59:999999`.
+The `TIME` type is used for values with a time part but no date part. Nebula Graph retrieves and displays `TIME` values in `hh:mm:ss.msmsmsususus` format. The supported range is `00:00:00.000000` to `23:59:59.999999`.
 
 ## DATETIME
 
-The `DATETIME` type is used for values that contain both date and time parts. Nebula Graph retrieves and displays `DATETIME` values in `YYYY-MM-DD hh:mm:ss:ususus` format. The supported range is `-32768-01-01 00:00:00:00` to `32767-12-31 23:59:59:999999`.
+The `DATETIME` type is used for values that contain both date and time parts. Nebula Graph retrieves and displays `DATETIME` values in `YYYY-MM-DDThh:mm:ss.msmsmsususus` format. The supported range is `-32768-01-01T00:00:00.000000` to `32767-12-31T23:59:59.999999`.
 
 ## TIMESTAMP
 
-The `TIMESTAMP` data type is used for values that contain both date and time parts.
+The `TIMESTAMP` data type is used for values that contain both date and time parts. It has a range of `1970-01-01T00:00:01` UTC to `2262-04-11T23:47:16` UTC.
 
-- `TIMESTAMP` has a range of `1970-01-01 00:00:01` UTC to `2262-04-11 23:47:16` UTC.
-- Timestamp is measured in units of seconds.
-- Supported `TIMESTAMP` inserting methods:
-  - Call the `now()` function.
-  - Input `TIMESTAMP` by using a string. For example: `2019-10-01 10:00:00`.
-  - Input `TIMESTAMP` directly, namely the number of seconds from `1970-01-01 00:00:00`.
-- The underlying storage data type is: **int64**.
+`TIMESTAMP` has the following features:
+
+- Stored and displayed in the form of a timestamp, such as `1615974839`, which means `2021-03-17T17:53:59`.
+
+- Supported `TIMESTAMP` querying methods: timestamp and `timestamp()` function.
+
+- 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.
+
+   ```ngql
+   # Return the current time.
+   nebula> return timestamp();
+   +-------------+
+   | timestamp() |
+   +-------------+
+   | 1625469277  |
+   +-------------+
+
+   # Return the specified time.
+   nebula> return timestamp("2021-07-05T06:18:43.984000");
+   +-----------------------------------------+
+   | timestamp("2021-07-05T06:18:43.984000") |
+   +-----------------------------------------+
+   | 1625465923                              |
+   +-----------------------------------------+
+   ```
+
+- The underlying storage data type is **int64**.
 
 ## Examples
 
-Create a tag named date.
+1. Create a tag named `date1` with three properties: `DATE`, `TIME`, and `DATETIME`.
 
-```ngql
-nebula> CREATE TAG date(p1 date, p2 time, p3 datetime);
-```
+    ```ngql
+    nebula> CREATE TAG date1(p1 date, p2 time, p3 datetime);
+    ```
 
-Insert a vertex named Date1.
+2. Insert a vertex named `test1`.
 
-```ngql
-nebula> INSERT VERTEX date(p1, p2, p3) VALUES "Date1":(date("2017-03-04"), time("23:01:00"), datetime("2017-03-04T22:30:40"));
-```
+    ```ngql
+    nebula> INSERT VERTEX date1(p1, p2, p3) VALUES "test1":(date("2021-03-17"), time("17:53:59"), datetime("2021-03-17T17:53:59"));
+    ```
 
-Create a tag named school.
+3. Create a tag named `school` with the property of `TIMESTAMP`.
 
-```ngql
-nebula> CREATE TAG school(name string , found_time timestamp);
-```
+    ```ngql
+    nebula> CREATE TAG school(name string , found_time timestamp);
+    ```
 
-Insert a vertex named "stanford" with the foundation date `"1885-10-01T08:00:00"`.
+4. Insert a vertex named `DUT` with a found-time timestamp of `"1988-03-01T08:00:00"`.
 
-```ngql
-nebula> INSERT VERTEX school(name, found_time) VALUES "Stanford":("Stanford", timestamp("1885-10-01T08:00:00"));
-```
+    ```ngql
+    # Insert as a timestamp. The corresponding timestamp of 1988-03-01T08:00:00 is 573177600, or 573206400 UTC.
+    nebula> INSERT VERTEX school(name, found_time) VALUES "DUT":("DUT", 573206400);
 
-Insert a vertex named "dut" with the foundation date now.
+    # Insert in the form of date and time.
+    nebula> INSERT VERTEX school(name, found_time) VALUES "DUT":("DUT", timestamp("1988-03-01T08:00:00"));
+    ```
 
-```ngql
-nebula> INSERT VERTEX school(name, found_time) VALUES "dut":("dut", now());
-```
+5. Insert a vertex named `dut` and store time with `now()` or `timestamp()` functions.
+
+    ```ngql
+    # Use now() function to store time
+    nebula> INSERT VERTEX school(name, found_time) VALUES "dut":("dut", now());
+
+    # Use timestamp() function to store time
+    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:
 
 ```ngql
 nebula> WITH time({hour: 12, minute: 31, second: 14}) AS d RETURN d;
@@ -90,12 +122,4 @@ nebula> WITH date({year: 1984, month: 10, day: 11}) AS x RETURN x + 1;
 +------------+
 | 1984-10-12 |
 +------------+
-
-nebula> WITH datetime({year: 1984, month: 10, day: 11, hour: 12, minute: 31, second: 14}) AS d \
-        RETURN toString(d) AS ts, datetime(toString(d)) == d AS b
-+-------------------------+------+
-| ts                      | b    |
-+-------------------------+------+
-| "1984-10-11T12:31:14.0" | true |
-+-------------------------+------+
 ```

docs-2.0/3.ngql-guide/3.data-types/5.null.md

@@ -1,16 +1,12 @@
 # NULL
 
-You can set the properties for vertices or edges to `NULL`. Also, you can set `NOT NULL` constraint to make sure that the property values are `NOT NULL`.
-
-If not specified, the property is set to `NULL` by default.
+You can set the properties for vertices or edges to `NULL`. Also, you can set the `NOT NULL` constraint to make sure that the property values are `NOT NULL`. If not specified, the property is set to `NULL` by default.
 
 ## Logical operations with NULL
 
-The logical operations with NULL is the same as openCypher.
-
-Here is the truth table for AND, OR, XOR, and NOT.
+Here is the truth table for `AND`, `OR`, `XOR`, and `NOT`.
 
-| a | b | a AND b | a OR b | a XOR b | NOT a |
+| a | b | a AND b | a OR b | a XOR | NOT a |
 | - | - | - | - | - | - |
 | false | false | false | false | false | true |
 | false|  null|  false | null | null | true |
@@ -24,28 +20,27 @@ Here is the truth table for AND, OR, XOR, and NOT.
 
 ## OpenCypher compatibility
 
-The comparisons and operations about NULL are different from openCypher.
-
-The behavior may change later.
+The comparisons and operations about NULL are different from openCypher. There may be changes later.
 
 ### Comparisons with NULL
 
-The comparison operations with NULL is incompatible with openCypher.
+The comparison operations with NULL are incompatible with openCypher.
 
-### Operations and expression with NULL
+### Operations and RETURN with NULL
 
-The NULL operations and RETURN with NULL is incompatible with openCypher.
+The NULL operations and RETURN with NULL are incompatible with openCypher.
 
 ## Examples
 
-Create a tag named player. Specify the property name with `NOT NULL`. Ignore the property age constraint.
+### Use NOT NULL
+
+Create a tag named `player`. Specify the property `name` as `NOT NULL`.
 
 ```ngql
 nebula> CREATE TAG player(name string NOT NULL, age int);
-Execution succeeded (time spent 5001/5980 us)
 ```
 
-The property `name` is `NOT NULL`. The property `age` is `NULL` by default.
+Use `SHOW` to create tag statements. The property `name` is `NOT NULL`. The property `age` is `NULL` by default.
 
 ```ngql
 nebula> SHOW CREATE TAG player;
@@ -59,7 +54,33 @@ nebula> SHOW CREATE TAG player;
 +-----------+-----------------------------------+
 ```
 
+Insert the vertex `Kobe`. The property `age` can be `NULL`.
+
 ```ngql
 nebula> INSERT VERTEX player(name, age) VALUES "Kobe":("Kobe",null);
-Execution succeeded (time spent 6367/7357 us)
+```
+
+### Use NOT NULL and set the default
+
+Create a tag named `player`. Specify the property `age` as `NOT NULL`. The default value is `18`.
+
+```ngql
+nebula> CREATE TAG player(name string, age int NOT NULL DEFAULT 18);
+```
+
+Insert the vertex `Kobe`. Specify the property `name` only.
+
+```ngql
+nebula> INSERT VERTEX player(name) VALUES "Kobe":("Kobe");
+```
+
+Query the vertex `Kobe`. The property `age` is `18` by default.
+
+```ngql
+nebula> FETCH PROP ON player "Kobe"
++-----------------------------------------+
+| vertices_                               |
++-----------------------------------------+
+| ("Kobe" :player{age: 18, name: "Kobe"}) |
++-----------------------------------------+
 ```