You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iotdb.apache.org by ro...@apache.org on 2022/05/25 03:15:53 UTC
[iotdb] branch master updated: [IOTDB-3070][IOTDB-3074] modify docs related to syntax convention (#5983)
This is an automated email from the ASF dual-hosted git repository.
rong 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 68c0285527 [IOTDB-3070][IOTDB-3074] modify docs related to syntax convention (#5983)
68c0285527 is described below
commit 68c0285527ae61529ddad399e256759679fac92f
Author: Liao Lanyu <48...@users.noreply.github.com>
AuthorDate: Wed May 25 11:15:48 2022 +0800
[IOTDB-3070][IOTDB-3074] modify docs related to syntax convention (#5983)
---
docs/UserGuide/Reference/Syntax-Conventions.md | 476 +++++++++++++++------
docs/zh/UserGuide/Reference/Syntax-Conventions.md | 499 +++++++++++++++-------
2 files changed, 691 insertions(+), 284 deletions(-)
diff --git a/docs/UserGuide/Reference/Syntax-Conventions.md b/docs/UserGuide/Reference/Syntax-Conventions.md
index 47aa477d38..1b202d4b7d 100644
--- a/docs/UserGuide/Reference/Syntax-Conventions.md
+++ b/docs/UserGuide/Reference/Syntax-Conventions.md
@@ -21,22 +21,133 @@
# 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 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.
+
+### 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
This section describes how to write literal values in IoTDB. These include strings, numbers, timestamp values, boolean values, and NULL.
### String Literals
-A string is a sequence of characters, enclosed within either single quote (`'`) or double quote (`"`) characters. Examples:
+> 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.
+
+Definition of string in MySQL could be found here：[MySQL :: MySQL 8.0 Reference Manual :: 9.1.1 String Literals](https://dev.mysql.com/doc/refman/8.0/en/string-literals.html)
+
+So in IoTDB, **A string is a sequence of bytes or characters, enclosed within either single quote (`'`) or double quote (`"`) characters.** Examples：
+
```js
'a string'
"another string"
```
-We will unescape the string unless it is used as a file path. Examples can be found in the usage scenarios part.
-
-More information about escape characters can be found in : [Characters (The Java™ Tutorials > Learning the Java Language > Numbers and Strings)](https://docs.oracle.com/javase/tutorial/java/data/characters.html)
-
#### Usage Scenarios
Usages of string literals:
@@ -48,20 +159,19 @@ Usages of string literals:
insert into root.ln.wf02.wt02(timestamp,hardware) values(1, 'v1')
insert into root.ln.wf02.wt02(timestamp,hardware) values(2, '\\')
- # select data from root.ln.wf02.wt02, '\\' is unescpaed as '\'.
+-----------------------------+--------------------------+
| Time|root.ln.wf02.wt02.hardware|
+-----------------------------+--------------------------+
|1970-01-01T08:00:00.001+08:00| v1|
+-----------------------------+--------------------------+
- |1970-01-01T08:00:00.002+08:00| \|
+ |1970-01-01T08:00:00.002+08:00| \\|
+-----------------------------+--------------------------+
- # select
+ # select
select code from root.sg1.d1 where code in ('string1', 'string2');
```
-
-- Used in`LOAD` / `REMOVE` / `SETTLE` instructions to represent file path. File path will not be unescaped.
+
+- Used in`LOAD` / `REMOVE` / `SETTLE` instructions to represent file path.
```SQL
# load
@@ -77,7 +187,7 @@ Usages of string literals:
- Password fields in user management statements
```SQL
- # 'write_pwd' is a password
+ # write_pwd is the password
CREATE USER ln_write_user 'write_pwd'
```
@@ -98,7 +208,7 @@ Usages of string literals:
CREATE FUNCTION example AS 'org.apache.iotdb.udf.UDTFExample'
```
-- `AS` function provided by IoTDB can assign an alias to time series selected in query. Alias can be string or identifier.
+- `AS` function provided by IoTDB can assign an alias to time series selected in query. Alias can be constant(including string) or identifier.
```SQL
select s1 as 'temperature', s2 as 'speed' from root.ln.wf01.wt01;
@@ -109,67 +219,8 @@ Usages of string literals:
+-----------------------------+-----------|-----+
```
-- The key of an attribute can be String Literal and identifier, the value of an attribute can be Constant(including String Literal) and identifer. Using string literal to represent key and value is recommended.
-
- 1. Attributes fields of trigger. See the attributes after `With` clause in the example below:
-
- ```SQL
- # exmaple
- CREATE TRIGGER `alert-listener-sg1d1s1`
- AFTER INSERT
- ON root.sg1.d1.s1
- AS 'org.apache.iotdb.db.engine.trigger.example.AlertListener'
- WITH (
- 'lo' = '0',
- 'hi' = '100.0'
- )
- ```
-
- 2. Attributes fields of UDF. See the attributes in select clause in the example below:
-
- ```sql
- # 示例
- SELECT example(s1, s2, 'key1'='value1', 'key2'='value2') FROM root.sg.d1;
- ```
+- The key/value of an attribute can be String Literal and identifier, more details can be found at **key-value pair** part.
- 3. Key-value pair to represent tag/attributes in timeseries.
-
- ```SQL
- # create timeseries
- CREATE timeseries root.turbine.d1.s1(temprature)
- WITH datatype=FLOAT, encoding=RLE, compression=SNAPPY, 'max_point_number' = '5'
- TAGS('tag1' = 'v1', 'tag2'= 'v2') ATTRIBUTES('attr1' = 'v1', 'attr2' = 'v2')
-
- # alter tags and attributes of timeseries
- ALTER timeseries root.turbine.d1.s1 SET 'newTag1' = 'newV1', 'attr1' = 'newV1'
-
- # rename tag
- ALTER timeseries root.turbine.d1.s1 RENAME 'tag1' TO 'newTag1'
-
- # upsert alias, tags, attributes
- ALTER timeseries root.turbine.d1.s1 UPSERT
- ALIAS='newAlias' TAGS('tag2' = 'newV2', tag3=v3) ATTRIBUTES('attr3' ='v3', 'attr4'='v4')
-
- # add new tags
- ALTER timeseries root.turbine.d1.s1 ADD TAGS 'tag3' = 'v3', 'tag4' = 'v4'
-
- # add new attributes
- ALTER timeseries root.turbine.d1.s1 ADD ATTRIBUTES 'attr3' = 'v3', 'attr4' = 'v4'
-
- # query for timeseries
- SHOW timeseries root.ln.** WHRER 'unit' = 'c'
- ```
-
- 4. Attributes fields of Pipe and PipeSink.
-
- ```SQL
- # PipeSink example
- CREATE PIPESINK my_iotdb AS IoTDB ('ip' = 'your ip')
-
- # Pipe example
- CREATE PIPE my_pipe TO my_iotdb FROM
- (select ** from root WHERE time>=yyyy-mm-dd HH:MM:SS) WITH 'SyncDelOp' = 'true'
- ```
#### How to use quotation marks in String Literals
@@ -227,11 +278,11 @@ The `NULL` value means “no data.” `NULL` can be written in any lettercase.
## 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.
@@ -240,14 +291,14 @@ Below are basic constraints of identifiers, specific identifiers may have other
- ['\u2E80'..'\u9FFF'] (UNICODE Chinese characters)
- Identifiers may begin with a digit, unquoted identifiers can not consists of solely digits.
- Identifiers are case sensitive.
+- Key words can be used as an identifier.
-You need to quote the identifier with back quote(`) in the following cases:
+**You need to quote the identifier with back quote(`) in the following cases:**
- Identifier contains special characters.
-- Using Key words as identifier
- Identifier consists of solely digits.
-#### How to use quotations marks in quoted identifiers
+### How to use quotations marks in quoted identifiers
`'` and `"` can be used directly in quoted identifiers.
@@ -263,7 +314,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 ：
@@ -284,14 +335,14 @@ Examples of case in which quoted identifier is used ：
- UDF name should be quoted in cases described above ：
```sql
- # craete function named select, select is a keyword.
- CREATE FUNCTION `select` AS 'org.apache.iotdb.udf.UDTFExample'
+ # create a funciton named 111, 111 consists of solely digits.
+ CREATE FUNCTION `111` AS 'org.apache.iotdb.udf.UDTFExample'
```
- Template name should be quoted in cases described above ：
```sql
- # create template named 111, 111 consists of solely digits.
+ # create a template named 111, 111 consists of solely digits.
create schema template `111`
(temperature FLOAT encoding=RLE, status BOOLEAN encoding=PLAIN compression=SNAPPY)
```
@@ -302,8 +353,8 @@ Examples of case in which quoted identifier is used ：
# create user special`user.
CREATE USER `special``user.` 'write_pwd'
- # create role `select`
- CREATE ROLE `select`
+ # create role 111
+ CREATE ROLE `111`
```
- Continuous query name should be quoted in cases described above ：
@@ -330,7 +381,7 @@ Examples of case in which quoted identifier is used ：
(select ** from root WHERE time>=yyyy-mm-dd HH:MM:SS) WITH 'SyncDelOp' = 'true'
```
-- `AS` function provided by IoTDB can assign an alias to time series selected in query. Alias can be string or identifier.
+- `AS` function provided by IoTDB can assign an alias to time series selected in query. Alias can be constant(including string) or identifier.
```sql
select s1 as temperature, s2 as speed from root.ln.wf01.wt01;
@@ -341,33 +392,8 @@ Examples of case in which quoted identifier is used ：
+-----------------------------+-----------|-----+
```
-- The key of an attribute can be String Literal and identifier, the value of an attribute can be Constant(including String Literal) and identifer. Using string literal to represent key and value is recommended. Below are examples of using identifier in key-value of tags and attributes:
+- The key/value of an attribute can be String Literal and identifier, more details can be found at **key-value pair** part.
- ```SQL
- # create timeseries
- CREATE timeseries root.turbine.d1.s1(temprature)
- WITH datatype=FLOAT, encoding=RLE, compression=SNAPPY, max_point_number = 5
- TAGS(tag1 = v1, tag2 = v2) ATTRIBUTES(attr1 = v1, attr2 = v2)
-
- # alter tags and attributes of timeseries
- ALTER timeseries root.turbine.d1.s1 SET newTag1 = newV1, attr1 = newV1
-
- # rename tag
- ALTER timeseries root.turbine.d1.s1 RENAME tag1 TO newTag1
-
- # upsert alias, tags, attributes
- ALTER timeseries root.turbine.d1.s1 UPSERT
- ALIAS = newAlias TAGS(tag2 = newV2, tag3=v3) ATTRIBUTES(attr3 = v3, attr4 = v4)
-
- # add new tags
- ALTER timeseries root.turbine.d1.s1 ADD TAGS tag3 = v3, tag4 = v4
-
- # add new attributes
- ALTER timeseries root.turbine.d1.s1 ADD ATTRIBUTES attr3 = v3, attr4 = v4
-
- # query for timeseries
- SHOW timeseries root.ln.** WHRER unit = c
- ```
## Node Names in Path
@@ -382,7 +408,7 @@ Node name is a special identifier, it can also be wildcard `*` and `**`. When cr
As `*` can also be used in expressions of select clause to represent multiplication, below are examples to help you better understand the usage of `* `:
```SQL
-# create timeseries root.sg.a*b
+# create timeseries root.sg.`a*b`
create timeseries root.sg.`a*b` with datatype=FLOAT,encoding=PLAIN;
# As described in Identifier part, a*b should be quoted.
@@ -394,7 +420,7 @@ create timeseries root.sg.a with datatype=FLOAT,encoding=PLAIN;
# create timeseries root.sg.b
create timeseries root.sg.b with datatype=FLOAT,encoding=PLAIN;
-# query data of root.sg.a*b
+# query data of root.sg.`a*b`
select `a*b` from root.sg
# Header of result dataset
|Time|root.sg.a*b|
@@ -409,17 +435,12 @@ select a*b from root.sg
When node name is not wildcard, it is a identifier, which means the constraints on it is the same as described in Identifier part.
-Node name quoted with back quote will also be wrapped with back quote in result dataset if it contains . or `, otherwise node name will not be quoted in result dataset. Below are examples to help you understand
-
-- Create timeseries stament:
+- Create timeseries statement:
```SQL
# Node name contains special characters like ` and .,all nodes of this timeseries are: ["root","sg","www.`baidu.com"]
create timeseries root.sg.`www.``baidu.com`.a with datatype=FLOAT,encoding=PLAIN;
-# Node name is a key word.
-create timeseries root.sg.`select`.a with datatype=FLOAT,encoding=PLAIN;
-
# Node name consists of solely digits.
create timeseries root.sg.`111` with datatype=FLOAT,encoding=PLAIN;
```
@@ -430,8 +451,7 @@ After executing above statments, execute "show timeseries"，below is the result
+---------------------------+-----+-------------+--------+--------+-----------+----+----------+
| timeseries|alias|storage group|dataType|encoding|compression|tags|attributes|
+---------------------------+-----+-------------+--------+--------+-----------+----+----------+
-| root.sg.select.a| null| root.sg| FLOAT| PLAIN| SNAPPY|null| null|
-| root.sg.111.a| null| root.sg| FLOAT| PLAIN| SNAPPY|null| null|
+| root.sg.`111`.a| null| root.sg| FLOAT| PLAIN| SNAPPY|null| null|
|root.sg.`www.``baidu.com`.a| null| root.sg| FLOAT| PLAIN| SNAPPY|null| null|
+---------------------------+-----+-------------+--------+--------+-----------+----+----------+
```
@@ -442,9 +462,6 @@ After executing above statments, execute "show timeseries"，below is the result
# Node name contains special characters like . and `
insert into root.sg.`www.``baidu.com`(timestamp, a) values(1, 2);
-# Node name is a key word.
-insert into root.sg.`select`(timestamp, a) values (1, 2);
-
# Node name consists of solely digits.
insert into root.sg(timestamp, `111`) values (1, 2);
```
@@ -455,9 +472,6 @@ insert into root.sg(timestamp, `111`) values (1, 2);
# Node name contains special characters like . and `
select a from root.sg.`www.``baidu.com`;
-# Node name is a key word.
-select a from root.sg.`select`
-
# Node name consists of solely digits.
select `111` from root.sg
```
@@ -472,13 +486,6 @@ Results:
|1970-01-01T08:00:00.001+08:00| 2.0|
+-----------------------------+---------------------------+
-# select a from root.sg.`select`
-+-----------------------------+----------------+
-| Time|root.sg.select.a|
-+-----------------------------+----------------+
-|1970-01-01T08:00:00.001+08:00| 2.0|
-+-----------------------------+----------------+
-
# select `111` from root.sg
+-----------------------------+-----------+
| Time|root.sg.111|
@@ -487,12 +494,209 @@ Results:
+-----------------------------+-----------+
```
+## Key-Value Pair
+
+**The key/value of an attribute can be constant(including string) and identifier. **
+
+Below are usage scenarios of key-value pair:
+
+- Attributes fields of trigger. See the attributes after `With` clause in the example below:
+
+```SQL
+# 以字符串形式表示键值对
+CREATE TRIGGER `alert-listener-sg1d1s1`
+AFTER INSERT
+ON root.sg1.d1.s1
+AS 'org.apache.iotdb.db.engine.trigger.example.AlertListener'
+WITH (
+ 'lo' = '0',
+ 'hi' = '100.0'
+)
+
+# 以标识符和常量形式表示键值对
+CREATE TRIGGER `alert-listener-sg1d1s1`
+AFTER INSERT
+ON root.sg1.d1.s1
+AS 'org.apache.iotdb.db.engine.trigger.example.AlertListener'
+WITH (
+ lo = 0,
+ hi = 100.0
+)
+```
+
+- Key-value pair to represent tag/attributes in timeseries:
+
+```sql
+# create timeseries using string as key/value
+CREATE timeseries root.turbine.d1.s1(temprature)
+WITH datatype = FLOAT, encoding = RLE, compression = SNAPPY, 'max_point_number' = '5'
+TAGS('tag1' = 'v1', 'tag2'= 'v2') ATTRIBUTES('attr1' = 'v1', 'attr2' = 'v2')
+
+# create timeseries using constant as key/value
+CREATE timeseries root.turbine.d1.s1(temprature)
+WITH datatype = FLOAT, encoding = RLE, compression = SNAPPY, max_point_number = 5
+TAGS(tag1 = v1, tag2 = v2) ATTRIBUTES(attr1 = v1, attr2 = v2)
+```
+
+```sql
+# alter tags and attributes of timeseries
+ALTER timeseries root.turbine.d1.s1 SET 'newTag1' = 'newV1', 'attr1' = 'newV1'
+
+ALTER timeseries root.turbine.d1.s1 SET newTag1 = newV1, attr1 = newV1
+```
+
+```sql
+# rename tag
+ALTER timeseries root.turbine.d1.s1 RENAME 'tag1' TO 'newTag1'
+
+ALTER timeseries root.turbine.d1.s1 RENAME tag1 TO newTag1
+```
+
+```sql
+# upsert alias, tags, attributes
+ALTER timeseries root.turbine.d1.s1 UPSERT
+ALIAS='newAlias' TAGS('tag2' = 'newV2', 'tag3' = 'v3') ATTRIBUTES('attr3' ='v3', 'attr4'='v4')
+
+ALTER timeseries root.turbine.d1.s1 UPSERT
+ALIAS = newAlias TAGS(tag2 = newV2, tag3 = v3) ATTRIBUTES(attr3 = v3, attr4 = v4)
+```
+
+```sql
+# add new tags
+ALTER timeseries root.turbine.d1.s1 ADD TAGS 'tag3' = 'v3', 'tag4' = 'v4'
+
+ALTER timeseries root.turbine.d1.s1 ADD TAGS tag3 = v3, tag4 = v4
+```
+
+```sql
+# add new attributes
+ALTER timeseries root.turbine.d1.s1 ADD ATTRIBUTES 'attr3' = 'v3', 'attr4' = 'v4'
+
+ALTER timeseries root.turbine.d1.s1 ADD ATTRIBUTES attr3 = v3, attr4 = v4
+```
+
+```sql
+# query for timeseries
+SHOW timeseries root.ln.** WHRER 'unit' = 'c'
+
+SHOW timeseries root.ln.** WHRER unit = c
+```
+
+- Attributes fields of Pipe and PipeSink.
+
+```SQL
+# PipeSink example
+CREATE PIPESINK my_iotdb AS IoTDB ('ip' = '输入你的IP')
+
+# Pipe example
+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 are words that have significance in SQL require special treatment for use as identifiers and node names, and need to be escaped with backticks.
-Certain keywords, such as TIME and ROOT, are reserved and cannot use as identifiers and node names (even after escaping).
+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
+
+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.
+
+1. Take creating a time series createTimeseries as an example:
+
+```Java
+public void createTimeseries(
+ String path,
+ TSDataType dataType,
+ TSEncoding encoding,
+ CompressionType compressor)
+ throws IoTDBConnectionException, StatementExecutionException;
+```
+
+If you wish to create the time series root.sg.a, root.sg.\`a.\`\`"b\`, root.sg.\`111\`, the SQL statement you use should look like this:
+
+```SQL
+create timeseries root.sg.a with datatype=FLOAT,encoding=PLAIN,compressor=SNAPPY;
+
+# node names contain special characters, each node in the time series is ["root","sg","a.`\"b"]
+create timeseries root.sg.`a.``"b` with datatype=FLOAT,encoding=PLAIN,compressor=SNAPPY;
+
+# node names are pure numbers
+create timeseries root.sg.`111` with datatype=FLOAT,encoding=PLAIN,compressor=SNAPPY;
+```
+
+When you call the createTimeseries method, you should assign the path string as follows to ensure that the content of the path string is the same as when using SQL:
+
+```Java
+// timeseries root.sg.a
+String path = "root.sg.a";
+
+// timeseries root.sg.`a``"b`
+String path = "root.sg.`a``\"b`";
+
+// timeseries root.sg.`111`
+String path = "root.sg.`111`";
+```
+
+2. Take inserting data insertRecord as an example:
+
+```Java
+public void insertRecord(
+ String deviceId,
+ long time,
+ List<String> measurements,
+ List<TSDataType> types,
+ Object... values)
+ throws IoTDBConnectionException, StatementExecutionException;
+```
-[Keywords and Reserved Words](Keywords.md) shows the keywords and reserved words in IoTDB 0.13.
+If you want to insert data into the time series root.sg.a, root.sg.\`a.\`\`"b\`, root.sg.\`111\`, the SQL statement you use should be as follows:
+
+```SQL
+insert into root.sg(timestamp, a, `a.``"b`, `111`) values (1, 2, 2, 2);
+```
+
+When you call the insertRecord method, you should assign deviceId and measurements as follows:
+
+```Java
+// deviceId is root.sg
+String deviceId = "root.sg";
+
+// measurements
+String[] measurements = new String[]{"a", "`a.``\"b`", "`111`"};
+List<String> measurementList = Arrays.asList(measurements);
+```
+
+3. Take executeRawDataQuery as an example:
+
+```Java
+public SessionDataSet executeRawDataQuery(
+ List<String> paths,
+ long startTime,
+ long endTime)
+ throws StatementExecutionException, IoTDBConnectionException;
+```
+
+If you wish to query the data of the time series root.sg.a, root.sg.\`a.\`\`"b\`, root.sg.\`111\`, the SQL statement you use should be as follows :
+
+```SQL
+select a from root.sg
+
+# node name contains special characters
+select `a.``"b` from root.sg;
+
+# node names are pure numbers
+select `111` from root.sg
+```
+
+When you call the executeRawDataQuery method, you should assign paths as follows:
+
+```Java
+// paths
+String[] paths = new String[]{"root.sg.a", "root.sg.`a.``\"b`", "root.sg.`111`"};
+List<String> pathList = Arrays.asList(paths);
+```
## Learn More
diff --git a/docs/zh/UserGuide/Reference/Syntax-Conventions.md b/docs/zh/UserGuide/Reference/Syntax-Conventions.md
index a02c1fcd3f..de39e2c74d 100644
--- a/docs/zh/UserGuide/Reference/Syntax-Conventions.md
+++ b/docs/zh/UserGuide/Reference/Syntax-Conventions.md
@@ -21,23 +21,133 @@
# 语法约定
+## 旧语法约定中的问题
+
+在之前版本的语法约定中，为了保持兼容性，我们引入了一些会引起歧义的规定。为了避免歧义，我们设计了新的语法约定，本章将说明旧语法约定中存在的问题，以及我们做出改动的原因。
+
+### 路径名使用的相关问题
+
+在旧语法约定中，什么时候需要给路径结点名添加引号，用单双引号还是反引号的规则较为复杂，在新的语法约定中我们做了统一，具体可以参考本文档的相关章节。
+
+#### 单双引号和反引号的使用时机
+
+在之前的语法约定中，路径结点名被定义成标识符，但是当需要在路径结点名中使用路径分隔符 . 时，需要使用单引号或者双引号引用。这与标识符使用反引号引用的规则相悖。
+
+```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|
++-----------------------------+-----------+
+```
+
+在新语法约定中，特殊路径结点名统一使用反引号进行引用，在路径结点名中使用单双引号无须添加反斜杠转义，使用反引号需要双写，具体可以参考新语法约定路径结点名章节。
+
+### 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.
+
+MySQL 对字符串的定义可以参考：[MySQL :: MySQL 8.0 Reference Manual :: 9.1.1 String Literals](https://dev.mysql.com/doc/refman/8.0/en/string-literals.html)
+
+即在 IoTDB 中，字符串是由**单引号（**`**'**`**）或双引号（**`**"**`**）字符括起来的字符序列**。示例如下：
```Plain%20Text
'a string'
"another string"
```
-除文件路径以外，我们会对字符串常量做反转义处理，具体使用可以参考使用场景中的示例。
-
-转义字符可以参考链接：[Characters (The Java™ Tutorials > Learning the Java Language > Numbers and Strings)](https://docs.oracle.com/javase/tutorial/java/data/characters.html)
-
#### 使用场景
- `INSERT` 或者 `SELECT` 中用于表达 `TEXT` 类型数据的场景。
@@ -47,20 +157,19 @@
insert into root.ln.wf02.wt02(timestamp,hardware) values(1, 'v1')
insert into root.ln.wf02.wt02(timestamp,hardware) values(2, '\\')
- # 查询 root.ln.wf02.wt02的数据，结果如下，可以看到\\被转义为了\
+-----------------------------+--------------------------+
| Time|root.ln.wf02.wt02.hardware|
+-----------------------------+--------------------------+
|1970-01-01T08:00:00.001+08:00| v1|
+-----------------------------+--------------------------+
- |1970-01-01T08:00:00.002+08:00| \|
+ |1970-01-01T08:00:00.002+08:00| \\|
+-----------------------------+--------------------------+
# select 示例
select code from root.sg1.d1 where code in ('string1', 'string2');
```
-
-- `LOAD` / `REMOVE` / `SETTLE` 指令中的文件路径。由于windows系统使用反斜杠\作为路径分隔符，文件路径我们不会做反转义处理。
+
+- `LOAD` / `REMOVE` / `SETTLE` 指令中的文件路径。
```SQL
# load 示例
@@ -76,7 +185,7 @@
- 用户密码。
```SQL
- # 示例，'write_pwd'即为用户密码
+ # 示例，write_pwd 即为用户密码
CREATE USER ln_write_user 'write_pwd'
```
@@ -108,73 +217,13 @@
+-----------------------------+-----------|-----+
```
-- 用于表示键值对，键值对的键可以被定义成字符串或者标识符，键值对的值可以被定义成常量（包括字符串）或者标识符，更推荐将键值对表示为字符串。示例如下：
-
- 1. 触发器中表示触发器属性的键值对。参考示例语句中 WITH 后的属性键值对。
-
- ```SQL
- # 示例
- CREATE TRIGGER `alert-listener-sg1d1s1`
- AFTER INSERT
- ON root.sg1.d1.s1
- AS 'org.apache.iotdb.db.engine.trigger.example.AlertListener'
- WITH (
- 'lo' = '0',
- 'hi' = '100.0'
- )
- ```
-
- 2. UDF 中函数输入参数中的属性键值对。参考示例语句中 SELECT 子句中的属性键值对。
-
- ```SQL
- # 示例
- SELECT example(s1, s2, 'key1'='value1', 'key2'='value2') FROM root.sg.d1;
- ```
-
- 3. 时间序列中用于表示标签和属性的键值对。
-
- ```SQL
- # 创建时间序列时设定标签和属性
- CREATE timeseries root.turbine.d1.s1(temprature)
- WITH datatype=FLOAT, encoding=RLE, compression=SNAPPY, 'max_point_number' = '5'
- TAGS('tag1' = 'v1', 'tag2'= 'v2') ATTRIBUTES('attr1' = 'v1', 'attr2' = 'v2')
-
- # 修改时间序列的标签和属性
- ALTER timeseries root.turbine.d1.s1 SET 'newTag1' = 'newV1', 'attr1' = 'newV1'
-
- # 修改标签名
- ALTER timeseries root.turbine.d1.s1 RENAME 'tag1' TO 'newTag1'
-
- # 插入别名、标签、属性
- ALTER timeseries root.turbine.d1.s1 UPSERT
- ALIAS='newAlias' TAGS('tag2' = 'newV2', tag3=v3) ATTRIBUTES('attr3' ='v3', 'attr4'='v4')
-
- # 添加新的标签
- ALTER timeseries root.turbine.d1.s1 ADD TAGS 'tag3' = 'v3', 'tag4' = 'v4'
-
- # 添加新的属性
- ALTER timeseries root.turbine.d1.s1 ADD ATTRIBUTES 'attr3' = 'v3', 'attr4' = 'v4'
-
- # 查询符合条件的时间序列信息
- SHOW timeseries root.ln.** WHRER 'unit' = 'c'
- ```
-
- 4. 创建 Pipe 以及 PipeSink 时表示属性的键值对。
-
- ```SQL
- # 创建 PipeSink 时表示属性
- CREATE PIPESINK my_iotdb AS IoTDB ('ip' = '输入你的IP')
-
- # 创建 Pipe 时在 WITH 子句中表示属性
- CREATE PIPE my_pipe TO my_iotdb FROM
- (select ** from root WHERE time>=yyyy-mm-dd HH:MM:SS) WITH 'SyncDelOp' = 'true'
- ```
+- 用于表示键值对，键值对的键和值可以被定义成常量（包括字符串）或者标识符，具体请参考键值对章节。
#### 如何在字符串内使用引号
- 在单引号引起的字符串内，双引号无需特殊处理。同理，在双引号引起的字符串内，单引号无需特殊处理。
-- 在引号前使用转义符 (\)。
+- 在引号前使用转义符 (\\)。
- 在单引号引起的字符串里，可以通过双写单引号来表示一个单引号，即单引号 ' 可以表示为 ''。
@@ -228,44 +277,44 @@
### 使用场景
-在 IoTDB 中，触发器名称、UDF函数名、元数据模板名称、用户与角色名、连续查询标识、Pipe、PipeSink、键值对中的键和值、别名等被称为标识符。
+在 IoTDB 中，触发器名称、UDF函数名、元数据模板名称、用户与角色名、连续查询标识、Pipe、PipeSink、键值对中的键和值、别名等可以作为标识符。
### 约束
请注意，此处约束是标识符的通用约束，具体标识符可能还附带其它约束条件，如用户名限制字符数大于等于4，更严格的约束请参考具体标识符相关的说明文档。
-标识符命名有以下约束：
+**标识符命名有以下约束：**
- 不使用反引号括起的标识符中，允许出现以下字符：
-
- [ 0-9 a-z A-Z _ : @ # $ { } ] （字母，数字，部分特殊字符）
- - ['\u2E80'..'\u9FFF'] （UNICODE 中文字符）
+- ['\u2E80'..'\u9FFF'] （UNICODE 中文字符）
- 标识符允许使用数字开头、不使用反引号括起的标识符不能全部为数字。
- 标识符是大小写敏感的。
-如果出现如下情况，标识符需要使用反引号进行引用：
+- 标识符允许为关键字。
+
+**如果出现如下情况，标识符需要使用反引号进行引用：**
- 标识符包含不允许的特殊字符。
-- 标识符为系统关键字。
- 标识符为纯数字。
### 如何在反引号引起的标识符中使用引号
-在反引号引起的标识符中可以直接使用单引号和双引号。
+**在反引号引起的标识符中可以直接使用单引号和双引号。**
-在用反引号引用的标识符中，可以通过双写反引号的方式使用反引号，即 ` 可以表示为 ``，示例如下：
+**在用反引号引用的标识符中，可以通过双写反引号的方式使用反引号，即 ` 可以表示为 ``**，示例如下：
```SQL
-# 创建模板 t1't"t
-create schema template `t1't"t`
-(temperature FLOAT encoding=RLE, status BOOLEAN encoding=PLAIN compression=SNAPPY)
-
# 创建模板 t1`t
create schema template `t1``t`
(temperature FLOAT encoding=RLE, status BOOLEAN encoding=PLAIN compression=SNAPPY)
+
+# 创建模板 t1't"t
+create schema template `t1't"t`
+(temperature FLOAT encoding=RLE, status BOOLEAN encoding=PLAIN compression=SNAPPY)
```
### 特殊情况示例
@@ -289,14 +338,14 @@ create schema template `t1``t`
- UDF 名称出现上述特殊情况时需使用反引号引用：
```sql
- # 创建名为 select 的 UDF，select 为系统关键字，所以需要用反引号引用
- CREATE FUNCTION `select` AS 'org.apache.iotdb.udf.UDTFExample'
+ # 创建名为 111 的 UDF，111 为纯数字，所以需要用反引号引用。
+ CREATE FUNCTION `111` AS 'org.apache.iotdb.udf.UDTFExample'
```
- 元数据模板名称出现上述特殊情况时需使用反引号引用：
```sql
- # 创建名为 111 的元数据模板，111 为纯数字，需要用反引号引用
+ # 创建名为 111 的元数据模板，111 为纯数字，需要用反引号引用。
create schema template `111`
(temperature FLOAT encoding=RLE, status BOOLEAN encoding=PLAIN compression=SNAPPY)
```
@@ -307,8 +356,8 @@ create schema template `t1``t`
# 创建用户 special`user.
CREATE USER `special``user.` 'write_pwd'
- # 创建角色 `select`
- CREATE ROLE `select`
+ # 创建角色 111
+ CREATE ROLE `111`
```
- 连续查询标识出现上述特殊情况时需使用反引号引用：
@@ -340,38 +389,13 @@ create schema template `t1``t`
```sql
select s1 as temperature, s2 as speed from root.ln.wf01.wt01;
# 表头如下所示
- +-----------------------------+-----------|-----+
+ +-----------------------------+-----------+-----+
| Time|temperature|speed|
- +-----------------------------+-----------|-----+
+ +-----------------------------+-----------+-----+
```
-- 用于表示键值对，键值对的键可以被定义成字符串或者标识符，键值对的值可以被定义成常量（包括字符串）或者标识符，更推荐将键值对表示为字符串。键值对的使用范围和字符串常量中提到的一致，下面以时间序列中用于表示标签和属性的键值对作为示例：
+- 用于表示键值对，键值对的键和值可以被定义成常量（包括字符串）或者标识符，具体请参考键值对章节。
- ```SQL
- # 创建时间序列时设定标签和属性
- CREATE timeseries root.turbine.d1.s1(temprature)
- WITH datatype=FLOAT, encoding=RLE, compression=SNAPPY, max_point_number = 5
- TAGS(tag1 = v1, tag2= v2) ATTRIBUTES(attr1 = v1, attr2 = v2)
-
- # 修改时间序列的标签和属性
- ALTER timeseries root.turbine.d1.s1 SET newTag1 = newV1, attr1 = newV1
-
- # 修改标签名
- ALTER timeseries root.turbine.d1.s1 RENAME tag1 TO newTag1
-
- # 插入别名、标签、属性
- ALTER timeseries root.turbine.d1.s1 UPSERT
- ALIAS = newAlias TAGS(tag2 = newV2, tag3 = v3) ATTRIBUTES(attr3 = v3, attr4 = v4)
-
- # 添加新的标签
- ALTER timeseries root.turbine.d1.s1 ADD TAGS tag3 = v3, tag4 = v4
-
- # 添加新的属性
- ALTER timeseries root.turbine.d1.s1 ADD ATTRIBUTES attr3 = v3, attr4 = v4
-
- # 查询符合条件的时间序列信息
- SHOW timeseries root.ln.** WHRER unit = c
- ```
## 路径结点名
@@ -386,7 +410,7 @@ create schema template `t1``t`
由于通配符 * 在查询表达式中也可以表示乘法符号，下述例子用于帮助您区分两种情况：
```SQL
-# 创建时间序列 root.sg.a*b
+# 创建时间序列 root.sg.`a*b`
create timeseries root.sg.`a*b` with datatype=FLOAT,encoding=PLAIN;
# 请注意，如标识符部分所述，a*b包含特殊字符，需要用``括起来使用
# create timeseries root.sg.a*b with datatype=FLOAT,encoding=PLAIN 是错误用法
@@ -397,7 +421,7 @@ create timeseries root.sg.a with datatype=FLOAT,encoding=PLAIN;
# 创建时间序列 root.sg.b
create timeseries root.sg.b with datatype=FLOAT,encoding=PLAIN;
-# 查询时间序列 root.sg.a*b
+# 查询时间序列 root.sg.`a*b`
select `a*b` from root.sg
# 其结果集表头为
|Time|root.sg.a*b|
@@ -410,9 +434,7 @@ select a*b from root.sg
### 标识符
-路径结点名不为通配符时，使用方法和标识符一致。
-
-使用反引号引起的路径结点名，若其中含有特殊字符 . `，在结果集中展示时会添加反引号，其它情况下会正常展示，具体请参考特殊情况示例中结果集的示例。
+路径结点名不为通配符时，使用方法和标识符一致。**在 SQL 中需要使用反引号引用的路径结点，在结果集中也会用反引号引起。**
需要使用反引号进行引用的部分特殊情况示例：
@@ -422,9 +444,6 @@ select a*b from root.sg
# 路径结点名中包含特殊字符，时间序列各结点为["root","sg","www.`baidu.com"]
create timeseries root.sg.`www.``baidu.com`.a with datatype=FLOAT,encoding=PLAIN;
-# 路径结点名为系统关键字
-create timeseries root.sg.`select`.a with datatype=FLOAT,encoding=PLAIN;
-
# 路径结点名为纯数字
create timeseries root.sg.`111` with datatype=FLOAT,encoding=PLAIN;
```
@@ -435,8 +454,7 @@ create timeseries root.sg.`111` with datatype=FLOAT,encoding=PLAIN;
+---------------------------+-----+-------------+--------+--------+-----------+----+----------+
| timeseries|alias|storage group|dataType|encoding|compression|tags|attributes|
+---------------------------+-----+-------------+--------+--------+-----------+----+----------+
-| root.sg.select.a| null| root.sg| FLOAT| PLAIN| SNAPPY|null| null|
-| root.sg.111.a| null| root.sg| FLOAT| PLAIN| SNAPPY|null| null|
+| root.sg.`111`.a| null| root.sg| FLOAT| PLAIN| SNAPPY|null| null|
|root.sg.`www.``baidu.com`.a| null| root.sg| FLOAT| PLAIN| SNAPPY|null| null|
+---------------------------+-----+-------------+--------+--------+-----------+----+----------+
```
@@ -444,12 +462,9 @@ create timeseries root.sg.`111` with datatype=FLOAT,encoding=PLAIN;
- 插入数据时，如下情况需要使用反引号对特殊节点名进行引用：
```SQL
-# 路径结点名中包含特殊字符 . 和 `
+# 路径结点名中包含特殊字符
insert into root.sg.`www.``baidu.com`(timestamp, a) values(1, 2);
-# 路径结点名为系统关键字
-insert into root.sg.`select`(timestamp, a) values (1, 2);
-
# 路径结点名为纯数字
insert into root.sg(timestamp, `111`) values (1, 2);
```
@@ -457,12 +472,9 @@ insert into root.sg(timestamp, `111`) values (1, 2);
- 查询数据时，如下情况需要使用反引号对特殊节点名进行引用：
```SQL
-# 路径结点名中包含特殊字符 . 和 `
+# 路径结点名中包含特殊字符
select a from root.sg.`www.``baidu.com`;
-# 路径结点名为系统关键字
-select a from root.sg.`select`
-
# 路径结点名为纯数字
select `111` from root.sg
```
@@ -477,27 +489,218 @@ select `111` from root.sg
|1970-01-01T08:00:00.001+08:00| 2.0|
+-----------------------------+---------------------------+
-# select a from root.sg.`select` 结果集
-+-----------------------------+----------------+
-| Time|root.sg.select.a|
-+-----------------------------+----------------+
-|1970-01-01T08:00:00.001+08:00| 2.0|
-+-----------------------------+----------------+
-
# select `111` from root.sg 结果集
-+-----------------------------+-----------+
-| Time|root.sg.111|
-+-----------------------------+-----------+
-|1970-01-01T08:00:00.001+08:00| 2.0|
-+-----------------------------+-----------+
++-----------------------------+-------------+
+| Time|root.sg.`111`|
++-----------------------------+-------------+
+|1970-01-01T08:00:00.001+08:00| 2.0|
++-----------------------------+-------------+
+```
+
+## 键值对
+
+**键值对的键和值可以被定义为标识符或者常量。**
+
+下面将介绍键值对的使用场景。
+
+- 触发器中表示触发器属性的键值对。参考示例语句中 WITH 后的属性键值对。
+
+```SQL
+# 以字符串形式表示键值对
+CREATE TRIGGER `alert-listener-sg1d1s1`
+AFTER INSERT
+ON root.sg1.d1.s1
+AS 'org.apache.iotdb.db.engine.trigger.example.AlertListener'
+WITH (
+ 'lo' = '0',
+ 'hi' = '100.0'
+)
+
+# 以标识符和常量形式表示键值对
+CREATE TRIGGER `alert-listener-sg1d1s1`
+AFTER INSERT
+ON root.sg1.d1.s1
+AS 'org.apache.iotdb.db.engine.trigger.example.AlertListener'
+WITH (
+ lo = 0,
+ hi = 100.0
+)
+```
+
+- 时间序列中用于表示标签和属性的键值对。
+
+```sql
+# 创建时间序列时设定标签和属性，用字符串来表示键值对。
+CREATE timeseries root.turbine.d1.s1(temprature)
+WITH datatype = FLOAT, encoding = RLE, compression = SNAPPY, 'max_point_number' = '5'
+TAGS('tag1' = 'v1', 'tag2'= 'v2') ATTRIBUTES('attr1' = 'v1', 'attr2' = 'v2')
+
+# 创建时间序列时设定标签和属性，用标识符和常量来表示键值对。
+CREATE timeseries root.turbine.d1.s1(temprature)
+WITH datatype = FLOAT, encoding = RLE, compression = SNAPPY, max_point_number = 5
+TAGS(tag1 = v1, tag2 = v2) ATTRIBUTES(attr1 = v1, attr2 = v2)
+```
+
+```sql
+# 修改时间序列的标签和属性
+ALTER timeseries root.turbine.d1.s1 SET 'newTag1' = 'newV1', 'attr1' = 'newV1'
+
+ALTER timeseries root.turbine.d1.s1 SET newTag1 = newV1, attr1 = newV1
+```
+
+```sql
+# 修改标签名
+ALTER timeseries root.turbine.d1.s1 RENAME 'tag1' TO 'newTag1'
+
+ALTER timeseries root.turbine.d1.s1 RENAME tag1 TO newTag1
+```
+
+```sql
+# 插入别名、标签、属性
+ALTER timeseries root.turbine.d1.s1 UPSERT
+ALIAS='newAlias' TAGS('tag2' = 'newV2', 'tag3' = 'v3') ATTRIBUTES('attr3' ='v3', 'attr4'='v4')
+
+ALTER timeseries root.turbine.d1.s1 UPSERT
+ALIAS = newAlias TAGS(tag2 = newV2, tag3 = v3) ATTRIBUTES(attr3 = v3, attr4 = v4)
+```
+
+```sql
+# 添加新的标签
+ALTER timeseries root.turbine.d1.s1 ADD TAGS 'tag3' = 'v3', 'tag4' = 'v4'
+
+ALTER timeseries root.turbine.d1.s1 ADD TAGS tag3 = v3, tag4 = v4
+```
+
+```sql
+# 添加新的属性
+ALTER timeseries root.turbine.d1.s1 ADD ATTRIBUTES 'attr3' = 'v3', 'attr4' = 'v4'
+
+ALTER timeseries root.turbine.d1.s1 ADD ATTRIBUTES attr3 = v3, attr4 = v4
+```
+
+```sql
+# 查询符合条件的时间序列信息
+SHOW timeseries root.ln.** WHRER 'unit' = 'c'
+
+SHOW timeseries root.ln.** WHRER unit = c
+```
+
+- 创建 Pipe 以及 PipeSink 时表示属性的键值对。
+
+```SQL
+# 创建 PipeSink 时表示属性
+CREATE PIPESINK my_iotdb AS IoTDB ('ip' = '输入你的IP')
+
+# 创建 Pipe 时在 WITH 子句中表示属性
+CREATE PIPE my_pipe TO my_iotdb FROM
+(select ** from root WHERE time>=yyyy-mm-dd HH:MM:SS) WITH 'SyncDelOp' = 'true'
```
## 关键字和保留字
-关键字是在 SQL 具有特定含义的词，不能直接用于标识符，需要使用反引号进行转义。保留字是关键字的一个子集，保留字不能用于标识符（即使进行了转义）。
+关键字是在 SQL 具有特定含义的词，可以作为标识符。保留字是关键字的一个子集，保留字不能用于标识符。
关于 IoTDB 的关键字和保留字列表，可以查看 [关键字和保留字](https://iotdb.apache.org/zh/UserGuide/Master/Reference/Keywords.html) 。
+## Session、TsFile API
+
+在使用Session、TsFIle API时，如果您调用的方法需要以字符串形式传入物理量（measurement）、设备（device）、存储组（storage group）、路径（path）等参数，**请保证所传入字符串与使用 SQL 语句时的写法一致**，下面是一些帮助您理解的例子。
+
+1. 以创建时间序列 createTimeseries 为例：
+
+```Java
+public void createTimeseries(
+ String path,
+ TSDataType dataType,
+ TSEncoding encoding,
+ CompressionType compressor)
+ throws IoTDBConnectionException, StatementExecutionException;
+```
+
+如果您希望创建时间序列 root.sg.a，root.sg.\`a.\`\`"b\`，root.sg.\`111\`，您使用的 SQL 语句应该如下所示：
+
+```SQL
+create timeseries root.sg.a with datatype=FLOAT,encoding=PLAIN,compressor=SNAPPY;
+
+# 路径结点名中包含特殊字符，时间序列各结点为["root","sg","a.`\"b"]
+create timeseries root.sg.`a.``"b` with datatype=FLOAT,encoding=PLAIN,compressor=SNAPPY;
+
+# 路径结点名为纯数字
+create timeseries root.sg.`111` with datatype=FLOAT,encoding=PLAIN,compressor=SNAPPY;
+```
+
+您在调用 createTimeseries 方法时，应该按照如下方法赋值 path 字符串，保证 path 字符串内容与使用 SQL 时一致：
+
+```Java
+// 时间序列 root.sg.a
+String path = "root.sg.a";
+
+// 时间序列 root.sg.`a``"b`
+String path = "root.sg.`a``\"b`";
+
+// 时间序列 root.sg.`111`
+String path = "root.sg.`111`";
+```
+
+2. 以插入数据 insertRecord 为例：
+
+```Java
+public void insertRecord(
+ String deviceId,
+ long time,
+ List<String> measurements,
+ List<TSDataType> types,
+ Object... values)
+ throws IoTDBConnectionException, StatementExecutionException;
+```
+
+如果您希望向时间序列 root.sg.a，root.sg.\`a.\`\`"b\`，root.sg.\`111\`中插入数据，您使用的 SQL 语句应该如下所示：
+
+```SQL
+insert into root.sg(timestamp, a, `a.``"b`, `111`) values (1, 2, 2, 2);
+```
+
+您在调用 insertRecord 方法时，应该按照如下方法赋值 deviceId 和 measurements：
+
+```Java
+// deviceId 为 root.sg
+String deviceId = "root.sg";
+
+// measurements
+String[] measurements = new String[]{"a", "`a.``\"b`", "`111`"};
+List<String> measurementList = Arrays.asList(measurements);
+```
+
+3. 以查询数据 executeRawDataQuery 为例：
+
+```Java
+public SessionDataSet executeRawDataQuery(
+ List<String> paths,
+ long startTime,
+ long endTime)
+ throws StatementExecutionException, IoTDBConnectionException;
+```
+
+如果您希望查询时间序列 root.sg.a，root.sg.\`a.\`\`"b\`，root.sg.\`111\`的数据，您使用的 SQL 语句应该如下所示：
+
+```SQL
+select a from root.sg
+
+# 路径结点名中包含特殊字符
+select `a.``"b` from root.sg;
+
+# 路径结点名为纯数字
+select `111` from root.sg
+```
+
+您在调用 executeRawDataQuery 方法时，应该按照如下方法赋值 paths：
+
+```Java
+// paths
+String[] paths = new String[]{"root.sg.a", "root.sg.`a.``\"b`", "root.sg.`111`"};
+List<String> pathList = Arrays.asList(paths);
+```
+
## 了解更多
请阅读代码仓库中的词法和语法描述文件：