You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iotdb.apache.org by qi...@apache.org on 2022/10/31 05:15:35 UTC
[iotdb] branch master updated: Update download doc (#7801)
This is an automated email from the ASF dual-hosted git repository.
qiaojialin pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/iotdb.git
The following commit(s) were added to refs/heads/master by this push:
new a78cd55c89 Update download doc (#7801)
a78cd55c89 is described below
commit a78cd55c893409b77846ed64bb4dd0e97bace3f3
Author: Liao Lanyu <14...@qq.com>
AuthorDate: Mon Oct 31 13:15:29 2022 +0800
Update download doc (#7801)
---
docs/Download/README.md | 148 +++++++++++++++++--
docs/UserGuide/Reference/Syntax-Conventions.md | 169 +++------------------
docs/zh/Download/README.md | 143 ++++++++++++++++--
docs/zh/UserGuide/Reference/Syntax-Conventions.md | 172 +++-------------------
4 files changed, 305 insertions(+), 327 deletions(-)
diff --git a/docs/Download/README.md b/docs/Download/README.md
index 5061fb31e6..f5db09fa90 100644
--- a/docs/Download/README.md
+++ b/docs/Download/README.md
@@ -100,22 +100,143 @@ Legacy version are available here: [https://archive.apache.org/dist/iotdb/](http
> sudo sysctl -w kern.ipc.somaxconn=65535
```
-## About 0.14.0-preview1
+## About Version 1.0
-- 0.14.0-preview1 is a preview release for the new IoTDB cluster, which you could download and have a try.
- We DO NOT recommend using preview release on-line, and DO NOT upgrade 0.13 to a preview release.
- - The UserGuide of 0.14.0-preview is still in the **latest**.
+**After we release version 1.0, how to upgrade from v.13.x to v1.0.x?**
+
+ - **Version 1.0 has changed the SQL syntax conventions (please refer to the syntax conventions section of the user manual)**.
+ - In order to ensure the stability of UDF-related APIs, in version 1.0, UDF-related APIs are seperated into an independent module and no longer depend on the tsfile package. The implemented UDFs need to rewrite the code, replace `TsDataType` with `Type`, and replace `org .apache.iotdb.tsfile.utils.Binary` with `org.apache.iotdb.udf.api.type.Binary`, then redo the packaging and loading process.
-**<font color=red>NOTE: Do not use the stop-confignode.bat/sh script, which has a bug that may kill other process</font>**:
-
+### Detailed description of Syntax Conventions in version 1.0 that are different from older versions
+
+In previous versions of syntax conventions, we introduced some ambiguity to maintain compatibility. To avoid ambiguity, we have designed new syntax conventions, and this chapter will explain the issues with the old syntax conventions and why we made the change.
+
+#### Issues related to identifier
+
+In version 0.13 and earlier, identifiers (including path node names) that are not quoted with backquotes are allowed to be pure numbers(Pure numeric path node names need to be enclosed in backquotes in the `SELECT` clause), and are allowed to contain some special characters. **In version 1.0, identifiers that are not quoted with backquotes are not allowed to be pure numbers and only allowed to contain letters, Chinese characters, and underscores.**
+
+#### Issues related to node name
+
+In previous versions of syntax conventions, when do you need to add quotation marks to the node name, and the rules for using single and double quotation marks or backquotes are complicated. We have unified usage of quotation marks in the new syntax conventions. For details, please refer to the relevant chapters of this document.
+
+##### When to use single and double quotes and backquotes
+
+In previous versions of syntax conventions, path node names were defined as identifiers, but when the path separator . was required in the path node name, single or double quotes were required. This goes against the rule that identifiers are quoted using backquotes.
+
+```SQL
+# In the previous syntax convention, if you need to create a time series root.sg.`www.baidu.com`, you need to use the following statement:
+create root.sg.'www.baidu.com' with datatype=BOOLEAN, encoding=PLAIN
+
+# The time series created by this statement is actually root.sg.'www.baidu.com', that is, the quotation marks are stored together. The three nodes of the time series are {"root","sg","'www.baidu.com'"}.
+
+# In the query statement, if you want to query the data of the time series, the query statement is as follows:
+select 'www.baidu.com' from root.sg;
+```
+
+**In the 1.0 syntax conventions, special node names are uniformly quoted using backquotes:**
+
+```SQL
+# In the new syntax convention, if you need to create a time series root.sg.`www.baidu.com`, the syntax is as follows:
+create root.sg.`www.baidu.com` with 'datatype' = 'BOOLEAN', 'encoding' = 'PLAIN'
+
+#To query the time series, you can use the following statement:
+select `www.baidu.com` from root.sg;
+```
+
+##### The issues of using quotation marks inside node names
+
+In previous versions of syntax conventions, when single quotes ' and double quotes " are used in path node names, they need to be escaped with a backslash \, and the backslashes will be stored as part of the path node name. Other identifiers do not have this restriction, causing inconsistency.
+
+```SQL
+# Create time series root.sg.\"a
+create timeseries root.sg.`\"a` with datatype=TEXT,encoding=PLAIN;
+
+# Query time series root.sg.\"a
+select `\"a` from root.sg;
++-----------------------------+-----------+
+| Time|root.sg.\"a|
++-----------------------------+-----------+
+|1970-01-01T08:00:00.004+08:00| test|
++-----------------------------+-----------+
+```
+
+**In the 1.0 syntax convention, special path node names are uniformly referenced with backquotes.** When single and double quotes are used in path node names, there is no need to add backslashes to escape, and backquotes need to be double-written. For details, please refer to the relevant chapters of the new syntax conventions.
+
+#### Issues related to session API
+
+##### Session API syntax restrictions
+
+In version 0.13, the restrictions on using path nodes in non-SQL interfaces are as follows:
+
+- The node names in path or path prefix as parameter:
+ - The node names which should be escaped by backticks (`) in the SQL statement, and escaping is not required here.
+ - The node names enclosed in single or double quotes still need to be enclosed in single or double quotes and must be escaped for JAVA strings.
+ - For the `checkTimeseriesExists` interface, since the IoTDB-SQL interface is called internally, the time-series pathname must be consistent with the SQL syntax conventions and be escaped for JAVA strings.
+
+**In version 1.0, restrictions on using path nodes in non-SQL interfaces were enhanced:**
+
+- **The node names in path or path prefix as parameter: The node names which should be escaped by backticks (`) in the SQL statement, escaping is required here.**
+- **Code example for syntax convention could be found at:** `example/session/src/main/java/org/apache/iotdb/SyntaxConventionRelatedExample.java`
+
+##### Inconsistent handling of string escaping between SQL and Session interfaces
+
+**In previous releases, there was an inconsistency between the SQL and Session interfaces when using strings.** For example, when using SQL to insert Text type data, the string will be unescaped, but not when using the Session interface, which is inconsistent. **In the new syntax convention, we do not unescape the strings. What you store is what will be obtained when querying (for the rules of using single and double quotation marks inside strings, please refer to this document for strin [...]
+
+The following are examples of inconsistencies in the old syntax conventions:
+
+Use Session's insertRecord method to insert data into the time series root.sg.a
+
+```Java
+// session insert
+String deviceId = "root.sg";
+List<String> measurements = new ArrayList<>();
+measurements.add("a");
+String[] values = new String[]{"\\\\", "\\t", "\\\"", "\\u96d5"};
+for(int i = 0; i <= values.length; i++){
+ List<String> valueList = new ArrayList<>();
+ valueList.add(values[i]);
+ session.insertRecord(deviceId, i + 1, measurements, valueList);
+ }
+```
+
+Query the data of root.sg.a, you can see that there is no unescaping:
+
+```Plain%20Text
+// query result
++-----------------------------+---------+
+| Time|root.sg.a|
++-----------------------------+---------+
+|1970-01-01T08:00:00.001+08:00| \\|
+|1970-01-01T08:00:00.002+08:00| \t|
+|1970-01-01T08:00:00.003+08:00| \"|
+|1970-01-01T08:00:00.004+08:00| \u96d5|
++-----------------------------+---------+
+```
+
+Instead use SQL to insert data into root.sg.a:
+
+```SQL
+# SQL insert
+insert into root.sg(time, a) values(1, "\\")
+insert into root.sg(time, a) values(2, "\t")
+insert into root.sg(time, a) values(3, "\"")
+insert into root.sg(time, a) values(4, "\u96d5")
+```
+
+Query the data of root.sg.a, you can see that the string is unescaped:
+
+```Plain%20Text
+// query result
++-----------------------------+---------+
+| Time|root.sg.a|
++-----------------------------+---------+
+|1970-01-01T08:00:00.001+08:00| \|
+|1970-01-01T08:00:00.002+08:00| |
+|1970-01-01T08:00:00.003+08:00| "|
+|1970-01-01T08:00:00.004+08:00| 雕|
++-----------------------------+---------+
+```
-- **After we release 0.14.0, how to upgrade from v.13.x to v0.14.x?**
-
- - **Version 0.14 has changed the SQL syntax conventions (please refer to the syntax conventions section of the user manual), the incompatibilities are as follows:**
- - **Identifiers that are not quoted with backquotes are not allowed to be pure numbers and only allowed to contain letters, Chinese characters, and underscores. If the above occurs in an identifier, use backquotes to enclose the identifier.**
- - **Identifiers no longer support quoting with single and double quotes, please use backquotes instead.**
- - **When using the path node name in the Session API, it needs to be consistent with that in the SQL statement. If the path node is a pure number 111, it needs to be enclosed in backquotes in the SQL statement and written as \`111\`, then when using the Session API, the corresponding parameter also needs to be written as \`111\`.**
- - In order to ensure the stability of UDF-related APIs, in version 0.14, UDF-related APIs are seperated into an independent module and no longer depend on the tsfile package. The implemented UDFs need to rewrite the code, replace `TsDataType` with `Type`, and replace `org .apache.iotdb.tsfile.utils.Binary` with `org.apache.iotdb.udf.api.type.Binary`, then redo the packaging and loading process.
## How to Upgrade
@@ -193,7 +314,6 @@ Legacy version are available here: [https://archive.apache.org/dist/iotdb/](http
* Stop IoTDB v0.8 instance, and start v0.9.x, then the IoTDB will upgrade data file format automatically.
-
# All releases
diff --git a/docs/UserGuide/Reference/Syntax-Conventions.md b/docs/UserGuide/Reference/Syntax-Conventions.md
index c492bd55d2..bf76c34195 100644
--- a/docs/UserGuide/Reference/Syntax-Conventions.md
+++ b/docs/UserGuide/Reference/Syntax-Conventions.md
@@ -19,143 +19,12 @@
-->
-# Syntax Conventions
-## Issues with syntax conventions in 0.13 and earlier version
-
-In previous versions of syntax conventions, we introduced some ambiguity to maintain compatibility. To avoid ambiguity, we have designed new syntax conventions, and this chapter will explain the issues with the old syntax conventions and why we made the change.
-
-### Issues related to identifier
-
-In version 0.13 and earlier, identifiers (including path node names) that are not quoted with backquotes are allowed to be pure numbers(Pure numeric path node names need to be enclosed in backquotes in the `SELECT` clause), and are allowed to contain some special characters. **In version 0.14, identifiers that are not quoted with backquotes are not allowed to be pure numbers and only allowed to contain letters, Chinese characters, and underscores. **
-
-### Issues related to node name
-
-In previous versions of syntax conventions, when do you need to add quotation marks to the node name, and the rules for using single and double quotation marks or backquotes are complicated. We have unified usage of quotation marks in the new syntax conventions. For details, please refer to the relevant chapters of this document.
-
-#### When to use single and double quotes and backquotes
-
-In previous versions of syntax conventions, path node names were defined as identifiers, but when the path separator . was required in the path node name, single or double quotes were required. This goes against the rule that identifiers are quoted using backquotes.
-
-```SQL
-# In the previous syntax convention, if you need to create a time series root.sg.`www.baidu.com`, you need to use the following statement:
-create root.sg.'www.baidu.com' with datatype=BOOLEAN, encoding=PLAIN
-
-# The time series created by this statement is actually root.sg.'www.baidu.com', that is, the quotation marks are stored together. The three nodes of the time series are {"root","sg","'www.baidu.com'"}.
-
-# In the query statement, if you want to query the data of the time series, the query statement is as follows:
-select 'www.baidu.com' from root.sg;
-```
-
-In the new syntax conventions, special node names are uniformly quoted using backquotes:
-
-```SQL
-# In the new syntax convention, if you need to create a time series root.sg.`www.baidu.com`, the syntax is as follows:
-create root.sg.`www.baidu.com` with 'datatype' = 'BOOLEAN', 'encoding' = 'PLAIN'
-
-#To query the time series, you can use the following statement:
-select `www.baidu.com` from root.sg;
-```
-
-#### The issues of using quotation marks inside node names
-
-In previous versions of syntax conventions, when single quotes ' and double quotes " are used in path node names, they need to be escaped with a backslash \, and the backslashes will be stored as part of the path node name. Other identifiers do not have this restriction, causing inconsistency.
-
-```SQL
-# Create time series root.sg.\"a
-create timeseries root.sg.`\"a` with datatype=TEXT,encoding=PLAIN;
-
-# Query time series root.sg.\"a
-select `\"a` from root.sg;
-+-----------------------------+-----------+
-| Time|root.sg.\"a|
-+-----------------------------+-----------+
-|1970-01-01T08:00:00.004+08:00| test|
-+-----------------------------+-----------+
-```
-
-In the new syntax convention, special path node names are uniformly referenced with backquotes. When single and double quotes are used in path node names, there is no need to add backslashes to escape, and backquotes need to be double-written. For details, please refer to the relevant chapters of the new syntax conventions.
-
-### Issues related to session API
-
-#### Session API syntax restrictions
-
-In version 0.13, the restrictions on using path nodes in non-SQL interfaces are as follows:
-
-- The node names in path or path prefix as parameter:
- - The node names which should be escaped by backticks (`) in the SQL statement, and escaping is not required here.
- - The node names enclosed in single or double quotes still need to be enclosed in single or double quotes and must be escaped for JAVA strings.
- - For the `checkTimeseriesExists` interface, since the IoTDB-SQL interface is called internally, the time-series pathname must be consistent with the SQL syntax conventions and be escaped for JAVA strings.
-
-**In version 0.14, restrictions on using path nodes in non-SQL interfaces were enhanced:**
-
-- **The node names in path or path prefix as parameter: The node names which should be escaped by backticks (`) in the SQL statement, escaping is required here.**
-- **Code example for syntax convention could be found at:** `example/session/src/main/java/org/apache/iotdb/SyntaxConventionRelatedExample.java`
-
-#### Inconsistent handling of string escaping between SQL and Session interfaces
-
-In previous releases, there was an inconsistency between the SQL and Session interfaces when using strings. For example, when using SQL to insert Text type data, the string will be unescaped, but not when using the Session interface, which is inconsistent. **In the new syntax convention, we do not unescape the strings. What you store is what will be obtained when querying (for the rules of using single and double quotation marks inside strings, please refer to this document for string li [...]
-
-The following are examples of inconsistencies in the old syntax conventions:
-
-Use Session's insertRecord method to insert data into the time series root.sg.a
-
-```Java
-// session insert
-String deviceId = "root.sg";
-List<String> measurements = new ArrayList<>();
-measurements.add("a");
-String[] values = new String[]{"\\\\", "\\t", "\\\"", "\\u96d5"};
-for(int i = 0; i <= values.length; i++){
- List<String> valueList = new ArrayList<>();
- valueList.add(values[i]);
- session.insertRecord(deviceId, i + 1, measurements, valueList);
- }
-```
-
-Query the data of root.sg.a, you can see that there is no unescaping:
-
-```Plain%20Text
-// query result
-+-----------------------------+---------+
-| Time|root.sg.a|
-+-----------------------------+---------+
-|1970-01-01T08:00:00.001+08:00| \\|
-|1970-01-01T08:00:00.002+08:00| \t|
-|1970-01-01T08:00:00.003+08:00| \"|
-|1970-01-01T08:00:00.004+08:00| \u96d5|
-+-----------------------------+---------+
-```
-
-Instead use SQL to insert data into root.sg.a:
-
-```SQL
-# SQL insert
-insert into root.sg(time, a) values(1, "\\")
-insert into root.sg(time, a) values(2, "\t")
-insert into root.sg(time, a) values(3, "\"")
-insert into root.sg(time, a) values(4, "\u96d5")
-```
-
-Query the data of root.sg.a, you can see that the string is unescaped:
-
-```Plain%20Text
-// query result
-+-----------------------------+---------+
-| Time|root.sg.a|
-+-----------------------------+---------+
-|1970-01-01T08:00:00.001+08:00| \|
-|1970-01-01T08:00:00.002+08:00| |
-|1970-01-01T08:00:00.003+08:00| "|
-|1970-01-01T08:00:00.004+08:00| 雕|
-+-----------------------------+---------+
-```
-
-## Literal Values
+# Literal Values
This section describes how to write literal values in IoTDB. These include strings, numbers, timestamp values, boolean values, and NULL.
-### String Literals
+## String Literals
> We refer to MySQL's definition of string：A string is a sequence of bytes or characters, enclosed within either single quote (`'`) or double quote (`"`) characters.
@@ -242,7 +111,7 @@ Usages of string literals:
- The key/value of an attribute can be String Literal and identifier, more details can be found at **key-value pair** part.
-#### How to use quotation marks in String Literals
+### How to use quotation marks in String Literals
There are several ways to include quote characters within a string:
@@ -263,7 +132,7 @@ The following examples demonstrate how quoting and escaping work:
"""string" // "string
```
-### Numeric Literals
+## Numeric Literals
Number literals include integer (exact-value) literals and floating-point (approximate-value) literals.
@@ -277,27 +146,27 @@ The `FLOAT` and `DOUBLE` data types are floating-point types and calculations ar
An integer may be used in floating-point context; it is interpreted as the equivalent floating-point number.
-### Timestamp Literals
+## Timestamp Literals
The timestamp is the time point at which data is produced. It includes absolute timestamps and relative timestamps in IoTDB. For information about timestamp support in IoTDB, see [Data Type Doc](../Data-Concept/Data-Type.md).
Specially, `NOW()` represents a constant timestamp that indicates the system time at which the statement began to execute.
-### Boolean Literals
+## Boolean Literals
The constants `TRUE` and `FALSE` evaluate to 1 and 0, respectively. The constant names can be written in any lettercase.
-### NULL Values
+## NULL Values
The `NULL` value means “no data.” `NULL` can be written in any lettercase.
-## Identifiers
+# Identifiers
-### Usage scenarios
+## Usage scenarios
Certain objects within IoTDB, including `TRIGGER`, `FUNCTION`(UDF), `CONTINUOUS QUERY`, `SCHEMA TEMPLATE`, `USER`, `ROLE`,`Pipe`,`PipeSink`,`alias` and other object names are known as identifiers.
-### Constraints
+## Constraints
Below are basic constraints of identifiers, specific identifiers may have other constraints, for example, `user` should consists of more than 4 characters.
@@ -313,7 +182,7 @@ Below are basic constraints of identifiers, specific identifiers may have other
- Identifier contains special characters.
- Identifier that is a real number.
-### How to use quotations marks in quoted identifiers
+## How to use quotations marks in quoted identifiers
`'` and `"` can be used directly in quoted identifiers.
@@ -329,7 +198,7 @@ create schema template `t1``t`
(temperature FLOAT encoding=RLE, status BOOLEAN encoding=PLAIN compression=SNAPPY)
```
-### Examples
+## Examples
Examples of case in which quoted identifier is used ：
@@ -410,11 +279,11 @@ Examples of case in which quoted identifier is used ：
- The key/value of an attribute can be String Literal and identifier, more details can be found at **key-value pair** part.
-## Node Names in Path
+# Node Names in Path
Node name is a special identifier, it can also be wildcard `*` and `**`. When creating timeseries, node name can not be wildcard. In query statment, you can use wildcard to match one or more nodes of path.
-### Wildcard
+## Wildcard
`*` represents one node. For example, `root.vehicle.*.sensor1` represents a 4-node path which is prefixed with `root.vehicle` and suffixed with `sensor1`.
@@ -446,7 +315,7 @@ select a*b from root.sg
|Time|root.sg.a * root.sg.b|
```
-### Identifier
+## Identifier
When node name is not wildcard, it is a identifier, which means the constraints on it is the same as described in Identifier part.
@@ -509,7 +378,7 @@ Results:
+-----------------------------+-----------+
```
-## Key-Value Pair
+# Key-Value Pair
**The key/value of an attribute can be constant(including string) and identifier. **
@@ -608,13 +477,13 @@ CREATE PIPE my_pipe TO my_iotdb FROM
(select ** from root WHERE time>=yyyy-mm-dd HH:MM:SS) WITH 'SyncDelOp' = 'true'
```
-## Keywords and Reserved Words
+# Keywords and Reserved Words
Keywords are words that have significance in SQL. Keywords can be used as an identifier. Certain keywords, such as TIME/TIMESTAMP and ROOT, are reserved and cannot use as identifiers.
[Keywords and Reserved Words](Keywords.md) shows the keywords and reserved words in IoTDB.
-## Session、TsFile API
+# Session、TsFile API
When using the Session and TsFile APIs, if the method you call requires parameters such as measurement, device, storage group, path in the form of String, **please ensure that the parameters passed in the input string is the same as when using the SQL statement**, here are some examples to help you understand. Code example could be found at: `example/session/src/main/java/org/apache/iotdb/SyntaxConventionRelatedExample.java`
@@ -713,7 +582,7 @@ String[] paths = new String[]{"root.sg.a", "root.sg.`a.``\"b`", "root.sg.`111`"}
List<String> pathList = Arrays.asList(paths);
```
-## Detailed Definitions of Lexical and Grammar
+# Detailed Definitions of Lexical and Grammar
Please read the lexical and grammar description files in our code repository:
diff --git a/docs/zh/Download/README.md b/docs/zh/Download/README.md
index aa2065f2ac..72b64e080b 100644
--- a/docs/zh/Download/README.md
+++ b/docs/zh/Download/README.md
@@ -98,22 +98,143 @@
> sudo sysctl -w kern.ipc.somaxconn=65535
```
-## 关于 0.14.0-preview1
+## 关于 Version 1.0
-- 0.14.0-preview1 仅包括分布式预览版，供测试及试用，不推荐从 0.13 升级到预览版。
+- 如何从 v0.13.x 升级到 v1.0.x?
-- 0.14.0-preview1 的用户手册在 latest 栏目，未单独新建栏目，正式版会新建栏目。
+ - **1.0版本进行了 SQL 语法约定的改动（请参考用户手册语法约定章节）,不兼容之处可以参考下方1.0 版本不兼容的语法详细说明**。
+ - 为了保证 UDF 相关 API 的稳定性，1.0 版本中 UDF 相关 API 被独立为一个单独的 module，不再依赖 tsfile 包，已经实现的 UDF 需要改写代码，将 `TsDataType` 替换为 `Type`，将 `org.apache.iotdb.tsfile.utils.Binary` 替换成 `org.apache.iotdb.udf.api.type.Binary`，并重新进行打包装载流程。
-**<font color=red>注意: 不要使用 stop-confignode.bat/sh 脚本，会误杀其他进程</font>**:
+### 1.0 版本不兼容的语法详细说明
+在之前版本的语法约定中，为了保持兼容性，我们引入了一些会引起歧义的规定。为了避免歧义，我们设计了新的语法约定，本章将说明旧语法约定中存在的问题，以及我们做出改动的原因。
-- 如何从 v0.13.x 升级到 v0.14.x?
-
- - **0.14 版本进行了 SQL 语法约定的改动（请参考用户手册语法约定章节），不兼容之处如下：**
- - **不使用反引号引用的标识符不允许为实数，不使用反引号引用的标识符，只允许包含字母、中文字符、下划线。如果标识符中出现上述情况，请使用反引号将标识符括起。**
- - **标识符不再支持使用单引号和双引号进行引用，请统一改为使用反引号引用。**
- - **Session 接口中使用路径结点名时，写法需要与 SQL 语句中的一致。如路径结点为实数111，在 SQL 语句中需要使用反引号括起，写作\`111\`, 那么使用 Session 接口时，相应参数也需要写作\`111\`。**
- - 为了保证 UDF 相关 API 的稳定性，0.14 版本中 UDF 相关 API 被独立为一个单独的 module，不再依赖 tsfile 包，已经实现的 UDF 需要改写代码，将 `TsDataType` 替换为 `Type`，将 `org.apache.iotdb.tsfile.utils.Binary` 替换成 `org.apache.iotdb.udf.api.type.Binary`，并重新进行打包装载流程。
+#### 标识符限制增强
+
+在0.13及之前版本中，不使用反引号引用的标识符（包括路径结点）允许为实数（实数路径名在 `SELECT` 子句中需要用反引号括起），且允许包含部分特殊字符，**在 1.0 版本中，不使用反引号引用的标识符不允许为实数，不使用反引号引用的标识符，只允许包含字母、中文字符、下划线。**
+
+#### 路径名使用的相关问题
+
+在旧语法约定中，什么时候需要给路径结点名添加引号，用单双引号还是反引号的规则较为复杂，在新的语法约定中我们做了统一，具体可以参考本文档的相关章节。
+
+##### 单双引号和反引号的使用时机
+
+在之前的语法约定中，路径结点名被定义成标识符，但是当需要在路径结点名中使用路径分隔符 . 时，需要使用单引号或者双引号引用。这与标识符使用反引号引用的规则相悖。
+
+```SQL
+# 在之前的语法约定中，如果需要创建时间序列 root.sg.`www.baidu.com`，需要使用下述语句：
+create root.sg.'www.baidu.com' with datatype=BOOLEAN, encoding=PLAIN
+
+# 该语句创建的时间序列实际为 root.sg.'www.baidu.com'，即引号一并存入,该时间序列的三个结点为{"root","sg","'www.baidu.com'"}
+
+# 在查询语句中，如果希望查询该时间序列的数据，查询语句如下：
+select 'www.baidu.com' from root.sg;
+```
+
+**而在 1.0 版本的语法约定中，特殊路径结点名统一使用反引号引用：**
+
+```SQL
+# 在现有语法约定中，如果需要创建时间序列 root.sg.`www.baidu.com`，语法如下：
+create root.sg.`www.baidu.com` with datatype = BOOLEAN, encoding = PLAIN
+
+# 查询该时间序列可以通过如下语句：
+select `www.baidu.com` from root.sg;
+```
+
+##### 路径结点名内部使用引号的问题
+
+在旧语法约定中，在路径结点名中使用单引号 ' 和 双引号 " 时，需要使用反斜杠 \ 进行转义，且反斜杠会被视为路径结点名的一部分存入，而在使用其它标识符时没有这个限制，造成了不统一。
+
+```SQL
+# 创建时间序列 root.sg.\"a
+create timeseries root.sg.`\"a` with datatype=TEXT,encoding=PLAIN;
+
+# 查询时间序列 root.sg.\"a
+select `\"a` from root.sg;
++-----------------------------+-----------+
+| Time|root.sg.\"a|
++-----------------------------+-----------+
+|1970-01-01T08:00:00.004+08:00| test|
++-----------------------------+-----------+
+```
+
+**在新语法约定中，特殊路径结点名统一使用反引号进行引用**，在路径结点名中使用单双引号无须添加反斜杠转义，使用反引号需要双写，具体可以参考新语法约定路径结点名章节。
+
+#### Session 接口相关
+
+##### Session 接口语法限制
+
+在0.13版本中，对于非SQL接口中使用路径结点的限制如下：
+
+- 经参数传入的路径或路径前缀中的节点：
+ - 在 SQL 语句中需要使用反引号（`）进行转义的，此处均不需要进行转义。
+ - 使用单引号或双引号括起的节点，仍需要使用单引号或双引号括起，并且要针对 JAVA 字符串进行反转义。
+ - 对于 `checkTimeseriesExists` 接口，由于内部调用了 IoTDB-SQL 接口，因此需要和 SQL 语法规范保持一致，并且针对 JAVA 字符串进行反转义。
+
+**1.0 版本中，对非SQL接口中使用路径结点的限制增强：**
+
+- **经参数传入的路径或路径前缀中的节点： 在 SQL 语句中需要使用反引号（`）进行转义的，均需要使用反引号进行转义。**
+
+- **语法说明相关代码示例可以参考：**`example/session/src/main/java/org/apache/iotdb/SyntaxConventionRelatedExample.java`
+
+##### SQL和Session接口对字符串反转义处理不一致
+
+**在之前版本中，使用字符串时，SQL 和 Session 接口存在不一致的情况**。比如使用 SQL 插入 Text 类型数据时，会对字符串进行反转义处理，而使用 Session 接口时不会进行这样的处理，存在不一致。**在新的语法约定中，我们统一不对字符串做反转义处理，存入什么内容，在查询时就会得到什么内容(字符串内部使用单双引号的规则可以参考本文档字符串常量章节)。**
+
+**下面是旧语法约定中不一致的例子：**
+
+使用 Session 的 insertRecord 方法向时序 root.sg.a 中插入数据
+
+```Java
+// session 插入
+String deviceId = "root.sg";
+List<String> measurements = new ArrayList<>();
+measurements.add("a");
+String[] values = new String[]{"\\\\", "\\t", "\\\"", "\\u96d5"};
+for(int i = 0; i <= values.length; i++){
+ List<String> valueList = new ArrayList<>();
+ valueList.add(values[i]);
+ session.insertRecord(deviceId, i + 1, measurements, valueList);
+ }
+```
+
+查询 root.sg.a 的数据，可以看到没有做反转义处理：
+
+```Plain%20Text
+// 查询结果
++-----------------------------+---------+
+| Time|root.sg.a|
++-----------------------------+---------+
+|1970-01-01T08:00:00.001+08:00| \\|
+|1970-01-01T08:00:00.002+08:00| \t|
+|1970-01-01T08:00:00.003+08:00| \"|
+|1970-01-01T08:00:00.004+08:00| \u96d5|
++-----------------------------+---------+
+```
+
+而使用 SQL 向 root.sg.a 中插入数据
+
+```SQL
+# SQL 插入
+insert into root.sg(time, a) values(1, "\\")
+insert into root.sg(time, a) values(2, "\t")
+insert into root.sg(time, a) values(3, "\"")
+insert into root.sg(time, a) values(4, "\u96d5")
+```
+
+查询 root.sg.a 的数据，可以看到字符串进行了反转义：
+
+```Plain%20Text
+// 查询结果
++-----------------------------+---------+
+| Time|root.sg.a|
++-----------------------------+---------+
+|1970-01-01T08:00:00.001+08:00| \|
+|1970-01-01T08:00:00.002+08:00| |
+|1970-01-01T08:00:00.003+08:00| "|
+|1970-01-01T08:00:00.004+08:00| 雕|
++-----------------------------+---------+
+```
# 如何升级
diff --git a/docs/zh/UserGuide/Reference/Syntax-Conventions.md b/docs/zh/UserGuide/Reference/Syntax-Conventions.md
index 2fb1111d65..6a94023f52 100644
--- a/docs/zh/UserGuide/Reference/Syntax-Conventions.md
+++ b/docs/zh/UserGuide/Reference/Syntax-Conventions.md
@@ -19,144 +19,12 @@
-->
-# 语法约定
-## 旧语法约定中的问题（0.14 版本不兼容的语法）
-
-在之前版本的语法约定中，为了保持兼容性，我们引入了一些会引起歧义的规定。为了避免歧义，我们设计了新的语法约定，本章将说明旧语法约定中存在的问题，以及我们做出改动的原因。
-
-### 标识符限制增强
-
-在0.13及之前版本中，不使用反引号引用的标识符（包括路径结点）允许为实数（实数路径名在 `SELECT` 子句中需要用反引号括起），且允许包含部分特殊字符，**在0.14版本中，不使用反引号引用的标识符不允许为实数，不使用反引号引用的标识符，只允许包含字母、中文字符、下划线。**
-
-### 路径名使用的相关问题
-
-在旧语法约定中，什么时候需要给路径结点名添加引号，用单双引号还是反引号的规则较为复杂，在新的语法约定中我们做了统一，具体可以参考本文档的相关章节。
-
-#### 单双引号和反引号的使用时机
-
-在之前的语法约定中，路径结点名被定义成标识符，但是当需要在路径结点名中使用路径分隔符 . 时，需要使用单引号或者双引号引用。这与标识符使用反引号引用的规则相悖。
-
-```SQL
-# 在之前的语法约定中，如果需要创建时间序列 root.sg.`www.baidu.com`，需要使用下述语句：
-create root.sg.'www.baidu.com' with datatype=BOOLEAN, encoding=PLAIN
-
-# 该语句创建的时间序列实际为 root.sg.'www.baidu.com'，即引号一并存入,该时间序列的三个结点为{"root","sg","'www.baidu.com'"}
-
-# 在查询语句中，如果希望查询该时间序列的数据，查询语句如下：
-select 'www.baidu.com' from root.sg;
-```
-
-而在新语法约定中，特殊路径结点名统一使用反引号引用：
-
-```SQL
-# 在现有语法约定中，如果需要创建时间序列 root.sg.`www.baidu.com`，语法如下：
-create root.sg.`www.baidu.com` with datatype = BOOLEAN, encoding = PLAIN
-
-# 查询该时间序列可以通过如下语句：
-select `www.baidu.com` from root.sg;
-```
-
-#### 路径结点名内部使用引号的问题
-
-在旧语法约定中，在路径结点名中使用单引号 ' 和 双引号 " 时，需要使用反斜杠 \ 进行转义，且反斜杠会被视为路径结点名的一部分存入，而在使用其它标识符时没有这个限制，造成了不统一。
-
-```SQL
-# 创建时间序列 root.sg.\"a
-create timeseries root.sg.`\"a` with datatype=TEXT,encoding=PLAIN;
-
-# 查询时间序列 root.sg.\"a
-select `\"a` from root.sg;
-+-----------------------------+-----------+
-| Time|root.sg.\"a|
-+-----------------------------+-----------+
-|1970-01-01T08:00:00.004+08:00| test|
-+-----------------------------+-----------+
-```
-
-在新语法约定中，特殊路径结点名统一使用反引号进行引用，在路径结点名中使用单双引号无须添加反斜杠转义，使用反引号需要双写，具体可以参考新语法约定路径结点名章节。
-
-### Session 接口相关
-
-#### Session 接口语法限制
-
-在0.13版本中，对于非SQL接口中使用路径结点的限制如下：
-
-- 经参数传入的路径或路径前缀中的节点：
- - 在 SQL 语句中需要使用反引号（`）进行转义的，此处均不需要进行转义。
- - 使用单引号或双引号括起的节点，仍需要使用单引号或双引号括起，并且要针对 JAVA 字符串进行反转义。
- - 对于 `checkTimeseriesExists` 接口，由于内部调用了 IoTDB-SQL 接口，因此需要和 SQL 语法规范保持一致，并且针对 JAVA 字符串进行反转义。
-
-**0.14 版本中，对非SQL接口中使用路径结点的限制增强：**
-
-- **经参数传入的路径或路径前缀中的节点： 在 SQL 语句中需要使用反引号（`）进行转义的，均需要使用反引号进行转义。**
-
-- **语法说明相关代码示例可以参考：**`example/session/src/main/java/org/apache/iotdb/SyntaxConventionRelatedExample.java`
-
-#### SQL和Session接口对字符串反转义处理不一致
-
-在之前版本中，使用字符串时，SQL 和 Session 接口存在不一致的情况。比如使用 SQL 插入 Text 类型数据时，会对字符串进行反转义处理，而使用 Session 接口时不会进行这样的处理，存在不一致。**在新的语法约定中，我们统一不对字符串做反转义处理，存入什么内容，在查询时就会得到什么内容(字符串内部使用单双引号的规则可以参考本文档字符串常量章节)。**
-
-下面是旧语法约定中不一致的例子：
-
-使用 Session 的 insertRecord 方法向时序 root.sg.a 中插入数据
-
-```Java
-// session 插入
-String deviceId = "root.sg";
-List<String> measurements = new ArrayList<>();
-measurements.add("a");
-String[] values = new String[]{"\\\\", "\\t", "\\\"", "\\u96d5"};
-for(int i = 0; i <= values.length; i++){
- List<String> valueList = new ArrayList<>();
- valueList.add(values[i]);
- session.insertRecord(deviceId, i + 1, measurements, valueList);
- }
-```
-
-查询 root.sg.a 的数据，可以看到没有做反转义处理：
-
-```Plain%20Text
-// 查询结果
-+-----------------------------+---------+
-| Time|root.sg.a|
-+-----------------------------+---------+
-|1970-01-01T08:00:00.001+08:00| \\|
-|1970-01-01T08:00:00.002+08:00| \t|
-|1970-01-01T08:00:00.003+08:00| \"|
-|1970-01-01T08:00:00.004+08:00| \u96d5|
-+-----------------------------+---------+
-```
-
-而使用 SQL 向 root.sg.a 中插入数据
-
-```SQL
-# SQL 插入
-insert into root.sg(time, a) values(1, "\\")
-insert into root.sg(time, a) values(2, "\t")
-insert into root.sg(time, a) values(3, "\"")
-insert into root.sg(time, a) values(4, "\u96d5")
-```
-
-查询 root.sg.a 的数据，可以看到字符串进行了反转义：
-
-```Plain%20Text
-// 查询结果
-+-----------------------------+---------+
-| Time|root.sg.a|
-+-----------------------------+---------+
-|1970-01-01T08:00:00.001+08:00| \|
-|1970-01-01T08:00:00.002+08:00| |
-|1970-01-01T08:00:00.003+08:00| "|
-|1970-01-01T08:00:00.004+08:00| 雕|
-+-----------------------------+---------+
-```
-
-## 字面值常量
+# 字面值常量
该部分对 IoTDB 中支持的字面值常量进行说明，包括字符串常量、数值型常量、时间戳常量、布尔型常量和空值。
-### 字符串常量
+## 字符串常量
> 我们参照了 MySQL 对 字符串的定义：A string is a sequence of bytes or characters, enclosed within either single quote (`'`) or double quote (`"`) characters.
@@ -169,7 +37,7 @@ MySQL 对字符串的定义可以参考：[MySQL :: MySQL 8.0 Reference Manual :
"another string"
```
-#### 使用场景
+### 使用场景
- `INSERT` 或者 `SELECT` 中用于表达 `TEXT` 类型数据的场景。
@@ -240,7 +108,7 @@ MySQL 对字符串的定义可以参考：[MySQL :: MySQL 8.0 Reference Manual :
- 用于表示键值对，键值对的键和值可以被定义成常量（包括字符串）或者标识符，具体请参考键值对章节。
-#### 如何在字符串内使用引号
+### 如何在字符串内使用引号
- 在单引号引起的字符串内，双引号无需特殊处理。同理，在双引号引起的字符串内，单引号无需特殊处理。
- 在单引号引起的字符串里，可以通过双写单引号来表示一个单引号，即单引号 ' 可以表示为 ''。
@@ -260,7 +128,7 @@ MySQL 对字符串的定义可以参考：[MySQL :: MySQL 8.0 Reference Manual :
"""string" // "string
```
-### 数值型常量
+## 数值型常量
数值型常量包括整型和浮点型。
@@ -272,27 +140,27 @@ MySQL 对字符串的定义可以参考：[MySQL :: MySQL 8.0 Reference Manual :
在浮点上下文中可以使用整数，它会被解释为等效的浮点数。
-### 时间戳常量
+## 时间戳常量
时间戳是一个数据到来的时间点，在 IoTDB 中分为绝对时间戳和相对时间戳。详细信息可参考 [数据类型文档](https://iotdb.apache.org/zh/UserGuide/Master/Data-Concept/Data-Type.html)。
特别地，`NOW()`表示语句开始执行时的服务端系统时间戳。
-### 布尔型常量
+## 布尔型常量
布尔值常量 `TRUE` 和 `FALSE` 分别等价于 `1` 和 `0`，它们对大小写不敏感。
-### 空值
+## 空值
`NULL`值表示没有数据。`NULL`对大小写不敏感。
-## 标识符
+# 标识符
-### 使用场景
+## 使用场景
在 IoTDB 中，触发器名称、UDF函数名、元数据模板名称、用户与角色名、连续查询标识、Pipe、PipeSink、键值对中的键和值、别名等可以作为标识符。
-### 约束
+## 约束
请注意，此处约束是标识符的通用约束，具体标识符可能还附带其它约束条件，如用户名限制字符数大于等于4，更严格的约束请参考具体标识符相关的说明文档。
@@ -313,7 +181,7 @@ MySQL 对字符串的定义可以参考：[MySQL :: MySQL 8.0 Reference Manual :
- 标识符包含不允许的特殊字符。
- 标识符为实数。
-### 如何在反引号引起的标识符中使用引号
+## 如何在反引号引起的标识符中使用引号
**在反引号引起的标识符中可以直接使用单引号和双引号。**
@@ -329,7 +197,7 @@ create schema template `t1't"t`
(temperature FLOAT encoding=RLE, status BOOLEAN encoding=PLAIN compression=SNAPPY)
```
-### 特殊情况示例
+## 特殊情况示例
需要使用反引号进行引用的部分情况示例：
@@ -409,11 +277,11 @@ create schema template `t1't"t`
- 用于表示键值对，键值对的键和值可以被定义成常量（包括字符串）或者标识符，具体请参考键值对章节。
-## 路径结点名
+# 路径结点名
路径结点名是特殊的标识符，其还可以是通配符 \* 或 \*\*。在创建时间序列时，各层级的路径结点名不能为通配符 \* 或 \*\*。在查询语句中，可以用通配符 \* 或 \*\* 来表示路径结点名，以匹配一层或多层路径。
-### 通配符
+## 通配符
`*`在路径中表示一层。例如`root.vehicle.*.sensor1`代表的是以`root.vehicle`为前缀，以`sensor1`为后缀，层次等于 4 层的路径。
@@ -444,7 +312,7 @@ select a*b from root.sg
|Time|root.sg.a * root.sg.b|
```
-### 标识符
+## 标识符
路径结点名不为通配符时，使用方法和标识符一致。**在 SQL 中需要使用反引号引用的路径结点，在结果集中也会用反引号引起。**
@@ -509,7 +377,7 @@ select `111` from root.sg
+-----------------------------+-------------+
```
-## 键值对
+# 键值对
**键值对的键和值可以被定义为标识符或者常量。**
@@ -608,13 +476,13 @@ CREATE PIPE my_pipe TO my_iotdb FROM
(select ** from root WHERE time>=yyyy-mm-dd HH:MM:SS) WITH 'SyncDelOp' = 'true'
```
-## 关键字和保留字
+# 关键字和保留字
关键字是在 SQL 具有特定含义的词，可以作为标识符。保留字是关键字的一个子集，保留字不能用于标识符。
关于 IoTDB 的关键字和保留字列表，可以查看 [关键字和保留字](https://iotdb.apache.org/zh/UserGuide/Master/Reference/Keywords.html) 。
-## Session、TsFile API
+# Session、TsFile API
在使用Session、TsFIle API时，如果您调用的方法需要以字符串形式传入物理量（measurement）、设备（device）、存储组（storage group）、路径（path）等参数，**请保证所传入字符串与使用 SQL 语句时的写法一致**，下面是一些帮助您理解的例子。具体代码示例可以参考：`example/session/src/main/java/org/apache/iotdb/SyntaxConventionRelatedExample.java`
@@ -713,7 +581,7 @@ String[] paths = new String[]{"root.sg.a", "root.sg.`a.``\"b`", "root.sg.`111`"}
List<String> pathList = Arrays.asList(paths);
```
-## 词法与文法详细定义
+# 词法与文法详细定义
请阅读代码仓库中的词法和语法描述文件：