You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iotdb.apache.org by ha...@apache.org on 2021/08/15 02:52:06 UTC
[iotdb] branch master updated: Add Measurement-Template doc (#3744)
This is an automated email from the ASF dual-hosted git repository.
haonan 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 04d7a9f Add Measurement-Template doc (#3744)
04d7a9f is described below
commit 04d7a9f000231bb33cc6ae269eb30ecd93778247
Author: zyk990424 <38...@users.noreply.github.com>
AuthorDate: Sun Aug 15 10:51:36 2021 +0800
Add Measurement-Template doc (#3744)
---
docs/UserGuide/API/Programming-Java-Native-API.md | 6 +-
.../Data-Concept/Data-Model-and-Terminology.md | 6 +-
.../UserGuide/Data-Concept/Measurement-Template.md | 84 ++++++++++++++++++++++
.../UserGuide/API/Programming-Java-Native-API.md | 8 +--
.../Data-Concept/Data-Model-and-Terminology.md | 4 +-
.../UserGuide/Data-Concept/Measurement-Template.md | 81 +++++++++++++++++++++
6 files changed, 175 insertions(+), 14 deletions(-)
diff --git a/docs/UserGuide/API/Programming-Java-Native-API.md b/docs/UserGuide/API/Programming-Java-Native-API.md
index cac776e..033fefe 100644
--- a/docs/UserGuide/API/Programming-Java-Native-API.md
+++ b/docs/UserGuide/API/Programming-Java-Native-API.md
@@ -290,7 +290,7 @@ Examples: ```session/src/test/java/org/apache/iotdb/session/pool/SessionPoolTest
Or `example/session/src/main/java/org/apache/iotdb/SessionPoolExample.java`
-For examples of aligned timeseries and device template, you can refer to `example/session/src/main/java/org/apache/iotdb/AlignedTimeseriesSessionExample.java`
+For examples of aligned timeseries and measurement template, you can refer to `example/session/src/main/java/org/apache/iotdb/AlignedTimeseriesSessionExample.java`
@@ -412,7 +412,7 @@ void createSchemaTemplate(
List<CompressionType> compressors)
```
-Create a device template, the param description at above
+Create a measurement template, the param description at above
```
@@ -420,7 +420,7 @@ void setSchemaTemplate(String templateName, String prefixPath)
```
-Set the device template named 'templateName' at path 'prefixPath'. You should firstly create the template using
+Set the measurement template named 'templateName' at path 'prefixPath'. You should firstly create the template using
```
diff --git a/docs/UserGuide/Data-Concept/Data-Model-and-Terminology.md b/docs/UserGuide/Data-Concept/Data-Model-and-Terminology.md
index e61f728..041e78a 100644
--- a/docs/UserGuide/Data-Concept/Data-Model-and-Terminology.md
+++ b/docs/UserGuide/Data-Concept/Data-Model-and-Terminology.md
@@ -150,8 +150,6 @@ The timestamp is the time point at which data is produced. It includes absolute
* Measurement template (From v0.13)
-In the actual scenario, many entities collect the same measurements, that is, they have the same measurements name and type. A **measurement template** can be declared to define the collectable measurements set. Measurement template is hung on any node of the tree data pattern, which means that all entities under the node have the same measurements set.
+In the actual scenario, many entities collect the same measurements, that is, they have the same measurements name and type. A **measurement template** can be declared to define the collectable measurements set. Measurement template helps save memory by implementing schema sharing. For detailed description, please refer to Measurement Template doc.
-Currently you can only set one **measurement template** on a specific path. If there's one measurement template on one node, it will be forbidden to set any measurement template on the ancestors or descendants of this node. An entity will use it's own measurement template or ancestor's measurement template.
-
-In the following chapters of data definition language, data operation language and Java Native Interface, various operations related to measurement template will be introduced one by one.
+In the following chapters of, data definition language, data operation language and Java Native Interface, various operations related to measurement template will be introduced one by one.
diff --git a/docs/UserGuide/Data-Concept/Measurement-Template.md b/docs/UserGuide/Data-Concept/Measurement-Template.md
new file mode 100644
index 0000000..2fd397e
--- /dev/null
+++ b/docs/UserGuide/Data-Concept/Measurement-Template.md
@@ -0,0 +1,84 @@
+<!--
+
+ 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.
+
+-->
+
+## Measurement Template
+
+### Problem scenario
+
+When faced with a large number of entities of the same type and the measurements of these entities are the same, registering time series for each measurent will result in the following problems. On the one hand, the metadata of time series will occupy a lot of memory resources; on the other hand, the maintenance of a large number of time series will be very complex.
+
+In order to enable different entities of the same type to share metadata, reduce the memory usage of metadata, and simplify the management of numerous entities and measurements, IoTDB introduces the measurement template function.
+
+The following picture illustrates the data model of petrol vehicle scenario. The velocity, fuel amount, acceleration, and angular velocity of each petrol vehicle spread over cities will be collected. Obviously, the measurements of single petrol vehicle are the same as those of another.
+
+<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; margin-right:auto; display:block;" src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Data%20Concept/Measurement%20Template/example_without_template.png?raw=true" alt="example without template">
+
+### Concept
+
+Supported from v0.13
+
+In the actual scenario, many entities collect the same measurements, that is, they have the same measurements name and type. A measurement template can be declared to define the collectable measurements set. Measurement template is hung on any node of the tree data pattern, which means that all entities under the node have the same measurements set.
+
+Currently you can only set one measurement template on a specific path. If there's one measurement template on one node, it will be forbidden to set any measurement template on the ancestors or descendants of this node. An entity will use it's own measurement template or ancestor's measurement template.
+
+In the following chapters of data definition language, data operation language and Java Native Interface, various operations related to measurement template will be introduced one by one.
+
+After applying measurement template, the following picture illustrates the new data model of petrol vehicle scenario. All petrol vehicles share the schemas defined in template. There are no redundancy storage of measurement schemas.
+
+<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; margin-right:auto; display:block;" src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Data%20Concept/Measurement%20Template/example_with_template.png?raw=true" alt="example with template">
+
+### Usage
+
+Currently, only Session API supports Measurement Template usage.
+
+* Create a measurement template
+```
+
+* 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 createSchemaTemplate(
+ String templateName,
+ List<String> schemaName,
+ List<List<String>> measurements,
+ List<List<TSDataType>> dataTypes,
+ List<List<TSEncoding>> encodings,
+ List<CompressionType> compressors)
+```
+* Set the device template named 'templateName' at path 'prefixPath'. You should firstly create the template using
+
+```
+
+void setSchemaTemplate(String templateName, String prefixPath)
+
+```
+
+After setting measurement template，data could be inserted directly to the according timeseries. For example, suppose there's storage group root.sg and template t1(s1,s2) has been set to root.sg.car，then timeseries like root.sg.car.d1.s1 and root.sg.car.d1.s2 are available and data can be inserted。
+
+For examples of measurement template, you can refer to example/session/src/main/java/org/apache/iotdb/AlignedTimeseriesSessionExample.java
\ No newline at end of file
diff --git a/docs/zh/UserGuide/API/Programming-Java-Native-API.md b/docs/zh/UserGuide/API/Programming-Java-Native-API.md
index 973b29d..d3db955 100644
--- a/docs/zh/UserGuide/API/Programming-Java-Native-API.md
+++ b/docs/zh/UserGuide/API/Programming-Java-Native-API.md
@@ -209,10 +209,10 @@ SessionDataSet executeQueryStatement(String sql)
void executeNonQueryStatement(String sql)
```
-* 创建一个设备模板
+* 创建一个物理量模板
```
-* name: 设备模板名称
+* name: 物理量模板名称
* measurements: 工况名称列表，如果该工况是非对齐的，直接将其名称放入一个 list 中再放入 measurements 中，
* 如果该工况是对齐的，将所有对齐工况名称放入一个 list 再放入 measurements 中
* dataTypes: 数据类型名称列表，如果该工况是非对齐的，直接将其数据类型放入一个 list 中再放入 dataTypes 中，
@@ -229,7 +229,7 @@ void createSchemaTemplate(
List<CompressionType> compressors)
```
-* 将名为'templateName'的设备模板挂载到'prefixPath'路径下，在执行这一步之前，你需要创建名为'templateName'的设备模板
+* 将名为'templateName'的物理量模板挂载到'prefixPath'路径下，在执行这一步之前，你需要创建名为'templateName'的物理量模板
```
void setSchemaTemplate(String templateName, String prefixPath)
@@ -287,7 +287,7 @@ void testInsertTablet(Tablet tablet)
或 `example/session/src/main/java/org/apache/iotdb/SessionPoolExample.java`
-使用对齐时间序列和设备模板的示例可以参见 `example/session/src/main/java/org/apache/iotdb/AlignedTimeseriesSessionExample.java`。
+使用对齐时间序列和物理量模板的示例可以参见 `example/session/src/main/java/org/apache/iotdb/AlignedTimeseriesSessionExample.java`。
### 示例代码
diff --git a/docs/zh/UserGuide/Data-Concept/Data-Model-and-Terminology.md b/docs/zh/UserGuide/Data-Concept/Data-Model-and-Terminology.md
index a11c88f..981ef7f 100644
--- a/docs/zh/UserGuide/Data-Concept/Data-Model-and-Terminology.md
+++ b/docs/zh/UserGuide/Data-Concept/Data-Model-and-Terminology.md
@@ -150,6 +150,4 @@ LayerName: Identifier | STAR
* 物理量模板（Measurement template，v0.13 起支持）
-实际应用中有许多实体所采集的物理量相同，即具有相同的工况名称和类型，可以声明一个**物理量模板**来定义可采集的物理量集合。将物理量模版挂在树形数据模式的任意节点上，表示该节点下的所有实体具有相同的物理量集合。
-
-目前每一条路径节点仅允许挂载一个物理量模板，即当一个节点被挂载物理量模板后，它的祖先节点和后代节点都不能再挂载物理量模板。实体将使用其自身或祖先的物理量模板作为有效模板。
\ No newline at end of file
+实际应用中有许多实体所采集的物理量相同，即具有相同的工况名称和类型，可以声明一个**物理量模板**来定义可采集的物理量集合。在实践中，物理量模板的使用可帮助减少元数据的资源占用，详细内容参见物理量模板文档。
\ No newline at end of file
diff --git a/docs/zh/UserGuide/Data-Concept/Measurement-Template.md b/docs/zh/UserGuide/Data-Concept/Measurement-Template.md
new file mode 100644
index 0000000..23f1e9f
--- /dev/null
+++ b/docs/zh/UserGuide/Data-Concept/Measurement-Template.md
@@ -0,0 +1,81 @@
+<!--
+
+ 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.
+
+-->
+
+## 物理量模板
+
+### 问题背景
+
+当面临一批大量的同类型的实体，这些实体的物理量都相同时，为每个序列注册时间序列一方面时间序列的元数据将占用较多的内存资源，另一方面大量序列的维护工作也会十分复杂。
+
+为了实现同类型不同实体的物理量元数据共享，减少元数据内存占用，同时简化同类型实体的管理，IoTDB引入物理量模板功能。
+
+下图展示了一个燃油车场景的数据模型，各地区的多台燃油车的速度、油量、加速度、角速度四个物理量将会被采集，显然这些燃油车实体具备相同的物理量。
+
+<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; margin-right:auto; display:block;" src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Data%20Concept/Measurement%20Template/example_without_template.png?raw=true" alt="example without template">
+
+### 概念定义
+
+物理量模板（Measurement template，v0.13 起支持）
+
+实际应用中有许多实体所采集的物理量相同，即具有相同的工况名称和类型，可以声明一个**物理量模板**来定义可采集的物理量集合。
+
+将物理量模版挂载在树形数据模式的任意节点上，表示该节点下的所有实体具有相同的物理量集合。
+
+目前每一条路径节点仅允许挂载一个物理量模板，即当一个节点被挂载物理量模板后，它的祖先节点和后代节点都不能再挂载物理量模板。实体将使用其自身或祖先的物理量模板作为有效模板。
+
+使用物理量模板后，问题背景中示例的燃油车数据模型将会转变至下图所示的形式。所有的物理量元数据仅在模板中保存一份，所有的实体共享模板中的元数据。
+
+<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; margin-right:auto; display:block;" src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Data%20Concept/Measurement%20Template/example_with_template.png?raw=true" alt="example with template">
+
+### 使用
+
+当前仅支持通过Session编程接口使用物理量模板，包括模板的创建和挂载操作。
+
+
+* 创建一个物理量模板
+
+```
+* name: 物理量模板名称
+* measurements: 工况名称列表，如果该工况是非对齐的，直接将其名称放入一个 list 中再放入 measurements 中，
+* 如果该工况是对齐的，将所有对齐工况名称放入一个 list 再放入 measurements 中
+* dataTypes: 数据类型名称列表，如果该工况是非对齐的，直接将其数据类型放入一个 list 中再放入 dataTypes 中，
+ 如果该工况是对齐的，将所有对齐工况的数据类型放入一个 list 再放入 dataTypes 中
+* encodings: 编码类型名称列表，如果该工况是非对齐的，直接将其数据类型放入一个 list 中再放入 encodings 中，
+ 如果该工况是对齐的，将所有对齐工况的编码类型放入一个 list 再放入 encodings 中
+* compressors: 压缩方式列表
+void createSchemaTemplate(
+ String templateName,
+ List<String> schemaName,
+ List<List<String>> measurements,
+ List<List<TSDataType>> dataTypes,
+ List<List<TSEncoding>> encodings,
+ List<CompressionType> compressors)
+```
+
+* 将名为'templateName'的物理量模板挂载到'prefixPath'路径下，在执行这一步之前，你需要创建名为'templateName'的物理量模板
+
+```
+void setSchemaTemplate(String templateName, String prefixPath)
+```
+
+挂载好物理量模板后，即可进行数据的写入。例如存储组为root.sg，模板t1(s1,s2)被挂载到了节点root.sg.car，那么可直接向时间序列（如root.sg.car.d1.s1和root.sg.car.d1.s2）写入时间序列数据，该时间序列已可被当作正常创建的序列使用。
+
+使用物理量模板的示例可以参见 `example/session/src/main/java/org/apache/iotdb/AlignedTimeseriesSessionExample.java`。