tag statements

docs-2.0/3.ngql-guide/10.tag-statements/1.create-tag.md

@@ -1,107 +1,70 @@
 # CREATE TAG
 
-`CREATE TAG` creates a tag with the given name in a graph space. You must have the `CREATE` [privilege](../../7.data-security/1.authentication/3.role-list.md) for the graph space. To create a tag in a specific graph space, you must use the graph space first.
+`CREATE TAG` creates a tag with the given name in a graph space.
 
 ## OpenCypher compatibility
 
-Tags in nGQL are similar with labels in openCypher. But they are also quite different. For example, the ways to create them are different.
+Tags in nGQL are similar to labels in openCypher. But they are also quite different. For example, the ways to create them are different.
 
-* In openCypher, labels are created together with nodes by `CREATE` statements.
-* In nGQL, tags are created separately by `CREATE TAG` statements. Tags in nGQL are more like tables in MySQL.
+* In openCypher, labels are created together with vertices in `CREATE` statements.
+* In nGQL, tags are created separately using `CREATE TAG` statements. Tags in nGQL are more like tables in MySQL.
 
-## Syntax
+## Prerequisites
 
-```ngql
-CREATE TAG [IF NOT EXISTS] <tag_name>
-    ([<create_definition>, ...])
-    [tag_options]
+Running the `CREATE TAG` statement requires some [privileges](../../7.data-security/1.authentication/3.role-list.md) for the graph space. Otherwise, Nebula Graph throws an error.
 
-<create_definition> ::=
-    <prop_name> <data_type> [NULL | NOT NULL]
+## Syntax
 
-<tag_options> ::=
-    <option> [, <option> ...]
+To create a tag in a specific graph space, you must specify the current working space with the `USE` statement.
 
-<option> ::=
-    TTL_DURATION [=] <ttl_duration>
-    | TTL_COL [=] <prop_name>
-    | DEFAULT <default_value>
+```ngql
+CREATE TAG [IF NOT EXISTS] <tag_name>
+    (
+      <prop_name> <data_type> [NULL | NOT NULL] [DEFAULT <default_value>] [COMMENT '<comment>']
+      [{, <prop_name> <data_type> [NULL | NOT NULL] [DEFAULT <default_value>] [COMMENT '<comment>']} ...] 
+    )
+    [TTL_DURATION = <ttl_duration>]
+    [TTL_COL = <prop_name>]
+    [COMMENT = '<comment>'];
 ```
 
-## Tag name
-
-- `IF NOT EXISTS`: Creating an existent tag results in an error. You can use the `IF NOT EXISTS` option to conditionally create the tag and avoid the error.
-
-  !!! note
-
-        The tag existence detection here compares only the tag names (excluding properties).
-
-- `tag_name`: The tag name must be **unique** in a graph space. Once the tag name is set, it can not be altered. The rules for permitted tag names are the same as those for graph space names. For prohibited names, see [Keywords and reserved words](../../20.appendix/keywords-and-reserved-words.md).
-
-### Property names and data types
-
-- `prop_name`
-
-    `prop_name` is the name of the property. It must be unique for each tag.
-
-- `data_type`
-
-    `data_type` shows the data type of each property. For a full description of the property data types, see [Data types](../3.data-types/1.numeric.md).
-
-- `NULL | NOT NULL`
-
-    Specifies if the property supports `NULL | NOT NULL`. The default value is `NULL`.
-
-- `DEFAULT`
-
-    Specifies a default value for a property. The default value can be a literal value or an expression supported by Nebula Graph. If no value is specified, the default value is used when inserting a new vertex.
-
-### Time-to-Live (TTL)
-
-- `TTL_DURATION`
-
-    Specifies the life cycle for the data. Data that exceeds the specified TTL expires. The expiration threshold is the `TTL_COL` value plus the `TTL_DURATION`. The default value of `TTL_DURATION` is zero. It means the data never expires.
-
-- `TTL_COL`
-
-    The data type of `prop_name` must be either `int` or `timestamp`.
-
-- single TTL definition
-
-    Only one `TTL_COL` field can be specified in a tag.
-
-For more information on TTL, see [TTL options](../8.clauses-and-options/ttl-options.md).
+|Parameter|Description|
+|:---|:---|
+|`IF NOT EXISTS`|Detects if the tag that you want to create exists. If it does not exist, a new one will be created. The tag existence detection here only compares the tag names (excluding properties).|
+|`<tag_name>`|The tag name must be **unique** in a graph space. Once the tag name is set, it can not be altered. The rules for permitted tag names are the same as those for graph space names. For prohibited names, see [Keywords and reserved words](../../3.ngql-guide/1.nGQL-overview/keywords-and-reserved-words.md).|
+|`<prop_name>`|The name of the property. It must be unique for each tag. The rules for permitted property names are the same as those for tag names.|
+|`<data_type>`|Shows the data type of each property. For a full description of the property data types, see [Data types](../3.data-types/1.numeric.md) and [Boolean](../3.data-types/2.boolean.md).|
+|`NULL \| NOT NULL`|Specifies if the property supports `NULL | NOT NULL`. The default value is `NULL`.|
+|`DEFAULT`|Specifies a default value for a property. The default value can be a literal value or an expression supported by Nebula Graph. If no value is specified, the default value is used when inserting a new vertex.|
+|`COMMENT`|The remarks of a certain property or the tag itself. The maximum length is 256 bytes. By default, there will be no comments on a tag.|
+|`TTL_DURATION`|Specifies the life cycle for the property. The property that exceeds the specified TTL expires. The expiration threshold is the `TTL_COL` value plus the `TTL_DURATION`. The default value of `TTL_DURATION` is `0`. It means the data never expires.|
+|`TTL_COL`|Specifies the property to set a timeout on. The data type of the property must be `int` or `timestamp`. A tag can only specify one field as `TTL_COL`. For more information on TTL, see [TTL options](../8.clauses-and-options/ttl-options.md).|
 
 ### Examples
 
 ```ngql
 nebula> CREATE TAG player(name string, age int);
 
