Add schema template lifecycle description and strengthen sql constrai…

…nts (apache#8100)

antlr/src/main/antlr4/org/apache/iotdb/db/qp/sql/IoTDBSqlParser.g4

@@ -99,7 +99,7 @@ alignedMeasurements
 
 // Create Schema Template
 createSchemaTemplate
-    : CREATE SCHEMA? TEMPLATE templateName=identifier
+    : CREATE SCHEMA TEMPLATE templateName=identifier
     ALIGNED? LR_BRACKET templateMeasurementClause (COMMA templateMeasurementClause)* RR_BRACKET
     ;
 
@@ -109,7 +109,7 @@ templateMeasurementClause
 
 // Create Timeseries Of Schema Template
 createTimeseriesOfSchemaTemplate
-    : CREATE TIMESERIES OF SCHEMA? TEMPLATE ON prefixPath
+    : CREATE TIMESERIES OF SCHEMA TEMPLATE ON prefixPath
     ;
 
 // Create Function
@@ -213,7 +213,7 @@ deletePartition
 
 // Delete Timeseries of Schema Template
 deleteTimeseriesOfSchemaTemplate
-    : (DELETE TIMESERIES OF | DEACTIVATE) SCHEMA? TEMPLATE (templateName=identifier) ? FROM prefixPath (COMMA prefixPath)*
+    : (DELETE TIMESERIES OF | DEACTIVATE) SCHEMA TEMPLATE (templateName=identifier) ? FROM prefixPath (COMMA prefixPath)*
     ;
 
 // Drop Function
@@ -233,7 +233,7 @@ dropContinuousQuery
 
 // Drop Schema Template
 dropSchemaTemplate
-    : DROP SCHEMA? TEMPLATE templateName=identifier
+    : DROP SCHEMA TEMPLATE templateName=identifier
     ;
 
 // Get Region Id
@@ -266,12 +266,12 @@ unsetTTL
 
 // Set Schema Template
 setSchemaTemplate
-    : SET SCHEMA? TEMPLATE templateName=identifier TO prefixPath
+    : SET SCHEMA TEMPLATE templateName=identifier TO prefixPath
     ;
 
 // Unset Schema Template
 unsetSchemaTemplate
-    : UNSET SCHEMA? TEMPLATE templateName=identifier FROM prefixPath
+    : UNSET SCHEMA TEMPLATE templateName=identifier FROM prefixPath
     ;
 
 // Start Trigger
@@ -361,22 +361,22 @@ showConfigNodes
 
 // Show Schema Template
 showSchemaTemplates
-    : SHOW SCHEMA? TEMPLATES
+    : SHOW SCHEMA TEMPLATES
     ;
 
 // Show Measurements In Schema Template
 showNodesInSchemaTemplate
-    : SHOW NODES OPERATOR_IN SCHEMA? TEMPLATE templateName=identifier
+    : SHOW NODES OPERATOR_IN SCHEMA TEMPLATE templateName=identifier
     ;
 
 // Show Paths Set Schema Template
 showPathsSetSchemaTemplate
-    : SHOW PATHS SET SCHEMA? TEMPLATE templateName=identifier
+    : SHOW PATHS SET SCHEMA TEMPLATE templateName=identifier
     ;
 
 // Show Paths Using Schema Template
 showPathsUsingSchemaTemplate
-    : SHOW PATHS prefixPath? USING SCHEMA? TEMPLATE templateName=identifier
+    : SHOW PATHS prefixPath? USING SCHEMA TEMPLATE templateName=identifier
     ;
 
 // Count Storage Group

docs/UserGuide/Data-Concept/Schema-Template.md

@@ -47,6 +47,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.

docs/UserGuide/Operate-Metadata/Template.md

@@ -30,7 +30,7 @@ Note: The `schema` keyword in the following statements can be omitted.
 The SQL syntax for creating a metadata template is as follows:
 
 ```sql
-CREATE SCHEMA? TEMPLATE <templateName> ALIGNED? '(' <measurementId> <attributeClauses> [',' <measurementId> <attributeClauses>]+ ')'
+CREATE SCHEMA TEMPLATE <templateName> ALIGNED? '(' <measurementId> <attributeClauses> [',' <measurementId> <attributeClauses>]+ ')'
 ```
 
 **Example 1:** Create a template containing two non-aligned timeseires

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 中使用方法为例，进行简要介绍。

docs/zh/UserGuide/Operate-Metadata/Template.md

@@ -30,7 +30,7 @@ IoTDB 支持元数据模板功能，实现同类型不同实体的物理量元
 创建元数据模板的 SQL 语法如下：
 
 ```sql
-CREATE SCHEMA? TEMPLATE <templateName> ALIGNED? '(' <measurementId> <attributeClauses> [',' <measurementId> <attributeClauses>]+ ')'
+CREATE SCHEMA TEMPLATE <templateName> ALIGNED? '(' <measurementId> <attributeClauses> [',' <measurementId> <attributeClauses>]+ ')'
 ```
 
 **示例1：** 创建包含两个非对齐序列的元数据模板

integration-test/src/test/java/org/apache/iotdb/db/it/IoTDBSyntaxConventionIdentifierIT.java

@@ -988,7 +988,7 @@ public void testTemplateName() {
         statement.execute(createTemplateSql);
       }
 
-      try (ResultSet resultSet = statement.executeQuery("SHOW TEMPLATES")) {
+      try (ResultSet resultSet = statement.executeQuery("SHOW SCHEMA TEMPLATES")) {
         Set<String> expectedResult = new HashSet<>(Arrays.asList(resultNames));
         while (resultSet.next()) {
           Assert.assertTrue(expectedResult.contains(resultSet.getString("TemplateName")));

integration-test/src/test/java/org/apache/iotdb/db/it/schema/IoTDBDeactivateTemplateIT.java

@@ -144,7 +144,7 @@ public void deactivateTemplateCrossSchemaRegionTest() throws Exception {
       }
     }
 
-    statement.execute("DEACTIVATE TEMPLATE FROM root.sg1.*");
+    statement.execute("DEACTIVATE SCHEMA TEMPLATE FROM root.sg1.*");
     try (ResultSet resultSet = statement.executeQuery("SELECT * FROM root.sg1.**")) {
       ResultSetMetaData resultSetMetaData = resultSet.getMetaData();
       Assert.assertEquals(1, resultSetMetaData.getColumnCount());
@@ -161,7 +161,7 @@ public void deactivateTemplateCrossStorageGroupTest() throws Exception {
       }
     }
 
-    statement.execute("DEACTIVATE TEMPLATE FROM root.*.d1");
+    statement.execute("DEACTIVATE SCHEMA TEMPLATE FROM root.*.d1");
     String[] retArray =
         new String[] {"1,1,1.0,1,1.0,", "2,2,2.0,2,2.0,", "3,3,3.0,3,3.0,", "4,4,4.0,4,4.0,"};
     int cnt = 0;
@@ -179,7 +179,7 @@ public void deactivateTemplateCrossStorageGroupTest() throws Exception {
       Assert.assertEquals(retArray.length, cnt);
     }
 
-    statement.execute("DEACTIVATE TEMPLATE FROM root.**, root.sg1.*");
+    statement.execute("DEACTIVATE SCHEMA TEMPLATE FROM root.**, root.sg1.*");
     try (ResultSet resultSet = statement.executeQuery("SELECT * FROM root.**")) {
       ResultSetMetaData resultSetMetaData = resultSet.getMetaData();
       Assert.assertEquals(1, resultSetMetaData.getColumnCount());
@@ -238,7 +238,7 @@ public void multiSyntaxTest() throws Exception {
       Assert.assertFalse(resultSet.next());
     }
 
-    statement.execute("DEACTIVATE TEMPLATE FROM root.**");
+    statement.execute("DEACTIVATE SCHEMA TEMPLATE FROM root.**");
     try (ResultSet resultSet = statement.executeQuery("SELECT * FROM root.**")) {
       ResultSetMetaData resultSetMetaData = resultSet.getMetaData();
       Assert.assertEquals(1, resultSetMetaData.getColumnCount());