[iotdb] branch rel/0.13 updated: [To rel/0.13]Add more docs about schema template (#7441)

[qiaojialin]

This is an automated email from the ASF dual-hosted git repository.

qiaojialin pushed a commit to branch rel/0.13
in repository https://gitbox.apache.org/repos/asf/iotdb.git


The following commit(s) were added to refs/heads/rel/0.13 by this push:
     new d97084255a [To rel/0.13]Add more docs about schema template (#7441)
d97084255a is described below

commit d97084255afac9c578a83a7889f2744146b7cb5d
Author: ZhaoXin <x_zha...@163.com>
AuthorDate: Wed Sep 28 21:02:19 2022 +0800

    [To rel/0.13]Add more docs about schema template (#7441)
---
 docs/UserGuide/Data-Concept/Schema-Template.md    | 17 ++++++++++++++++-
 docs/zh/UserGuide/Data-Concept/Schema-Template.md | 17 ++++++++++++++++-
 2 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/docs/UserGuide/Data-Concept/Schema-Template.md 
b/docs/UserGuide/Data-Concept/Schema-Template.md
index 9d589980ab..fac5f8592f 100644
--- a/docs/UserGuide/Data-Concept/Schema-Template.md
+++ b/docs/UserGuide/Data-Concept/Schema-Template.md
@@ -31,7 +31,7 @@ The following picture illustrates the data model of petrol 
vehicle scenario. The
 
 <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
+## Concepts
 
 Supported from v0.13
 
@@ -49,6 +49,21 @@ After applying schema template, the following picture 
illustrates the new data m
 
 <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">
 
+### Lifetime of Schema Template
+
+The term about lifetime of schema template may help you utilize it in a better 
way.   Within this section, there are 6 key words specifying certain phase of 
schema template, namely CREATE, SET, ACTIVATE, DEACTIVATE, UNSET, and DROP.   
The figure below shows the process and related SQL examples for all these 
phases.   When a user issues a statement mentioned above, there will be a check 
accordingly.   The statement will be executed successfully if the check passed, 
refused otherwise.
+
+1. To CREATE a template, ensure that the template has a distinct name from all 
existed ones;
+2. To SET a template on one node, ensure that all ancestors and descendants of 
the node has not been set any template yet;
+3. To ACTIVATE a template on one node, ensure that the node or one of its 
ancestor had been set the template and no measurement child of the node 
entitled identical name as those inside the template;
+4. To DEACTIVATE a template from one node, ensure that the node had been 
ACTIVATED before and note that timeseries instantiated from the template as 
well as its data points will be removed; 
+5. To UNSET a template on one node, ensure that the node had been SET the 
template previously and none of its descendants are being ACTIVATED of the 
template;
+6. To DROP a template, ensure that the template is not SET to any nodes on the 
MTree now.
+
+It should be complemented that the distinction between SET and ACTIVATE is 
meant to serve an ubiquitous scenario where massive nodes with a common 
ancestor may need to apply the template. Under this circumstance, it is more 
feasible to SET the template on the common ancestor rather than all those 
descendant.    For those who needs to apply the template, ACTIVATE is a more 
appropriate arrangement.
+
+<img style="width:100%; max-width:800px; 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_template_lifetime.png?raw=true";
 alt="example with template">
+
 ## Usage
 
 Java Native API, C++ Native API, and IoTDB-SQL have supported Schema Template 
usage.
\ No newline at end of file
diff --git a/docs/zh/UserGuide/Data-Concept/Schema-Template.md 
b/docs/zh/UserGuide/Data-Concept/Schema-Template.md
index 1fc7e8add5..c0add6c8b2 100644
--- a/docs/zh/UserGuide/Data-Concept/Schema-Template.md
+++ b/docs/zh/UserGuide/Data-Concept/Schema-Template.md
@@ -47,6 +47,21 @@
 
 <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">
 
+### 生命周期
+
+了解元数据的生命周期及相关名词，有助于更顺畅地使用元数据模板。在描述这一概念时，有六个关键词分别指向特定的过程，分别是“创建”、“挂载”、“激活”、“解除”、“卸载”、和“删除”。下图展示了一个模板从创建、挂到删除的全部过程。当用户操作执行其中任一过程时，系统都会执行对应条件检查，如条件检查通过，则操作成功，否则，操作会被拒绝：
+
+1. 创建模板时，检查确认正在创建的模板名称与所有已存在的模板不重复；
+2. 在某节点挂载模板，需检查该节点的所有祖先节点与子孙节点，确认均未挂载任何模板；
+3. 在某节点激活模板，需检查确认该节点或其祖先已挂载对应模板，且该节点下不存在与模板中同名的物理量；
+4. 在某节点解除模板时，需确认该节点已经激活了模板，请注意，解除模板会删除该节点通过模板实例化的物理量及其数据点；
+5. 在某节点卸载模板时，需检查确认该节点曾挂载该模板，且其所有子孙节点均不处于模板激活状态；
+6. 删除模板时，需检查确认模板没有挂载在任何一个节点上。
+
+最后需要补充的是，**对挂载模板与激活模板进行区分，是为了服务一种常见的场景**：在 Apache IoTDB 元数据模型 MTree 
中，经常需要在数量众多的节点上“应用”元数据模板，而这些节点一般拥有共同的祖先节点。因此，可以在其共同祖先节点**挂载**模板，而不必对其大量的孩子节点进行挂载操作。对于需要“应用”模板的节点，则应该使用**激活模板**的操作。
+
+<img style="width:100%; max-width:800px; 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_template_lifetime_zh.png?raw=true";
 alt="example with template">
+
 ### 使用
 
 目前，用户可以通过 Session 编程接口或 IoTDB-SQL 来使用元数据模板，包括模板的创建、修改、挂载与卸载等。Session 
编程接口的详细文档可参见[此处](../API/Programming-Java-Native-API.md)，IoTDB-SQL 
的详细文档可参加[此处](../Operate-Metadata/Template.md)。下文将以 Session 中使用方法为例，进行简要介绍。
@@ -115,7 +130,7 @@ setSchemaTemplate("template", "root.Beijing");
 
 创建元数据模板后，还可以增加或删除模板中的节点。需要注意的是，一旦模板被挂载，在卸载模板之前就不再允许从模板中删除节点。
 
-对于挂载了模板的节点或其子孙节点，可以通过相应接口激活模板。**对挂载模板与激活模板的状态进行区分，是为了服务一种常见的场景**：在 Apache 
IoTDB 元数据模型 MTree 
中，经常需要在数量众多的节点上“应用”元数据模板，而这些节点一般拥有共同的祖先节点。因此，可以在其共同祖先节点**挂载**模板，而不必对其大量的孩子节点进行挂载操作。对于需要“应用”模板的节点，则应该使用**激活模板**的操作。
+对于挂载了模板的节点或其子孙节点，可以通过相应接口激活模板。
 
 
解除与卸载模板，分别是激活与挂载模板的逆过程。**其中，对一个节点解除模板还会删除该节点在模板中的序列写入的数据。**需要注意的是，如果一个挂载了模板的节点或其子孙节点，当前已经激活了模板，那么在解除激活之前，该节点就不能卸载模板。类似地，如果有任意一个节点挂载了模板，那么在其卸载之前，模板就不能被删除。