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/01/26 09:23:04 UTC
[iotdb] branch master updated: add docs to suggest only flat measurement template is a long-term feature (#4982)
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 c694c01 add docs to suggest only flat measurement template is a long-term feature (#4982)
c694c01 is described below
commit c694c018c83f93b0fea0f07098262e3ccaf9fef3
Author: ZhaoXin <x_...@163.com>
AuthorDate: Wed Jan 26 17:22:31 2022 +0800
add docs to suggest only flat measurement template is a long-term feature (#4982)
---
docs/UserGuide/API/Programming-Java-Native-API.md | 30 +++++++---------------
.../UserGuide/API/Programming-Java-Native-API.md | 9 ++++---
.../java/org/apache/iotdb/session/Session.java | 9 +++++++
.../apache/iotdb/session/template/Template.java | 10 ++++++++
4 files changed, 33 insertions(+), 25 deletions(-)
diff --git a/docs/UserGuide/API/Programming-Java-Native-API.md b/docs/UserGuide/API/Programming-Java-Native-API.md
index 657bdf5..df58da2 100644
--- a/docs/UserGuide/API/Programming-Java-Native-API.md
+++ b/docs/UserGuide/API/Programming-Java-Native-API.md
@@ -172,7 +172,7 @@ boolean checkTimeseriesExists(String path)
#### Schema Template
-Create a schema template for massive identical subtree will help to improve memory performance. You can use the API above to create a template at server side, and use Template, InternalNode and MeasurementNode to depict the structure of the template, and use belowed interface to create it inside session.
+Create a schema template for massive identical devices will help to improve memory performance. You can use Template, InternalNode and MeasurementNode to depict the structure of the template, and use belowed interface to create it inside session.
```java
public void createSchemaTemplate(Template template);
@@ -194,13 +194,6 @@ Abstract Class Node {
public void deleteChild(Node node);
}
-Class InternalNode extends Node {
- boolean shareTime;
- Map<String, Node> children;
- public void setShareTime(boolean shareTime);
- public InternalNode(String name, boolean isShareTime);
-}
-
Class MeasurementNode extends Node {
TSDataType dataType;
TSEncoding encoding;
@@ -212,6 +205,8 @@ Class MeasurementNode extends Node {
}
```
+We strongly suggest you implement templates only with flat-measurement (like object 'flatTemplate' in belowed snippet), since tree-structured template may not be a long-term supported feature in further version of IoTDB.
+
A snippet of using above Method and Class：
```java
@@ -219,20 +214,13 @@ MeasurementNode nodeX = new MeasurementNode("x", TSDataType.FLOAT, TSEncoding.RL
MeasurementNode nodeY = new MeasurementNode("y", TSDataType.FLOAT, TSEncoding.RLE, CompressionType.SNAPPY);
MeasurementNode nodeSpeed = new MeasurementNode("speed", TSDataType.DOUBLE, TSEncoding.GORILLA, CompressionType.SNAPPY);
-InternalNode internalGPS = new InternalNode("GPS", true);
-InternalNode internalVehicle = new InternalNode("vehicle", false);
-
-internalGPS.addChild(nodeX);
-internalGPS.addChild(nodeY);
-internalVehicle.addChild(GPS);
-internalVehicle.addChild(nodeSpeed);
-
-Template template = new Template("treeTemplateExample");
-template.addToTemplate(internalGPS);
-template.addToTemplate(internalVehicle);
+// This is the template we suggest to implement
+Template flatTemplate = new Template("flatTemplate");
+template.addToTemplate(nodeX);
+template.addToTemplate(nodeY);
template.addToTemplate(nodeSpeed);
-createSchemaTemplate(template);
+createSchemaTemplate(flatTemplate);
```
After measurement template created, you can edit the template with belowed APIs.
@@ -275,7 +263,7 @@ public void addUnalignedMeasurementsIntemplate(String templateName,
TSEncoding[] encodings,
CompressionType[] compressors);
-// Delete a node in template and its children
+// Delete a node in template
public void deleteNodeInTemplate(String templateName, String path);
```
diff --git a/docs/zh/UserGuide/API/Programming-Java-Native-API.md b/docs/zh/UserGuide/API/Programming-Java-Native-API.md
index 2ffabb0..55bb140 100644
--- a/docs/zh/UserGuide/API/Programming-Java-Native-API.md
+++ b/docs/zh/UserGuide/API/Programming-Java-Native-API.md
@@ -207,19 +207,20 @@ Class MeasurementNode extends Node {
}
```
-通过这种方式创建元数据模板的代码示例如下：
+通过上述类的实例描述模板时，Template 内应当仅能包含单层的 MeasurementNode，具体可以参见如下示例：
```java
MeasurementNode nodeX = new MeasurementNode("x", TSDataType.FLOAT, TSEncoding.RLE, CompressionType.SNAPPY);
MeasurementNode nodeY = new MeasurementNode("y", TSDataType.FLOAT, TSEncoding.RLE, CompressionType.SNAPPY);
MeasurementNode nodeSpeed = new MeasurementNode("speed", TSDataType.DOUBLE, TSEncoding.GORILLA, CompressionType.SNAPPY);
-Template template = new Template("templateExample");
+// This is the template we suggest to implement
+Template flatTemplate = new Template("flatTemplate");
template.addToTemplate(nodeX);
template.addToTemplate(nodeY);
template.addToTemplate(nodeSpeed);
-createSchemaTemplate(template);
+createSchemaTemplate(flatTemplate);
```
* 在创建概念元数据模板以后，还可以通过以下接口增加或删除模板内的物理量。请注意，已经挂载的模板不能删除内部的物理量。
@@ -254,7 +255,7 @@ public void addUnalignedMeasurementsIntemplate(String templateName,
TSEncoding[] encodings,
CompressionType[] compressors);
-// 从指定模板中删除一个节点及其子树
+// 从指定模板中删除一个节点
public void deleteNodeInTemplate(String templateName, String path);
```
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 e89d18d..2c18c2d 100644
--- a/session/src/main/java/org/apache/iotdb/session/Session.java
+++ b/session/src/main/java/org/apache/iotdb/session/Session.java
@@ -2052,6 +2052,15 @@ public class Session {
/**
* Construct Template at session and create it at server.
*
+ * <p>The template instance constructed within session is SUGGESTED to be a flat measurement
+ * template, which has no internal nodes inside a template.
+ *
+ * <p>For example, template(s1, s2, s3) is a flat measurement template, while template2(GPS.x,
+ * GPS.y, s1) is not.
+ *
+ * <p>Tree-structured template, which is contrary to flat measurement template, may not be
+ * supported in further version of IoTDB
+ *
* @see Template
*/
public void createSchemaTemplate(Template template)
diff --git a/session/src/main/java/org/apache/iotdb/session/template/Template.java b/session/src/main/java/org/apache/iotdb/session/template/Template.java
index 78b25aa..ed12b27 100644
--- a/session/src/main/java/org/apache/iotdb/session/template/Template.java
+++ b/session/src/main/java/org/apache/iotdb/session/template/Template.java
@@ -32,6 +32,16 @@ import java.util.HashSet;
import java.util.Map;
import java.util.Set;
+/**
+ * The template instance constructed within session is SUGGESTED to be a flat measurement template,
+ * which has no internal nodes inside a template.
+ *
+ * <p>For example, template(s1, s2, s3) is a flat measurement template, while template2(GPS.x,
+ * GPS.y, s1) is not.
+ *
+ * <p>Tree-structured template, which is contrary to flat measurement template, may not be supported
+ * in further version of IoTDB
+ */
public class Template {
private String name;
private Map<String, TemplateNode> children;