[iotdb] 08/08: Syntax-Conventions CN

[rong]

This is an automated email from the ASF dual-hosted git repository.

rong pushed a commit to branch iotdb-1620
in repository https://gitbox.apache.org/repos/asf/iotdb.git

commit 478e88d9fbea966b3d470e73b9ce82edb3002954
Author: Steve Yurong Su <r...@apache.org>
AuthorDate: Wed Oct 27 12:10:58 2021 +0800

    Syntax-Conventions CN
---
 .gitignore                                         |  1 +
 .../IoTDB-SQL-Language/Syntax-Conventions.md       | 90 +++++++++++++++++++++-
 2 files changed, 89 insertions(+), 2 deletions(-)

diff --git a/.gitignore b/.gitignore
index 491b7cc..31c481f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -112,3 +112,4 @@ node3/
 # ANTLR
 antlr/gen/
 antlr/src/main/antlr4/org/apache/iotdb/db/qp/sql/gen/
+antlr/src/main/antlr4/org/apache/iotdb/db/qp/sql/IoTDBSqlLexer.tokens
diff --git a/docs/zh/UserGuide/IoTDB-SQL-Language/Syntax-Conventions.md 
b/docs/zh/UserGuide/IoTDB-SQL-Language/Syntax-Conventions.md
index 1175f85..7396c5e 100644
--- a/docs/zh/UserGuide/IoTDB-SQL-Language/Syntax-Conventions.md
+++ b/docs/zh/UserGuide/IoTDB-SQL-Language/Syntax-Conventions.md
@@ -21,9 +21,95 @@
 
 # 语法约定
 
-## ID 中的 双引号（\"）、反引号（\`）
+## 双引号（\"）、反引号（\`）
+
+双引号和反引号内引用的字符串被解释为标识符（ID），被引用的字符串一般包含特殊字符。需要注意的是，被引用的字符串不可带有 `.` 字符。
+
+标识符（ID）的定义为：
+
+```sql
+ID
+    : NAME_CHAR+
+    | '"' (~('"' | '.') | '""')+ '"'
+    | '`' (~('`' | '.') | '``')+ '`'
+    ;
+
+fragment NAME_CHAR
+    : 'A'..'Z'
+    | 'a'..'z'
+    | '0'..'9'
+    | '_'
+    | ':'
+    | '@'
+    | '#'
+    | '$'
+    | '{'
+    | '}'
+    | CN_CHAR
+    ;
+
+fragment CN_CHAR
+    : '\u2E80'..'\u9FFF'
+    ;
+```
+
+标志符的使用场景：
+* `TRIGGER`，`FUNCTION`(UDF)，`CONTINUOUS QUERY`，`USER`，`ROLE` 等的名字。
+* 时间序列路径的表达：除了时间序列的开头的层级（`root`）和存储组层级外，层级还支持使用被  \`  或者 ` " ` 符号引用的特殊字符串作为其名称。
+
+例子：
+
+```sql
+CREATE FUNCTION "udfname:""actual-name""" AS 
'org.apache.iotdb.db.query.udf.example.Counter'
+# "udfname:""actual-name""" 会被解析成 udfname:"actual-name"
+
+CREATE FUNCTION `udfname:actual-name` AS 
'org.apache.iotdb.db.query.udf.example.Counter'
+# `udfname:actual-name` 会被解析成 udfname:actual-name
+
+CREATE TIMESERIES root.a.b.`s1+s2/s3`.c WITH DATATYPE=INT32,ENCODING=RLE
+# root.a.b.`s1+s2/s3`.c 会被解析成 root.a.b.s1+s2/s3.c
+```
+
 
-https://dev.mysql.com/doc/refman/5.6/en/string-literals.html
 
 ## 单引号（\'）
 
+字符串字面值只能由单引号（`'`）字符包围的字符串表示。
+
+字符串字面值（`STRING_LITERAL`）的定义为：
+
+```sql
+STRING_LITERAL
+    : '\'' ((~'\'') | '\'\'')* '\''
+    ;
+```
+
+字符串字面值的使用场景：
+
+* `INSERT` 或者 `SELECT` 中用于表达 `TEXT` 类型数据的场景
+* SQL 中 UDF 和 Trigger 的 Java 类全类名
+* `CREATE TRIGGER` 语句中描述触发器属性的键值对
+* UDF 函数输入参数中的属性
+* `LOAD` / `REMOVE` / `SETTLE` 指令中的文件路径
+* 用户密码
+
+例子：
+
+```sql
+SELECT `my-udf`(s1, s2, 'key'='value') FROM root.sg.d;
+
+CREATE TRIGGER trigger_name BEFORE INSERT ON root.a.b.`s1+s2/s3`.c AS 
'org.apache.iotdb.db.engine.trigger.example.Counter'
+
+CREATE USER `my-%+-*/user&name` 'my-password'
+```
+
+
+
+## 了解更多
+
+请阅读代码仓库中的词法和语法描述文件：
+
+词法文件：`antlr/src/main/antlr4/org/apache/iotdb/db/qp/sql/IoTDBSqlLexer.g4`
+
+语法文件：`antlr/src/main/antlr4/org/apache/iotdb/db/qp/sql/IoTDBSqlParser.g4`
+