-// Create a tag with no properties.
+# The following example creates a tag with no properties.
 nebula> CREATE TAG no_property(); 
 
-// Create a tag with a default value.
+# The following example creates a tag with a default value.
 nebula> CREATE TAG player_with_default(name string, age int DEFAULT 20);
-```
 
-```ngql
-// Time interval is 100s, starting from the create_time field
+# In the following example, the TTL of the create_time field is set to be 100 seconds.
 nebula> CREATE TAG woman(name string, age int, \
-   married bool, salary double, create_time timestamp) \
-   TTL_DURATION = 100, TTL_COL = "create_time";
-
-// Data expires after TTL_DURATION
-nebula> CREATE TAG icec_ream(made timestamp, temperature int) \
-   TTL_DURATION = 100, TTL_COL = "made";
+        married bool, salary double, create_time timestamp) \
+        TTL_DURATION = 100, TTL_COL = "create_time";
 ```
 
 ## Implementation of the operation
 
-Trying to insert vertices with a newly created tag may fail, because the creation of the tag is implemented asynchronously.
+Trying to use a newly created tag may fail because the creation of the tag is implemented asynchronously.
+
+Nebula Graph implements the creation of the tag in the next heartbeat cycle. To make sure the creation is successful, take one of the following approaches:
 
-Nebula Graph implements the creation in the next heartbeat cycle. To make sure the creation is successful, take one of the following approaches:
+- Find the new tag in the result of [`SHOW TAGS`](4.show-tags.md). If you cannot, wait a few seconds and try again.
 
-- Find the new tag in the result of [`SHOW TAGS`](4.show-tags.md). If you can't, wait a few seconds and try again.
 - Wait for two heartbeat cycles, i.e., 20 seconds.
 
 To change the heartbeat interval, modify the `heartbeat_interval_secs` parameter in the [configuration files](../../5.configurations-and-logs/1.configurations/1.configurations.md) for all services.

docs-2.0/3.ngql-guide/10.tag-statements/2.drop-tag.md

@@ -1,36 +1,43 @@
 # DROP TAG
 
-```ngql
-DROP TAG [IF EXISTS] <tag_name>
-```
+`DROP TAG` drops a tag with the given name in the current working graph space.
 
-`DROP TAG` drops a tag with the given name in a graph space. You must have the `DROP` [privilege](../../7.data-security/1.authentication/3.role-list.md) for the graph space. To drop a tag in a specific graph space, you must use the graph space first.
+A vertex can have one or more tags.
 
-!!! note
+- If a vertex has only one tag, the vertex **CANNOT** be accessed after you drop it. But its edges are available. The vertex will be deleted in the next compaction.
 
-    Before you drop a tag, make sure that the tag does not have any indexes. Otherwise, a conflict error (`[ERROR (-8)]: Conflict!`) is returned. To remove an index, see [DROP INDEX](../14.native-index-statements/6.drop-native-index.md).
+- If a vertex has multiple tags, the vertex is still accessible after you drop one of them. But all the properties defined by this dropped tag **CANNOT** be accessed.
 
-A vertex can have one or more tags.
+This operation only deletes the Schema data. All the files or directories in the disk will not be deleted directly until the next compaction.
 
-- When a vertex has only one tag, after you drop it, the vertex **CANNOT** be accessible. But its edges are available. The vertex is deleted in the next compaction.
-- When a vertex has multiple tags, after you drop one of them, the vertex is still accessible. But all the properties defined by this dropped tag are not accessible.
+## Prerequisites
 
-This operation only deletes the Schema data. All the files and directories in the disk are NOT deleted directly. Data is deleted in the next compaction.
+- Running the `DROP TAG` statement requires some [privileges](../../7.data-security/1.authentication/3.role-list.md) for the graph space. Otherwise, Nebula Graph throws an error.
 
-## Tag name
+- Before you drop a tag, make sure that the tag does not have any indexes. Otherwise, the conflict error (`[ERROR (-8)]: Conflict!`) will be returned when you run the `DROP TAG` statement. To drop an index, see [DROP INDEX](../14.native-index-statements/6.drop-native-index.md).
 
-- `IF EXISTS`: Dropping a non-existent tag results in an error. You can use the `IF EXISTS` option to conditionally drop the tag and avoid the error.
+## Syntax
 
-  !!! note
+```ngql
+DROP TAG [IF EXISTS] <tag_name>;
+```
 
-        The tag existence detection here compares only the tag names (excluding properties).
+- `IF NOT EXISTS`: Detects if the tag that you want to drop exists. Only when it exists will it be dropped.
 
 - `tag_name`: Specifies the tag name that you want to drop. You can drop only one tag in one statement.
 
 ## Example
 
 ```ngql
 nebula> CREATE TAG test(p1 string, p2 int);
