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 <[email protected]>
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;
