You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iotdb.apache.org by xu...@apache.org on 2021/04/08 02:25:54 UTC
[iotdb] 01/01: add doc
This is an automated email from the ASF dual-hosted git repository.
xuekaifeng pushed a commit to branch add-device-template-doc-to-vector
in repository https://gitbox.apache.org/repos/asf/iotdb.git
commit 47c45a94d45a42fe317eb970980fc6d633f91835
Author: 151250176 <15...@smail.nju.edu.cn>
AuthorDate: Thu Apr 8 10:24:44 2021 +0800
add doc
---
docs/UserGuide/API/Programming-Native-API.md | 41 +-
.../DDL-Data-Definition-Language.md | 304 ++++++++------
docs/zh/UserGuide/API/Programming-Native-API.md | 30 ++
.../UserGuide/Client/Programming - Native API.md | 457 +++++++++++++++++++++
.../DDL-Data-Definition-Language.md | 27 ++
.../java/org/apache/iotdb/session/Session.java | 41 +-
6 files changed, 757 insertions(+), 143 deletions(-)
diff --git a/docs/UserGuide/API/Programming-Native-API.md b/docs/UserGuide/API/Programming-Native-API.md
index ab763d7..cb2e29d 100644
--- a/docs/UserGuide/API/Programming-Native-API.md
+++ b/docs/UserGuide/API/Programming-Native-API.md
@@ -224,6 +224,8 @@ To get more information of the following interfaces, please view session/src/mai
The sample code of using these interfaces is in example/session/src/main/java/org/apache/iotdb/SessionExample.java，which provides an example of how to open an IoTDB session, execute a batch insertion.
+For device template and vector using example, you can refer to example/session/src/main/java/org/apache/iotdb/VectorSessionExample.java
+
### Session Pool for Native API
@@ -332,4 +334,41 @@ public Session(String host, int rpcPort, String username, String password,
boolean isEnableCacheLeader)
```
-Open a session and specifies whether the Leader cache is enabled. Note that this interface improves performance for distributed IoTDB, but adds less cost to the client for stand-alone IoTDB.
\ No newline at end of file
+Open a session and specifies whether the Leader cache is enabled. Note that this interface improves performance for distributed IoTDB, but adds less cost to the client for stand-alone IoTDB.
+
+```
+
+* name: template name
+* measurements: List of measurements, if it is a single measurement, just put it's name
+* into a list and add to measurements if it is a vector measurement, put all measurements of
+* the vector into a list and add to measurements
+* dataTypes: List of datatypes, if it is a single measurement, just put it's type into a
+* list and add to dataTypes if it is a vector measurement, put all types of the vector
+* into a list and add to dataTypes
+* encodings: List of encodings, if it is a single measurement, just put it's encoding into
+* a list and add to encodings if it is a vector measurement, put all encodings of the
+* vector into a list and add to encodings
+* compressors: List of compressors
+void createDeviceTemplate(
+ String name,
+ List<List<String>> measurements,
+ List<List<TSDataType>> dataTypes,
+ List<List<TSEncoding>> encodings,
+ List<CompressionType> compressors)
+```
+
+Create a device template, the param description at above
+
+```
+
+void setDeviceTemplate(String templateName, String prefixPath)
+
+```
+
+Set the device template named 'templateName' at path 'prefixPath'. You should firstly create the template using
+
+```
+
+void createDeviceTemplate
+
+```
\ No newline at end of file
diff --git a/docs/UserGuide/IoTDB-SQL-Language/DDL-Data-Definition-Language.md b/docs/UserGuide/IoTDB-SQL-Language/DDL-Data-Definition-Language.md
index c91cc25..0c43702 100644
--- a/docs/UserGuide/IoTDB-SQL-Language/DDL-Data-Definition-Language.md
+++ b/docs/UserGuide/IoTDB-SQL-Language/DDL-Data-Definition-Language.md
@@ -19,12 +19,9 @@
-->
-# IoTDB-SQL Language
+# DDL (Data Definition Language)
-## Data Definition Language (DDL)
-
-### Stroage Group Management
-#### Create Storage Group
+## Create Storage Group
According to the storage model we can set up the corresponding storage group. The SQL statements for creating storage groups are as follows:
@@ -39,15 +36,15 @@ It is worth noting that when the path itself or the parent/child layer of the pa
```
IoTDB> set storage group to root.ln.wf01
-Msg: 300: root.ln has already been set to storage group.
+Msg: org.apache.iotdb.exception.MetadataException: org.apache.iotdb.exception.MetadataException: The prefix of root.ln.wf01 has been set to the storage group.
```
The LayerName of storage group can only be characters, numbers and underscores.
Besides, if deploy on Windows system, the LayerName is case-insensitive, which means it's not allowed to set storage groups `root.ln` and `root.LN` at the same time.
-#### Show Storage Group
+## Show Storage Group
-After creating the storage group, we can use the [SHOW STORAGE GROUP](../Appendix/SQL-Reference.md) statement and [SHOW STORAGE GROUP \<PrefixPath>](../Appendix/SQL-Reference.md) to view the storage groups. The SQL statements are as follows:
+After creating the storage group, we can use the [SHOW STORAGE GROUP](../Operation%20Manual/SQL%20Reference.md) statement and [SHOW STORAGE GROUP \<PrefixPath>](../Operation%20Manual/SQL%20Reference.md) to view the storage groups. The SQL statements are as follows:
```
IoTDB> show storage group
@@ -67,7 +64,7 @@ Total line number = 2
It costs 0.060s
```
-#### Delete Storage Group
+## Delete Storage Group
User can use the `DELETE STORAGE GROUP <PrefixPath>` statement to delete all storage groups under the prefixPath. Please note the data in the storage group will also be deleted.
@@ -77,8 +74,8 @@ IoTDB > DELETE STORAGE GROUP root.sgcc
// delete all data, all timeseries and all storage groups
IoTDB > DELETE STORAGE GROUP root.*
```
-### Timeseries Management
-#### Create Timeseries
+
+## Create Timeseries
According to the storage model selected before, we can create corresponding timeseries in the two storage groups respectively. The SQL statements for creating timeseries are as follows:
@@ -98,21 +95,72 @@ IoTDB> create timeseries root.ln.wf02.wt02.status WITH DATATYPE=BOOLEAN, ENCODIN
error: encoding TS_2DIFF does not support BOOLEAN
```
-Please refer to [Encoding](../Data-Concept/Encoding.md) for correspondence between data type and encoding.
+Please refer to [Encoding](../Concept/Encoding.md) for correspondence between data type and encoding.
-#### Delete Timeseries
+### Create and set device template
+```
-To delete the timeseries we created before, we are able to use `DELETE TimeSeries <PrefixPath>` statement.
+IoTDB > set storage group root.beijing
-The usage are as follows:
+// create a device templat
+IoTDB > create device template temp1(
+ (s1 INT32 with encoding=Gorilla, compression=SNAPPY),
+ (s2 FLOAT with encoding=RLE, compression=SNAPPY)
+ )
+
+// set device template to storage group "root.beijing"
+IoTDB > set device template temp1 to root.beijing
```
-IoTDB> delete timeseries root.ln.wf01.wt01.status
-IoTDB> delete timeseries root.ln.wf01.wt01.temperature, root.ln.wf02.wt02.hardware
-IoTDB> delete timeseries root.ln.wf02.*
+
+### Tag and attribute management
+
+We can also add an alias, extra tag and attribute information while creating one timeseries.
+The SQL statements for creating timeseries with extra tag and attribute information are extended as follows:
+
```
+create timeseries root.turbine.d1.s1(temprature) with datatype=FLOAT, encoding=RLE, compression=SNAPPY tags(tag1=v1, tag2=v2) attributes(attr1=v1, attr2=v2)
+```
+
+The `temprature` in the brackets is an alias for the sensor `s1`. So we can use `temprature` to replace `s1` anywhere.
+
+> IoTDB also supports [using AS function](../Operation%20Manual/DML%20Data%20Manipulation%20Language.md) to set alias. The difference between the two is: the alias set by the AS function is used to replace the whole time series name, temporary and not bound with the time series; while the alias mentioned above is only used as the alias of the sensor, which is bound with it and can be used equivalent to the original sensor name.
+
+The only difference between tag and attribute is that we will maintain an inverted index on the tag, so we can use tag property in the show timeseries where clause which you can see in the following `Show Timeseries` section.
+
+> Notice that the size of the extra tag and attribute information shouldn't exceed the `tag_attribute_total_size`.
+
-#### Show Timeseries
+## UPDATE TAG OPERATION
+We can update the tag information after creating it as following:
+
+* Rename the tag/attribute key
+```
+ALTER timeseries root.turbine.d1.s1 RENAME tag1 TO newTag1
+```
+* reset the tag/attribute value
+```
+ALTER timeseries root.turbine.d1.s1 SET newTag1=newV1, attr1=newV1
+```
+* delete the existing tag/attribute
+```
+ALTER timeseries root.turbine.d1.s1 DROP tag1, tag2
+```
+* 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
+```
+* upsert alias, tags and attributes
+> add alias or a new key-value if the alias or key doesn't exist, otherwise, update the old one with new value.
+```
+ALTER timeseries root.turbine.d1.s1 UPSERT ALIAS=newAlias TAGS(tag3=v3, tag4=v4) ATTRIBUTES(attr3=v3, attr4=v4)
+```
+
+## Show Timeseries
* SHOW LATEST? TIMESERIES prefixPath? showWhereClause? limitClause?
@@ -207,8 +255,63 @@ It costs 0.004s
It is worth noting that when the queried path does not exist, the system will return no timeseries.
+## Show Child Paths
+
+```
+SHOW CHILD PATHS prefixPath
+```
+
+Return all child paths of the prefixPath, the prefixPath could contains *.
+
+Example：
+
+* return the child paths of root.ln：show child paths root.ln
-#### Count Timeseries
+```
++------------+
+| child paths|
++------------+
+|root.ln.wf01|
+|root.ln.wf02|
++------------+
+Total line number = 2
+It costs 0.002s
+```
+
+> get all paths in form of root.xx.xx.xx：show child paths root.xx.xx
+
+## Show Child Nodes
+
+```
+SHOW CHILD NODES prefixPath
+```
+
+Return all child nodes of the prefixPath.
+
+Example：
+
+* return the child nodes of root：show child paths root
+
+```
++------------+
+| child nodes|
++------------+
+| ln|
++------------+
+```
+
+* return the child nodes of root.vehicle：show child paths root.ln
+
+```
++------------+
+| child nodes|
++------------+
+| wf01|
+| wf02|
++------------+
+```
+
+## Count Timeseries
IoTDB is able to use `COUNT TIMESERIES <Path>` to count the number of timeseries in the path. SQL statements are as follows:
@@ -284,109 +387,7 @@ It costs 0.002s
> Note: The path of timeseries is just a filter condition, which has no relationship with the definition of level.
-#### Tag and attribute management
-
-We can also add an alias, extra tag and attribute information while creating one timeseries.
-The SQL statements for creating timeseries with extra tag and attribute information are extended as follows:
-
-```
-create timeseries root.turbine.d1.s1(temprature) with datatype=FLOAT, encoding=RLE, compression=SNAPPY tags(tag1=v1, tag2=v2) attributes(attr1=v1, attr2=v2)
-```
-
-The `temprature` in the brackets is an alias for the sensor `s1`. So we can use `temprature` to replace `s1` anywhere.
-
-> IoTDB also supports [using AS function](../Appendix/DML-Data-Manipulation-Language.md) to set alias. The difference between the two is: the alias set by the AS function is used to replace the whole time series name, temporary and not bound with the time series; while the alias mentioned above is only used as the alias of the sensor, which is bound with it and can be used equivalent to the original sensor name.
-
-The only difference between tag and attribute is that we will maintain an inverted index on the tag, so we can use tag property in the show timeseries where clause which you can see in the following `Show Timeseries` section.
-
-> Notice that the size of the extra tag and attribute information shouldn't exceed the `tag_attribute_total_size`.
-
-We can update the tag information after creating it as following:
-
-* Rename the tag/attribute key
-```
-ALTER timeseries root.turbine.d1.s1 RENAME tag1 TO newTag1
-```
-* reset the tag/attribute value
-```
-ALTER timeseries root.turbine.d1.s1 SET newTag1=newV1, attr1=newV1
-```
-* delete the existing tag/attribute
-```
-ALTER timeseries root.turbine.d1.s1 DROP tag1, tag2
-```
-* 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
-```
-* upsert alias, tags and attributes
-> add alias or a new key-value if the alias or key doesn't exist, otherwise, update the old one with new value.
-```
-ALTER timeseries root.turbine.d1.s1 UPSERT ALIAS=newAlias TAGS(tag3=v3, tag4=v4) ATTRIBUTES(attr3=v3, attr4=v4)
-```
-
-### Node Management
-#### Show Child Paths
-
-```
-SHOW CHILD PATHS prefixPath
-```
-
-Return all child paths of the prefixPath, the prefixPath could contains *.
-
-Example：
-
-* return the child paths of root.ln：show child paths root.ln
-
-```
-+------------+
-| child paths|
-+------------+
-|root.ln.wf01|
-|root.ln.wf02|
-+------------+
-Total line number = 2
-It costs 0.002s
-```
-
-> get all paths in form of root.xx.xx.xx：show child paths root.xx.xx
-
-#### Show Child Nodes
-
-```
-SHOW CHILD NODES prefixPath
-```
-
-Return all child nodes of the prefixPath.
-
-Example：
-
-* return the child nodes of root：show child nodes root
-
-```
-+------------+
-| child nodes|
-+------------+
-| ln|
-+------------+
-```
-
-* return the child nodes of root.vehicle：show child nodes root.ln
-
-```
-+------------+
-| child nodes|
-+------------+
-| wf01|
-| wf02|
-+------------+
-```
-
-#### Count Nodes
+## Count Nodes
IoTDB is able to use `COUNT NODES <PrefixPath> LEVEL=<INTEGER>` to count the number of nodes at the given level in current Metadata Tree. This could be used to query the number of devices. The usage are as follows:
@@ -427,7 +428,19 @@ It costs 0.002s
> Note: The path of timeseries is just a filter condition, which has no relationship with the definition of level.
`PrefixPath` could contains `*`, but all nodes after `*` would be ignored. Only the prefix path before `*` is valid.
-#### Show Devices
+## Delete Timeseries
+
+To delete the timeseries we created before, we are able to use `DELETE TimeSeries <PrefixPath>` statement.
+
+The usage are as follows:
+
+```
+IoTDB> delete timeseries root.ln.wf01.wt01.status
+IoTDB> delete timeseries root.ln.wf01.wt01.temperature, root.ln.wf02.wt02.hardware
+IoTDB> delete timeseries root.ln.wf02.*
+```
+
+## Show Devices
* SHOW DEVICES prefixPath? (WITH STORAGE GROUP)? limitClause? #showDevices
@@ -504,11 +517,11 @@ Total line number = 2
It costs 0.001s
```
-### TTL
+# TTL
IoTDB supports storage-level TTL settings, which means it is able to delete old data automatically and periodically. The benefit of using TTL is that hopefully you can control the total disk space usage and prevent the machine from running out of disks. Moreover, the query performance may downgrade as the total number of files goes up and the memory usage also increase as there are more files. Timely removing such files helps to keep at a high query performance level and reduce memory usage.
-#### Set TTL
+## Set TTL
The SQL Statement for setting TTL is as follow:
@@ -518,7 +531,7 @@ IoTDB> set ttl to root.ln 3600000
This example means that for data in `root.ln`, only that of the latest 1 hour will remain, the older one is removed or made invisible.
-#### Unset TTL
+## Unset TTL
To unset TTL, we can use follwing SQL statement:
@@ -528,7 +541,7 @@ IoTDB> unset ttl to root.ln
After unset TTL, all data will be accepted in `root.ln`
-#### Show TTL
+## Show TTL
To Show TTL, we can use following SQL statement:
@@ -542,3 +555,38 @@ The SHOW TTL ON root.group1 , root.group2 , root.group3 example shows the TTL f
groups specified.
Note: the TTL for storage groups that do not have a TTL set will display as null.
+## FLUSH
+
+Persist all the data points in the memory table of the storage group to the disk, and seal the data file.
+
+```
+IoTDB> FLUSH
+IoTDB> FLUSH root.ln
+IoTDB> FLUSH root.sg1,root.sg2
+```
+
+## MERGE
+
+Merge sequence and unsequence data. Currently IoTDB supports the following two types of SQL to manually trigger the merge process of data files:
+
+* `MERGE` Only rewrite overlapped Chunks, the merge speed is quick, while there will be redundant data on the disk eventually.
+* `FULL MERGE` Rewrite all data in overlapped files, the merge speed is slow, but there will be no redundant data on the disk eventually.
+
+```
+IoTDB> MERGE
+IoTDB> FULL MERGE
+```
+
+## CLEAR CACHE
+
+Clear the cache of chunk, chunk metadata and timeseries metadata to release the memory footprint.
+```
+IoTDB> CLEAR CACHE
+```
+
+## CREATE SNAPSHOT FOR SCHEMA
+
+To speed up restarting of IoTDB, users can create snapshot of schema and avoid recovering schema from mlog file.
+```
+IoTDB> CREATE SNAPSHOT FOR SCHEMA
+```
diff --git a/docs/zh/UserGuide/API/Programming-Native-API.md b/docs/zh/UserGuide/API/Programming-Native-API.md
index 8f5198e..bdbf416 100644
--- a/docs/zh/UserGuide/API/Programming-Native-API.md
+++ b/docs/zh/UserGuide/API/Programming-Native-API.md
@@ -210,6 +210,31 @@ void testInsertRecord(String deviceId, long time, List<String> measurements,
void testInsertTablet(Tablet tablet)
```
+* 创建一个设备模板
+```
+* name: 设备模板名称
+* measurements: 工况名称列表，如果该工况是非对齐的，直接将其名称放入一个list中再放入measurements中，
+* 如果该工况是对齐的，将所有对齐工况名称放入一个list再放入measurements中
+* dataTypes: 数据类型名称列表，如果该工况是非对齐的，直接将其数据类型放入一个list中再放入dataTypes中，
+ 如果该工况是对齐的，将所有对齐工况的数据类型放入一个list再放入dataTypes中
+* encodings: 编码类型名称列表，如果该工况是非对齐的，直接将其数据类型放入一个list中再放入encodings中，
+ 如果该工况是对齐的，将所有对齐工况的编码类型放入一个list再放入encodings中
+* compressors: 压缩方式列表
+void createDeviceTemplate(
+ String name,
+ List<List<String>> measurements,
+ List<List<TSDataType>> dataTypes,
+ List<List<TSEncoding>> encodings,
+ List<CompressionType> compressors)
+```
+* 将名为'templateName'的设备模板挂载到'prefixPath'路径下，在执行这一步之前，你需要创建名为'templateName'的设备模板
+
+```
+void setDeviceTemplate(String templateName, String prefixPath)
+```
+
+
+
### 针对原生接口的连接池
我们提供了一个针对原生接口的连接池(`SessionPool`)，使用该接口时，你只需要指定连接池的大小，就可以在使用时从池中获取连接。
@@ -236,3 +261,8 @@ void testInsertTablet(Tablet tablet)
使用上述接口的示例代码在 ```example/session/src/main/java/org/apache/iotdb/SessionExample.java```
+有关对其时间序列和设备模板的实例代码在 ```example/session/src/main/java/org/apache/iotdb/VectorSessionExample.java```
+
+
+开启一个session，并指定是否启用leader缓存。注意此接口对于分布式写入能够提高性能，但对于单机版写入反而会给客户端增加较少的消耗。
+
diff --git a/docs/zh/UserGuide/Client/Programming - Native API.md b/docs/zh/UserGuide/Client/Programming - Native API.md
new file mode 100644
index 0000000..8c39376
--- /dev/null
+++ b/docs/zh/UserGuide/Client/Programming - Native API.md
@@ -0,0 +1,457 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+# 编程 - 原生接口
+
+## 依赖
+
+* JDK >= 1.8
+* Maven >= 3.6
+
+## 安装到本地 maven 库
+
+在根目录下运行:
+> mvn clean install -pl session -am -Dmaven.test.skip=true
+
+## 在 maven 中使用原生接口
+
+```
+<dependencies>
+ <dependency>
+ <groupId>org.apache.iotdb</groupId>
+ <artifactId>iotdb-session</artifactId>
+ <version>0.10.0</version>
+ </dependency>
+</dependencies>
+```
+
+## 原生接口使用示例
+
+下面将给出Session对应的接口的简要介绍和对应参数：
+
+* 初始化Session
+
+ ```
+ Session(String host, int rpcPort)
+ Session(String host, String rpcPort, String username, String password)
+ Session(String host, int rpcPort, String username, String password)
+ ```
+
+* 开启Session
+
+ ```
+ Session.open()
+ ```
+
+* 关闭Session
+
+ ```
+ Session.close()
+ ```
+
+* 设置存储组
+
+ ```
+ void setStorageGroup(String storageGroupId)
+ ```
+
+* 删除单个或多个存储组
+
+ ```
+ void deleteStorageGroup(String storageGroup)
+ void deleteStorageGroups(List<String> storageGroups)
+ ```
+
+* 创建单个或多个时间序列
+
+ ```
+ void createTimeseries(String path, TSDataType dataType,
+ TSEncoding encoding, CompressionType compressor, Map<String, String> props,
+ Map<String, String> tags, Map<String, String> attributes, String measurementAlias)
+
+ void createMultiTimeseries(List<String> paths, List<TSDataType> dataTypes,
+ List<TSEncoding> encodings, List<CompressionType> compressors,
+ List<Map<String, String>> propsList, List<Map<String, String>> tagsList,
+ List<Map<String, String>> attributesList, List<String> measurementAliasList)
+ ```
+
+* 删除一个或多个时间序列
+
+ ```
+ void deleteTimeseries(String path)
+ void deleteTimeseries(List<String> paths)
+ ```
+
+* 删除一个或多个时间序列在某个时间点前的数据
+
+ ```
+ void deleteData(String path, long time)
+ void deleteData(List<String> paths, long time)
+ ```
+
+* 插入一个 Record，一个 Record 是一个设备一个时间戳下多个测点的数据。服务器需要做类型推断，可能会有额外耗时
+
+ ```
+ void insertRecord(String deviceId, long time, List<String> measurements, List<String> values)
+ ```
+
+* 插入一个 Tablet，Tablet 是一个设备若干行非空数据块，每一行的列都相同
+
+ ```
+ void insertTablet(Tablet tablet)
+ ```
+
+* 插入多个 Tablet
+
+ ```
+ void insertTablets(Map<String, Tablet> tablet)
+ ```
+
+* 插入多个 Record。服务器需要做类型推断，可能会有额外耗时
+
+ ```
+ void insertRecords(List<String> deviceIds, List<Long> times,
+ List<List<String>> measurementsList, List<List<String>> valuesList)
+ ```
+
+* 插入一个 Record，一个 Record 是一个设备一个时间戳下多个测点的数据。提供数据类型后，服务器不需要做类型推断，可以提高性能
+
+ ```
+ void insertRecord(String deviceId, long time, List<String> measurements,
+ List<TSDataType> types, List<Object> values)
+ ```
+
+* 插入多个 Record。提供数据类型后，服务器不需要做类型推断，可以提高性能
+
+ ```
+ void insertRecords(List<String> deviceIds, List<Long> times,
+ List<List<String>> measurementsList, List<List<TSDataType>> typesList,
+ List<List<Object>> valuesList)
+ ```
+
+* 插入同属于一个device的多个 Record。
+
+ ```
+ void insertRecordsOfOneDevice(String deviceId, List<Long> times,
+ List<List<String>> measurementsList, List<List<TSDataType>> typesList,
+ List<List<Object>> valuesList)
+ ```
+
+* 原始数据查询。时间间隔包含开始时间，不包含结束时间
+
+ ```
+ SessionDataSet executeRawDataQuery(List<String> paths, long startTime, long endTime)
+ ```
+
+* 执行查询语句
+
+ ```
+ SessionDataSet executeQueryStatement(String sql)
+ ```
+
+* 执行非查询语句
+
+ ```
+ void executeNonQueryStatement(String sql)
+ ```
+
+## 测试客户端逻辑+网络传输代价的接口
+
+* 测试 testInsertRecords，不实际写入数据，只将数据传输到 server 即返回。
+
+ ```
+ void testInsertRecords(List<String> deviceIds, List<Long> times, List<List<String>> measurementsList, List<List<String>> valuesList)
+ ```
+ 或
+ or
+ ```
+ void testInsertRecords(List<String> deviceIds, List<Long> times,
+ List<List<String>> measurementsList, List<List<TSDataType>> typesList,
+ List<List<Object>> valuesList)
+ ```
+
+* 测试 testInsertRecordsOfOneDevice，不实际写入数据，只将数据传输到 server 即返回。
+
+ ```
+ void testInsertRecordsOfOneDevice(List<String> deviceIds, List<Long> times,
+ List<List<String>> measurementsList, List<List<TSDataType>> typesList,
+ List<List<Object>> valuesList)
+ ```
+
+* 测试 insertRecord，不实际写入数据，只将数据传输到 server 即返回。
+
+ ```
+ void testInsertRecord(String deviceId, long time, List<String> measurements, List<String> values)
+ ```
+ 或
+ ```
+ void testInsertRecord(String deviceId, long time, List<String> measurements,
+ List<TSDataType> types, List<Object> values)
+ ```
+
+
+* 测试 insertTablet，不实际写入数据，只将数据传输到 server 即返回。
+
+ ```
+ void testInsertTablet(Tablet tablet)
+ ```
+
+
+## 示例代码
+
+浏览上述接口的详细信息，请参阅代码 ```session/src/main/java/org/apache/iotdb/session/Session.java```
+
+使用上述接口的示例代码在 ```example/session/src/main/java/org/apache/iotdb/SessionExample.java```
+
+有关对其时间序列和设备模板的实例代码在 ```example/session/src/main/java/org/apache/iotdb/VectorSessionExample.java```
+
+## 针对原生接口的连接池
+
+我们提供了一个针对原生接口的连接池(`SessionPool`)，使用该接口时，你只需要指定连接池的大小，就可以在使用时从池中获取连接。
+如果超过60s都没得到一个连接的话，那么会打印一条警告日志，但是程序仍将继续等待。
+
+当一个连接被用完后，他会自动返回池中等待下次被使用；
+当一个连接损坏后，他会从池中被删除，并重建一个连接重新执行用户的操作。
+
+对于查询操作：
+
+1. 使用SessionPool进行查询时，得到的结果集是`SessionDataSet`的封装类`SessionDataSetWrapper`;
+2. 若对于一个查询的结果集，用户并没有遍历完且不再想继续遍历时，需要手动调用释放连接的操作`closeResultSet`;
+3. 若对一个查询的结果集遍历时出现异常，也需要手动调用释放连接的操作`closeResultSet`.
+4. 可以调用 `SessionDataSetWrapper` 的 `getColumnNames()` 方法得到结果集列名
+
+使用示例可以参见 ```session/src/test/java/org/apache/iotdb/session/pool/SessionPoolTest.java```
+
+或 `example/session/src/main/java/org/apache/iotdb/SessionPoolExample.java`
+
+## 0.9-0.10 版本IoTDB Session 接口更新
+
+从0.9到0.10版本的IoTDB session接口有了较大改变。一部分接口名称和参数类型发生了变化，另外新增了大量可用接口。所有session接口抛出的异常类型 *IoTDBSessionExeception* 更改为 *IoTDBConnectionException* 和 *StatementExecutionExeception* 。下面详细介绍具体接口的变化。
+
+### 接口名称更改
+
+#### insert()
+
+用于插入一行数据，需提供数据点的deviceId, time, 所有measurement和相应的value值。
+
+```
+void insert(String deviceId, long time, List<String> measurements, List<String> values)
+```
+
+
+该方法在0.10版本中方法名发生变化
+
+```
+void insertRecord(String deviceId, long time, List<String> measurements, List<String> values)
+```
+
+#### insertRowInBatch()
+
+用于插入多行数据，需提供各行数据的deviceId, time, 所有measurement名称和相应的value值。
+
+```
+void insertRowInBatch(List<String> deviceIds, List<Long> times, List<List<String>> measurementsList,
+ List<List<String>> valuesList)
+```
+
+
+该方法在0.10版本中方法名发生变化
+
+```
+void insertRecords(List<String> deviceIds, List<Long> times, List<List<String>> measurementsList,
+ List<List<String>> valuesList)
+```
+
+#### insertBatch()
+
+在0.9版本中用于以"RowBatch"结构为单位插入数据
+
+```
+void insertBatch(RowBatch rowBatch)
+```
+
+在0.10版本中"RowBatch"类型更改为"Tablet"类型，因此方法名也随之改变。
+
+```
+void insertTablet(Tablet tablet)
+```
+
+#### testInsertRow()
+
+用于测试插入一行接口的响应
+
+```
+void testInsertRow(String deviceId, long time, List<String> measurements, List<String> values)
+```
+
+在0.10版本中方法名改为testInsertRecord。
+
+```
+void testInsertRecord(String deviceId, long time, List<String> measurements, List<String> values)
+```
+
+#### testInsertRowInBatch()
+
+用于测试插入多行数据接口的响应
+
+```
+void testInsertRowInBatch(List<String> deviceIds, List<Long> times, List<List<String>> measurementsList,
+ List<List<String>> valuesList)
+```
+
+在0.10版本中方法名改为testInsertRecords
+
+```
+void testInsertRecords(List<String> deviceIds, List<Long> times, List<List<String>> measurementsList,
+ List<List<String>> valuesList)
+```
+
+#### testInsertBatch
+
+用于测试以RowBatch结构为单位插入数据的响应
+
+```
+void testInsertBatch(RowBatch rowBatch)
+```
+
+在0.10版本中RowBatch类型更改为Tabet类型，因此方法名也随之改变为testInsertTablet
+
+```
+void testInsertTablet(Tablet tablet)
+```
+
+
+
+### 新增接口
+
+```
+void open(boolean enableRPCCompression)
+```
+
+开启一个session，并指定是否启用RPC压缩。注意客户端开启PRC压缩的状态需与服务端保持一致。
+
+```
+void insertRecord(String deviceId, long time, List<String> measurements,
+ List<TSDataType> types, List<Object> values)
+```
+
+插入一行数据，该方法和已有的insertRecord()方法不同在于需额外提供每个measurement的类型信息types，且参数values以原始类型的方式提供。写入速度相对于参数为String格式的insertRecord接口要快一些。
+
+```
+void insertRecords(List<String> deviceIds, List<Long> times, List<List<String>> measurementsList,
+ List<List<TSDataType>> typesList, List<List<Object>> valuesList)
+```
+
+插入多行数据，该方法和已有的insertRecords()方法不同在于需额外提供每个measurement的类型信息typesList，且参数valuesList以原始类型的方式提供。写入速度相对于参数为String格式的insertRecords接口要快一些。
+
+```
+void insertTablet(Tablet tablet, boolean sorted)
+```
+
+提供额外的sorted参数，表示tablet是否内部已排好序，如sorted为真则会省去排序的过程从而提升处理速度。
+
+```
+void insertTablets(Map<String, Tablet> tablets)
+```
+
+新增insertTablets接口用于写入多个tablet结构，tablets参数为Map<device名, tablet数据>
+
+```
+void insertTablets(Map<String, Tablet> tablets, boolean sorted)
+```
+
+带额外sorted参数的insertTablets接口
+
+```
+void testInsertRecord(String deviceId, long time, List<String> measurements, List<TSDataType> types,
+ List<Object> values)
+void testInsertRecords(List<String> deviceIds, List<Long> times, List<List<String>> measurementsList,
+ List<List<TSDataType>> typesList, List<List<Object>> valuesList)
+void testInsertTablet(Tablet tablet, boolean sorted)
+void testInsertTablets(Map<String, Tablet> tablets)
+void testInsertTablets(Map<String, Tablet> tablets, boolean sorted)
+```
+
+以上接口均为新增的测试rpc响应的方法，用于测试新增的写入接口
+
+```
+void createTimeseries(String path, TSDataType dataType, TSEncoding encoding, CompressionType compressor,
+ Map<String, String> props, Map<String, String> tags, Map<String, String> attributes,
+ String measurementAlias)
+```
+
+在原来createTimeseries接口的基础上，创建时间序列可以额外指定时间序列的props, tags, attributes和measurementAlias。如果不需要指定以上额外参数可以将参数设为null。
+
+```
+void createMultiTimeseries(List<String> paths, List<TSDataType> dataTypes, List<TSEncoding> encodings,
+ List<CompressionType> compressors, List<Map<String, String>> propsList,
+ List<Map<String, String>> tagsList, List<Map<String, String>> attributesList,
+ List<String> measurementAliasList)
+```
+
+一次性创建多个时间序列，同时也可以指定多个时间序列的props, tags, attributes和measurementAlias。
+
+```
+boolean checkTimeseriesExists(String path)
+```
+
+用于检测时间序列是否存在
+
+```
+public Session(String host, int rpcPort, String username, String password,
+ boolean isEnableCacheLeader)
+```
+
+开启一个session，并指定是否启用leader缓存。注意此接口对于分布式写入能够提高性能，但对于单机版写入反而会给客户端增加较少的消耗。
+
+```
+
+* name: 设备模板名称
+* measurements: 工况名称列表，如果该工况是非对齐的，直接将其名称放入一个list中再放入measurements中，
+* 如果该工况是对齐的，将所有对齐工况名称放入一个list再放入measurements中
+* dataTypes: 数据类型名称列表，如果该工况是非对齐的，直接将其数据类型放入一个list中再放入dataTypes中，
+ 如果该工况是对齐的，将所有对齐工况的数据类型放入一个list再放入dataTypes中
+* encodings: 编码类型名称列表，如果该工况是非对齐的，直接将其数据类型放入一个list中再放入encodings中，
+ 如果该工况是对齐的，将所有对齐工况的编码类型放入一个list再放入encodings中
+* compressors: 压缩方式列表
+void createDeviceTemplate(
+ String name,
+ List<List<String>> measurements,
+ List<List<TSDataType>> dataTypes,
+ List<List<TSEncoding>> encodings,
+ List<CompressionType> compressors)
+```
+
+创建一个设备模板
+
+```
+
+void setDeviceTemplate(String templateName, String prefixPath)
+
+```
+
+将名为'templateName'的设备模板挂载到'prefixPath'路径下，在执行这一步之前，你需要创建名为'templateName'的设备模板
+
+```
+
+void createDeviceTemplate
+
+```
\ No newline at end of file
diff --git a/docs/zh/UserGuide/IoTDB-SQL-Language/DDL-Data-Definition-Language.md b/docs/zh/UserGuide/IoTDB-SQL-Language/DDL-Data-Definition-Language.md
index a01db82..e108482 100644
--- a/docs/zh/UserGuide/IoTDB-SQL-Language/DDL-Data-Definition-Language.md
+++ b/docs/zh/UserGuide/IoTDB-SQL-Language/DDL-Data-Definition-Language.md
@@ -101,6 +101,33 @@ error: encoding TS_2DIFF does not support BOOLEAN
详细的数据类型与编码方式的对应列表请参见[编码方式](../Data-Concept/Encoding.md)。
+### 创建和挂载设备模板
+```
+
+IoTDB > set storage group root.beijing
+
+// 创建设备模板
+IoTDB > create device template temp1(
+ (s1 INT32 with encoding=Gorilla, compression=SNAPPY),
+ (s2 FLOAT with encoding=RLE, compression=SNAPPY)
+ )
+
+// 将设备模板挂载到root.beijing存储组上
+IoTDB > set device template temp1 to root.beijing
+
+```
+
+### 标签点管理
+
+我们可以在创建时间序列的时候，为它添加别名和额外的标签和属性信息。
+所用到的扩展的创建时间序列的SQL语句如下所示：
+```
+create timeseries root.turbine.d1.s1(temprature) with datatype=FLOAT, encoding=RLE, compression=SNAPPY tags(tag1=v1, tag2=v2) attributes(attr1=v1, attr2=v2)
+```
+
+括号里的`temprature`是`s1`这个传感器的别名。
+我们可以在任何用到`s1`的地方，将其用`temprature`代替，这两者是等价的。
+
#### 删除时间序列
我们可以使用`DELETE TimeSeries <PrefixPath>`语句来删除我们之前创建的时间序列。SQL语句如下所示：
diff --git a/session/src/main/java/org/apache/iotdb/session/Session.java b/session/src/main/java/org/apache/iotdb/session/Session.java
index 95428f0..359438e 100644
--- a/session/src/main/java/org/apache/iotdb/session/Session.java
+++ b/session/src/main/java/org/apache/iotdb/session/Session.java
@@ -18,6 +18,18 @@
*/
package org.apache.iotdb.session;
+import java.nio.ByteBuffer;
+import java.time.ZoneId;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Map.Entry;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.stream.Collectors;
import org.apache.iotdb.rpc.BatchExecutionException;
import org.apache.iotdb.rpc.IoTDBConnectionException;
import org.apache.iotdb.rpc.RedirectException;
@@ -48,23 +60,9 @@ import org.apache.iotdb.tsfile.utils.ReadWriteIOUtils;
import org.apache.iotdb.tsfile.write.record.Tablet;
import org.apache.iotdb.tsfile.write.schema.IMeasurementSchema;
import org.apache.iotdb.tsfile.write.schema.MeasurementSchema;
-
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
-import java.nio.ByteBuffer;
-import java.time.ZoneId;
-import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.Collections;
-import java.util.Comparator;
-import java.util.HashMap;
-import java.util.List;
-import java.util.Map;
-import java.util.Map.Entry;
-import java.util.concurrent.atomic.AtomicReference;
-import java.util.stream.Collectors;
-
@SuppressWarnings({"java:S107", "java:S1135"}) // need enough parameters, ignore todos
public class Session {
@@ -1631,6 +1629,21 @@ public class Session {
defaultSessionConnection.setDeviceTemplate(request);
}
+ /**
+ * @param name template name
+ * @param measurements List of measurements, if it is a single measurement, just put it's name
+ * into a list and add to measurements if it is a vector measurement, put all measurements of
+ * the vector into a list and add to measurements
+ * @param dataTypes List of datatypes, if it is a single measurement, just put it's type into a
+ * list and add to dataTypes if it is a vector measurement, put all types of the vector into a
+ * list and add to dataTypes
+ * @param encodings List of encodings, if it is a single measurement, just put it's encoding into
+ * a list and add to encodings if it is a vector measurement, put all encodings of the vector
+ * into a list and add to encodings
+ * @param compressors List of compressors
+ * @throws IoTDBConnectionException
+ * @throws StatementExecutionException
+ */
public void createDeviceTemplate(
String name,
List<List<String>> measurements,