-
 nebula> DROP TAG test;
 ```
+
+!!! Note
+
+    In nGQL, there is no such statement to drop a certain tag of a vertex with the given name.
+
+    * In openCypher, you can use the statement `REMOVE v:LABEL` to drop the tag `LABLE` of the vertex `v`.
+    * In nGQL，after `CREATE TAG` and `INSERT VERTEX`, you can add a `TAG` on the vertex. But there is no way to drop the `TAG` afterward.
+
+    We recommend you to add a field to identify the logical deletion in the schema. For example, add `removed` to the schema of each tag.

docs-2.0/3.ngql-guide/10.tag-statements/3.alter-tag.md

@@ -1,9 +1,19 @@
 # ALTER TAG
 
+`ALTER TAG` alters the structure of a tag with the given name in a graph space. You can add or drop properties, and change the data type of an existing property. You can also set a [TTL](../8.clauses-and-options/ttl-options.md) (Time-To-Live) on a property, or change its TTL duration.
+
+## Prerequisites
+
+- Running the `ALTER TAG` statement requires some [privileges](../../7.data-security/1.authentication/3.role-list.md) for the graph space. Otherwise, Nebula Graph throws an error.
+
+- Before you alter properties for a tag, make sure that the properties are not indexed. If the properties contain any indexes, the conflict error `[ERROR (-8)]: Conflict!` will occur when you `ALTER TAG`. For more information on dropping an index, see [DROP INDEX](../14.native-index-statements/6.drop-native-index.md).
+
+## Syntax
+
 ```ngql
 ALTER TAG <tag_name>
     <alter_definition> [, alter_definition] ...]
-    [ttl_definition [, ttl_definition] ... ]
+    [ttl_definition [, ttl_definition] ... ];
 
 alter_definition:
 | ADD    (prop_name data_type)
@@ -14,21 +24,11 @@ ttl_definition:
     TTL_DURATION = ttl_duration, TTL_COL = prop_name
 ```
 
-`ALTER TAG` alters the structure of a tag with the given name in a graph space. You must have the `ALTER` [privilege](../../7.data-security/1.authentication/3.role-list.md) for the graph space. To alter a tag in a specific graph space, you must use the graph space first.
-
-You can add or drop properties, change the data type of an existing property. You can also set TTL (Time-To-Live) for a property, or change the TTL duration. `TTL_COL` only supports the properties whose values are of the `INT` or the `TIMESTAMP` type.
+- `tag_name`: Specifies the tag name that you want to alter. You can alter only one tag in one statement. Before you alter a tag, make sure that the tag exists in the current working graph space. If the tag does not exist, an error will occur when you alter it.
 
-Before you alter properties for a tag, make sure that the properties are not indexed. If the properties contain any indexes, a conflict error occurs when you alter them.
+- Multiple `ADD`, `DROP`, and `CHANGE` clauses are permitted in a single `ALTER TAG` statement, separated by commas.
 
-For information about index, see [Index](../14.native-index-statements/1.create-native-index.md).
-
-Multiple `ADD`, `DROP`, and `CHANGE` clauses are permitted in a single `ALTER` statement, separated by commas.
-
-## Tag name
-
-- `tag_name`: Specifies the tag name that you want to alter. You can alter only one tag in one statement. Before you alter a tag, make sure that the tag exists in the graph space. If the tag does not exist, an error occurs when you alter it.
-
-## Example
+## Examples
 
 ```ngql
 nebula> CREATE TAG t1 (p1 string, p2 int);
@@ -38,9 +38,12 @@ nebula> ALTER TAG t1 TTL_DURATION = 2, TTL_COL = "p2";
 
 ## Implementation of the operation
 
-Nebula Graph implements the alteration asynchronously in the next heartbeat cycle. Before the process finishes, the alteration does not take effect. To make sure the alteration is successful, take the following approaches:
+Trying to use a newly altered tag may fail because the alteration of the tag is implemented asynchronously.
+
+Nebula Graph implements the alteration of the tag in the next heartbeat cycle. To make sure the alteration is successful, take one of the following approaches:
 
 - Use [`DESCRIBE TAG`](5.describe-tag.md) to confirm that the tag information is updated. If it is not, wait a few seconds and try again.
+
 - Wait for two heartbeat cycles, i.e., 20 seconds.
 
 To change the heartbeat interval, modify the `heartbeat_interval_secs` parameter in the [configuration files](../../5.configurations-and-logs/1.configurations/1.configurations.md) for all services.

docs-2.0/3.ngql-guide/10.tag-statements/4.show-tags.md

@@ -1,11 +1,15 @@
 # SHOW TAGS
 
+The `SHOW TAGS` statement shows the name of all tags in the current graph space.
+
+You do not need any privileges for the graph space to run the `SHOW TAGS` statement. But the returned results are different based on [role privileges](../../7.data-security/1.authentication/3.role-list.md).
+
+## Syntax
+
 ```ngql
-SHOW TAGS
+SHOW TAGS;
 ```
 
-`SHOW TAGS` shows all tags in the current graph space. You do not need any privileges for the graph space to run this statement. But the returned results are different based on [role privileges](../../7.data-security/1.authentication/3.role-list.md). To show tags in a specific graph space, you must use the graph space first.
-
 ## Examples
 
 ```ngql
@@ -17,5 +21,4 @@ nebula> SHOW TAGS;
 +----------+
 | "team"   |
 +----------+
-Got 2 rows (time spent 1461/2114 us)
 ```

docs-2.0/3.ngql-guide/10.tag-statements/5.describe-tag.md

@@ -1,25 +1,28 @@
 # DESCRIBE TAG
 
+`DESCRIBE TAG` returns the information about a tag with the given name in a graph space, such as field names, data type, and so on.
+
+## Prerequisite
+
+Running the `DESCRIBE TAG` statement requires some [privileges](../../7.data-security/1.authentication/3.role-list.md) for the graph space. Otherwise, Nebula Graph throws an error.
+
+## Syntax
+
 ```ngql
-DESC[RIBE] TAG <tag_name>
+DESC[RIBE] TAG <tag_name>;
 ```
 
-`DESCRIBE TAG` returns information about a tag with the given name in a graph space. You must have the read Schema [privilege](../../7.data-security/1.authentication/3.role-list.md) for the graph space. To describe a tag in a specific graph space, you must use the graph space first. You can use `DESC` instead of `DESCRIBE` for short.
-
-`DESCRIBE TAG` is different from `SHOW TAGS`. For details about `SHOW TAGS`, see [SHOW TAGS](4.show-tags.md).
+You can use `DESC` instead of `DESCRIBE` for short.
 
 ## Example
 
-Get information about a tag named `player`.
-
 ```ngql
 nebula> DESCRIBE TAG player;
-
-+--------+----------+-------+-----------+
-| Field  | Type     | Null  | Default   |
-+--------+----------+-------+-----------+
-| "name" | "string" | "YES" | __EMPTY__ |
-+--------+----------+-------+-----------+
-| "age"  | "int64"  | "YES" | __EMPTY__ |
-+--------+----------+-------+-----------+
++--------+----------+-------+---------+---------+
+| Field  | Type     | Null  | Default | Comment |
++--------+----------+-------+---------+---------+
+| "name" | "string" | "YES" |         |         |
++--------+----------+-------+---------+---------+
+| "age"  | "int64"  | "YES" |         |         |
++--------+----------+-------+---------+---------+
 ```