You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iotdb.apache.org by hu...@apache.org on 2022/11/25 13:59:43 UTC
[iotdb] branch master updated: Split trigger doc into muitlple files for better display (#8169)
This is an automated email from the ASF dual-hosted git repository.
hui 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 53d69a7d33 Split trigger doc into muitlple files for better display (#8169)
53d69a7d33 is described below
commit 53d69a7d334f50a103e76a07b2cde5517f483abe
Author: Liao Lanyu <14...@qq.com>
AuthorDate: Fri Nov 25 21:59:38 2022 +0800
Split trigger doc into muitlple files for better display (#8169)
---
docs/UserGuide/Trigger/Configuration-Parameters.md | 29 +++
.../Triggers.md => Trigger/Implement-Trigger.md} | 201 ++-------------------
docs/UserGuide/Trigger/Instructions.md | 51 ++++++
docs/UserGuide/Trigger/Notes.md | 30 +++
docs/UserGuide/Trigger/Trigger-Management.md | 152 ++++++++++++++++
.../UserGuide/Trigger/Configuration-Parameters.md | 29 +++
.../Trigger/{Trigger.md => Implement-Trigger.md} | 198 ++------------------
docs/zh/UserGuide/Trigger/Instructions.md | 46 +++++
docs/zh/UserGuide/Trigger/Notes.md | 33 ++++
docs/zh/UserGuide/Trigger/Trigger-Management.md | 152 ++++++++++++++++
site/src/main/.vuepress/config.js | 20 +-
11 files changed, 571 insertions(+), 370 deletions(-)
diff --git a/docs/UserGuide/Trigger/Configuration-Parameters.md b/docs/UserGuide/Trigger/Configuration-Parameters.md
new file mode 100644
index 0000000000..9d49e0f684
--- /dev/null
+++ b/docs/UserGuide/Trigger/Configuration-Parameters.md
@@ -0,0 +1,29 @@
+<!--
+
+ 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.
+
+-->
+
+
+
+# Configuration Parameters
+
+| Parameter | Meaning |
+| ------------------------------------------------- | ------------------------------------------------------------ |
+| *trigger_lib_dir* | Directory to save the trigger jar package |
+| *stateful\_trigger\_retry\_num\_when\_not\_found* | How many times will we retry to found an instance of stateful trigger on DataNodes if not found |
\ No newline at end of file
diff --git a/docs/UserGuide/Process-Data/Triggers.md b/docs/UserGuide/Trigger/Implement-Trigger.md
similarity index 51%
rename from docs/UserGuide/Process-Data/Triggers.md
rename to docs/UserGuide/Trigger/Implement-Trigger.md
index cf99d4e679..4d0ff7d76d 100644
--- a/docs/UserGuide/Process-Data/Triggers.md
+++ b/docs/UserGuide/Trigger/Implement-Trigger.md
@@ -21,41 +21,11 @@
-# Triggers
-
-The trigger provides a mechanism for listening to changes in time series data. With user-defined logic, tasks such as alerting and data forwarding can be conducted.
-
-The trigger is implemented based on the reflection mechanism. Users can monitor data changes by implementing the Java interfaces. IoTDB allows users to dynamically register and drop triggers without restarting the server.
-
-The document will help you learn to define and manage triggers.
-
-
-
-## Instructions for use
-
-### Pattern for listening
-
-A single trigger can be used to listen for data changes in a time series that match a specific pattern. For example, a trigger can listen for the data changes of time series `root.sg.a`, or time series that match the pattern `root.sg.*`. When you register a trigger, you can specify the path pattern that the trigger listens on through an SQL statement.
-
-### Trigger Type
-
-There are currently two types of triggers, and you can specify the type through an SQL statement when registering a trigger:
-
-- Stateful triggers: The execution logic of this type of trigger may depend on data from multiple insertion statement . The framework will aggregate the data written by different nodes into the same trigger instance for calculation to retain context information. This type of trigger is usually used for sampling or statistical data aggregation for a period of time. information. Only one node in the cluster holds an instance of a stateful trigger.
-- Stateless triggers: The execution logic of the trigger is only related to the current input data. The framework does not need to aggregate the data of different nodes into the same trigger instance. This type of trigger is usually used for calculation of single row data and abnormal detection. Each node in the cluster holds an instance of a stateless trigger.
-
-### Trigger Event
-
-There are currently two trigger events for the trigger, and other trigger events will be expanded in the future. When you register a trigger, you can specify the trigger event through an SQL statement:
-
-- BEFORE INSERT: Fires before the data is persisted. **Please note that currently the trigger does not support data cleaning and will not change the data to be persisted itself.**
-- AFTER INSERT: Fires after the data is persisted.
-
-## How to implement a trigger
+# How to implement a trigger
You need to implement the trigger by writing a Java class, where the dependency shown below is required. If you use [Maven](http://search.maven.org/), you can search for them directly from the [Maven repository](http://search.maven.org/).
-### Dependency
+## Dependency
```xml
<dependency>
@@ -68,7 +38,7 @@ You need to implement the trigger by writing a Java class, where the dependency
Note that the dependency version should be correspondent to the target server version.
-### Interface Description
+## Interface Description
To implement a trigger, you need to implement the `org.apache.iotdb.trigger.api.Trigger` class.
@@ -137,18 +107,18 @@ This class provides two types of programming interfaces: **Lifecycle related int
Descriptions of the interfaces are as followed.
-#### Lifecycle related interfaces
+### Lifecycle related interfaces
-| Interface | Description [...]
-| ------------------------------------------------------------ |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [...]
-| *default void validate(TriggerAttributes attributes) throws Exception {}* | When you creates a trigger using the `CREATE TRIGGER` statement, you can specify the parameters that the trigger needs to use, and this interface will be used to verify the correctness of the parameters。 [...]
-| *default void onCreate(TriggerAttributes attributes) throws Exception {}* | This interface is called once when you create a trigger using the `CREATE TRIGGER` statement. During the lifetime of each trigger instance, this interface will be called only once. This interface is mainly used for the following functions: helping users to parse custom attributes in SQL statements (using `TriggerAttributes`). You can create or apply for resources, such as establishing external links, opening fi [...]
-| *default void onDrop() throws Exception {}* | This interface is called when you drop a trigger using the `DROP TRIGGER` statement. During the lifetime of each trigger instance, this interface will be called only once. This interface mainly has the following functions: it can perform the operation of resource release and can be used to persist the results of trigger calculations. [...]
+| Interface | Description |
+| ------------------------------------------------------------ | ------------------------------------------------------------ |
+| *default void validate(TriggerAttributes attributes) throws Exception {}* | When you creates a trigger using the `CREATE TRIGGER` statement, you can specify the parameters that the trigger needs to use, and this interface will be used to verify the correctness of the parameters。 |
+| *default void onCreate(TriggerAttributes attributes) throws Exception {}* | This interface is called once when you create a trigger using the `CREATE TRIGGER` statement. During the lifetime of each trigger instance, this interface will be called only once. This interface is mainly used for the following functions: helping users to parse custom attributes in SQL statements (using `TriggerAttributes`). You can create or apply for resources, such as establishing external links, opening fi [...]
+| *default void onDrop() throws Exception {}* | This interface is called when you drop a trigger using the `DROP TRIGGER` statement. During the lifetime of each trigger instance, this interface will be called only once. This interface mainly has the following functions: it can perform the operation of resource release and can be used to persist the results of trigger calculations. |
| *default void restore() throws Exception {}* | When the DataNode is restarted, the cluster will restore the trigger instance registered on the DataNode, and this interface will be called once for stateful trigger during the process. After the DataNode where the stateful trigger instance is located goes down, the cluster will restore the trigger instance on another available DataNode, calling this interface once in the process. This interface can be used to customize rec [...]
-#### Data change listening related interfaces
+### Data change listening related interfaces
-##### Listening interface
+#### Listening interface
```java
/**
@@ -193,7 +163,7 @@ The time series `root.sg.a` matches Trigger1 and Trigger2, and the sequence `roo
- The data of `root.sg.a` will be assembled into a new tablet2, and Trigger2.fire(tablet2) will be executed at the corresponding Trigger Event.
- The data of `root.sg.b` will be assembled into a new tablet3, and Trigger3.fire(tablet3) will be executed at the corresponding Trigger Event.
-##### Listening strategy interface
+#### Listening strategy interface
When the trigger fails to fire, we will take corresponding actions according to the strategy set by the listening strategy interface. You can set `org.apache.iotdb.trigger.api.enums.FailureStrategy`. There are currently two strategies, optimistic and pessimistic:
@@ -212,7 +182,7 @@ When the trigger fails to fire, we will take corresponding actions according to
}
```
-### Example
+## Example
If you use [Maven](http://search.maven.org/), you can refer to our sample project **trigger-example**.
@@ -322,148 +292,3 @@ public class ClusterAlertingExample implements Trigger {
}
```
-## Triggers Management
-
-You can create and drop a trigger through an SQL statement, and you can also query all registered triggers through an SQL statement.
-
-**We recommend that you stop insertion while creating triggers.**
-
-### Create Trigger
-
-Triggers can be registered on arbitrary path patterns. The time series registered with the trigger will be listened to by the trigger. When there is data change on the series, the corresponding fire method in the trigger will be called.
-
-Registering a trigger can be done as follows:
-
-1. Implement a Trigger class as described in the How to implement a Trigger chapter, assuming the class's full class name is `org.apache.iotdb.trigger.ClusterAlertingExample`
-2. Package the project into a JAR package.
-3. Register the trigger with an SQL statement. During the creation process, the `validate` and `onCreate` interfaces of the trigger will only be called once. For details, please refer to the chapter of How to implement a Trigger.
-
-The complete SQL syntax is as follows:
-
-```sql
-// Create Trigger
-createTrigger
- : CREATE triggerType TRIGGER triggerName=identifier triggerEventClause ON pathPattern AS className=STRING_LITERAL uriClause? triggerAttributeClause?
- ;
-
-triggerType
- : STATELESS | STATEFUL
- ;
-
-triggerEventClause
- : (BEFORE | AFTER) INSERT
- ;
-
-uriClause
- : USING URI uri
- ;
-
-uri
- : STRING_LITERAL
- ;
-
-triggerAttributeClause
- : WITH LR_BRACKET triggerAttribute (COMMA triggerAttribute)* RR_BRACKET
- ;
-
-triggerAttribute
- : key=attributeKey operator_eq value=attributeValue
- ;
-```
-
-Below is the explanation for the SQL syntax:
-
-- triggerName: The trigger ID, which is globally unique and used to distinguish different triggers, is case-sensitive.
-- triggerType: Trigger types are divided into two categories, STATELESS and STATEFUL.
-- triggerEventClause: when the trigger fires, BEFORE INSERT and AFTER INSERT are supported now.
-- pathPattern：The path pattern the trigger listens on, can contain wildcards * and **.
-- className：The class name of the Trigger class.
-- jarLocation: Optional. When this option is not specified, by default, we consider that the DBA has placed the JAR package required to create the trigger in the trigger_root_dir directory (configuration item, default is IOTDB_HOME/ext/trigger) of each DataNode node. When this option is specified, we will download and distribute the file resource corresponding to the URI to the trigger_root_dir/install directory of each DataNode.
-- triggerAttributeClause: It is used to specify the parameters that need to be set when the trigger instance is created. This part is optional in the SQL syntax.
-
-Here is an example SQL statement to help you understand:
-
-```sql
-CREATE STATELESS TRIGGER triggerTest
-BEFORE INSERT
-ON root.sg.**
-AS 'org.apache.iotdb.trigger.ClusterAlertingExample'
-USING URI '/jar/ClusterAlertingExample.jar'
-WITH (
- "name" = "trigger",
- "limit" = "100"
-)
-```
-
-The above SQL statement creates a trigger named triggerTest:
-
-- The trigger is stateless.
-- Fires before insertion.
-- Listens on path pattern root.sg.**
-- The implemented trigger class is named `org.apache.iotdb.trigger.ClusterAlertingExample`
-- The JAR package URI is http://jar/ClusterAlertingExample.jar
-- When creating the trigger instance, two parameters, name and limit, are passed in.
-
-### Drop Trigger
-
-The trigger can be dropped by specifying the trigger ID. During the process of dropping the trigger, the `onDrop` interface of the trigger will be called only once.
-
-The SQL syntax is:
-
-```sql
-// Drop Trigger
-dropTrigger
- : DROP TRIGGER triggerName=identifier
-;
-```
-
-Here is an example statement:
-
-```sql
-DROP TRIGGER triggerTest1
-```
-
-The above statement will drop the trigger with ID triggerTest1.
-
-### Show Trigger
-
-You can query information about triggers that exist in the cluster through an SQL statement.
-
-The SQL syntax is as follows:
-
-```sql
-SHOW TRIGGERS
-```
-
-The result set format of this statement is as follows:
-
-| TriggerName | Event | Type | State | PathPattern | ClassName | NodeId |
-| ------------ | ---------------------------- | -------------------- | ------------------------------------------- | ----------- | --------------------------------------- | --------------------------------------- |
-| triggerTest1 | BEFORE_INSERT / AFTER_INSERT | STATELESS / STATEFUL | INACTIVE / ACTIVE / DROPPING / TRANSFFERING | root.** | org.apache.iotdb.trigger.TriggerExample | ALL(STATELESS) / DATA_NODE_ID(STATEFUL) |
-
-### Trigger State
-
-During the process of creating and dropping triggers in the cluster, we maintain the states of the triggers. The following is a description of these states:
-
-| State | Description | Is it recommended to insert data? |
-| ------------ | ------------------------------------------------------------ | --------------------------------- |
-| INACTIVE | The intermediate state of executing `CREATE TRIGGER`, the cluster has just recorded the trigger information on the ConfigNode, and the trigger has not been activated on any DataNode. | NO |
-| ACTIVE | Status after successful execution of `CREATE TRIGGE`, the trigger is available on all DataNodes in the cluster. | YES |
-| DROPPING | Intermediate state of executing `DROP TRIGGER`, the cluster is in the process of dropping the trigger. | NO |
-| TRANSFERRING | The cluster is migrating the location of this trigger instance. | NO |
-
-## Notes
-
-- The trigger takes effect from the time of registration, and does not process the existing historical data. **That is, only insertion requests that occur after the trigger is successfully registered will be listened to by the trigger. **
-- The fire process of trigger is synchronous currently, so you need to ensure the efficiency of the trigger, otherwise the writing performance may be greatly affected. **You need to guarantee concurrency safety of triggers yourself**.
-- Please do no register too many triggers in the cluster. Because the trigger information is fully stored in the ConfigNode, and there is a copy of the information in all DataNodes
-- **It is recommended to stop writing when registering triggers**. Registering a trigger is not an atomic operation. When registering a trigger, there will be an intermediate state in which some nodes in the cluster have registered the trigger, and some nodes have not yet registered successfully. To avoid write requests on some nodes being listened to by triggers and not being listened to on some nodes, we recommend not to perform writes when registering triggers.
-- When the node holding the stateful trigger instance goes down, we will try to restore the corresponding instance on another node. During the recovery process, we will call the restore interface of the trigger class once.
-- The trigger JAR package has a size limit, which must be less than min(`config_node_ratis_log_appender_buffer_size_max`, 2G), where `config_node_ratis_log_appender_buffer_size_max` is a configuration item. For the specific meaning, please refer to the IOTDB configuration item description.
-- **It is better not to have classes with the same full class name but different function implementations in different JAR packages.** For example, trigger1 and trigger2 correspond to resources trigger1.jar and trigger2.jar respectively. If two JAR packages contain a `org.apache.iotdb.trigger.example.AlertListener` class, when `CREATE TRIGGER` uses this class, the system will randomly load the class in one of the JAR packages, which will eventually leads the inconsistent behavior of trig [...]
-
-## Configuration Parameters
-
-| Parameter | Meaning |
-| ----------------- | ----------------------------------------- |
-| *trigger_lib_dir* | Directory to save the trigger jar package |
diff --git a/docs/UserGuide/Trigger/Instructions.md b/docs/UserGuide/Trigger/Instructions.md
new file mode 100644
index 0000000000..3e4aed35b4
--- /dev/null
+++ b/docs/UserGuide/Trigger/Instructions.md
@@ -0,0 +1,51 @@
+<!--
+
+ 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.
+
+-->
+
+
+
+# Instructions
+
+The trigger provides a mechanism for listening to changes in time series data. With user-defined logic, tasks such as alerting and data forwarding can be conducted.
+
+The trigger is implemented based on the reflection mechanism. Users can monitor data changes by implementing the Java interfaces. IoTDB allows users to dynamically register and drop triggers without restarting the server.
+
+The document will help you learn to define and manage triggers.
+
+## Pattern for listening
+
+A single trigger can be used to listen for data changes in a time series that match a specific pattern. For example, a trigger can listen for the data changes of time series `root.sg.a`, or time series that match the pattern `root.sg.*`. When you register a trigger, you can specify the path pattern that the trigger listens on through an SQL statement.
+
+## Trigger Type
+
+There are currently two types of triggers, and you can specify the type through an SQL statement when registering a trigger:
+
+- Stateful triggers: The execution logic of this type of trigger may depend on data from multiple insertion statement . The framework will aggregate the data written by different nodes into the same trigger instance for calculation to retain context information. This type of trigger is usually used for sampling or statistical data aggregation for a period of time. information. Only one node in the cluster holds an instance of a stateful trigger.
+- Stateless triggers: The execution logic of the trigger is only related to the current input data. The framework does not need to aggregate the data of different nodes into the same trigger instance. This type of trigger is usually used for calculation of single row data and abnormal detection. Each node in the cluster holds an instance of a stateless trigger.
+
+## Trigger Event
+
+There are currently two trigger events for the trigger, and other trigger events will be expanded in the future. When you register a trigger, you can specify the trigger event through an SQL statement:
+
+- BEFORE INSERT: Fires before the data is persisted. **Please note that currently the trigger does not support data cleaning and will not change the data to be persisted itself.**
+- AFTER INSERT: Fires after the data is persisted.
+
+
+
diff --git a/docs/UserGuide/Trigger/Notes.md b/docs/UserGuide/Trigger/Notes.md
new file mode 100644
index 0000000000..77f282a0cb
--- /dev/null
+++ b/docs/UserGuide/Trigger/Notes.md
@@ -0,0 +1,30 @@
+<!--
+
+ 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.
+
+-->
+
+# Notes
+
+- The trigger takes effect from the time of registration, and does not process the existing historical data. **That is, only insertion requests that occur after the trigger is successfully registered will be listened to by the trigger. **
+- The fire process of trigger is synchronous currently, so you need to ensure the efficiency of the trigger, otherwise the writing performance may be greatly affected. **You need to guarantee concurrency safety of triggers yourself**.
+- Please do no register too many triggers in the cluster. Because the trigger information is fully stored in the ConfigNode, and there is a copy of the information in all DataNodes
+- **It is recommended to stop writing when registering triggers**. Registering a trigger is not an atomic operation. When registering a trigger, there will be an intermediate state in which some nodes in the cluster have registered the trigger, and some nodes have not yet registered successfully. To avoid write requests on some nodes being listened to by triggers and not being listened to on some nodes, we recommend not to perform writes when registering triggers.
+- When the node holding the stateful trigger instance goes down, we will try to restore the corresponding instance on another node. During the recovery process, we will call the restore interface of the trigger class once.
+- The trigger JAR package has a size limit, which must be less than min(`config_node_ratis_log_appender_buffer_size_max`, 2G), where `config_node_ratis_log_appender_buffer_size_max` is a configuration item. For the specific meaning, please refer to the IOTDB configuration item description.
+- **It is better not to have classes with the same full class name but different function implementations in different JAR packages.** For example, trigger1 and trigger2 correspond to resources trigger1.jar and trigger2.jar respectively. If two JAR packages contain a `org.apache.iotdb.trigger.example.AlertListener` class, when `CREATE TRIGGER` uses this class, the system will randomly load the class in one of the JAR packages, which will eventually leads the inconsistent behavior of trig [...]
\ No newline at end of file
diff --git a/docs/UserGuide/Trigger/Trigger-Management.md b/docs/UserGuide/Trigger/Trigger-Management.md
new file mode 100644
index 0000000000..0c555a47bb
--- /dev/null
+++ b/docs/UserGuide/Trigger/Trigger-Management.md
@@ -0,0 +1,152 @@
+<!--
+
+ 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.
+
+-->
+
+
+
+# Triggers Management
+
+You can create and drop a trigger through an SQL statement, and you can also query all registered triggers through an SQL statement.
+
+**We recommend that you stop insertion while creating triggers.**
+
+## Create Trigger
+
+Triggers can be registered on arbitrary path patterns. The time series registered with the trigger will be listened to by the trigger. When there is data change on the series, the corresponding fire method in the trigger will be called.
+
+Registering a trigger can be done as follows:
+
+1. Implement a Trigger class as described in the How to implement a Trigger chapter, assuming the class's full class name is `org.apache.iotdb.trigger.ClusterAlertingExample`
+2. Package the project into a JAR package.
+3. Register the trigger with an SQL statement. During the creation process, the `validate` and `onCreate` interfaces of the trigger will only be called once. For details, please refer to the chapter of How to implement a Trigger.
+
+The complete SQL syntax is as follows:
+
+```sql
+// Create Trigger
+createTrigger
+ : CREATE triggerType TRIGGER triggerName=identifier triggerEventClause ON pathPattern AS className=STRING_LITERAL uriClause? triggerAttributeClause?
+ ;
+
+triggerType
+ : STATELESS | STATEFUL
+ ;
+
+triggerEventClause
+ : (BEFORE | AFTER) INSERT
+ ;
+
+uriClause
+ : USING URI uri
+ ;
+
+uri
+ : STRING_LITERAL
+ ;
+
+triggerAttributeClause
+ : WITH LR_BRACKET triggerAttribute (COMMA triggerAttribute)* RR_BRACKET
+ ;
+
+triggerAttribute
+ : key=attributeKey operator_eq value=attributeValue
+ ;
+```
+
+Below is the explanation for the SQL syntax:
+
+- triggerName: The trigger ID, which is globally unique and used to distinguish different triggers, is case-sensitive.
+- triggerType: Trigger types are divided into two categories, STATELESS and STATEFUL.
+- triggerEventClause: when the trigger fires, BEFORE INSERT and AFTER INSERT are supported now.
+- pathPattern：The path pattern the trigger listens on, can contain wildcards * and **.
+- className：The class name of the Trigger class.
+- jarLocation: Optional. When this option is not specified, by default, we consider that the DBA has placed the JAR package required to create the trigger in the trigger_root_dir directory (configuration item, default is IOTDB_HOME/ext/trigger) of each DataNode node. When this option is specified, we will download and distribute the file resource corresponding to the URI to the trigger_root_dir/install directory of each DataNode.
+- triggerAttributeClause: It is used to specify the parameters that need to be set when the trigger instance is created. This part is optional in the SQL syntax.
+
+Here is an example SQL statement to help you understand:
+
+```sql
+CREATE STATELESS TRIGGER triggerTest
+BEFORE INSERT
+ON root.sg.**
+AS 'org.apache.iotdb.trigger.ClusterAlertingExample'
+USING URI '/jar/ClusterAlertingExample.jar'
+WITH (
+ "name" = "trigger",
+ "limit" = "100"
+)
+```
+
+The above SQL statement creates a trigger named triggerTest:
+
+- The trigger is stateless.
+- Fires before insertion.
+- Listens on path pattern root.sg.**
+- The implemented trigger class is named `org.apache.iotdb.trigger.ClusterAlertingExample`
+- The JAR package URI is http://jar/ClusterAlertingExample.jar
+- When creating the trigger instance, two parameters, name and limit, are passed in.
+
+## Drop Trigger
+
+The trigger can be dropped by specifying the trigger ID. During the process of dropping the trigger, the `onDrop` interface of the trigger will be called only once.
+
+The SQL syntax is:
+
+```sql
+// Drop Trigger
+dropTrigger
+ : DROP TRIGGER triggerName=identifier
+;
+```
+
+Here is an example statement:
+
+```sql
+DROP TRIGGER triggerTest1
+```
+
+The above statement will drop the trigger with ID triggerTest1.
+
+## Show Trigger
+
+You can query information about triggers that exist in the cluster through an SQL statement.
+
+The SQL syntax is as follows:
+
+```sql
+SHOW TRIGGERS
+```
+
+The result set format of this statement is as follows:
+
+| TriggerName | Event | Type | State | PathPattern | ClassName | NodeId |
+| ------------ | ---------------------------- | -------------------- | ------------------------------------------- | ----------- | --------------------------------------- | --------------------------------------- |
+| triggerTest1 | BEFORE_INSERT / AFTER_INSERT | STATELESS / STATEFUL | INACTIVE / ACTIVE / DROPPING / TRANSFFERING | root.** | org.apache.iotdb.trigger.TriggerExample | ALL(STATELESS) / DATA_NODE_ID(STATEFUL) |
+
+## Trigger State
+
+During the process of creating and dropping triggers in the cluster, we maintain the states of the triggers. The following is a description of these states:
+
+| State | Description | Is it recommended to insert data? |
+| ------------ | ------------------------------------------------------------ | --------------------------------- |
+| INACTIVE | The intermediate state of executing `CREATE TRIGGER`, the cluster has just recorded the trigger information on the ConfigNode, and the trigger has not been activated on any DataNode. | NO |
+| ACTIVE | Status after successful execution of `CREATE TRIGGE`, the trigger is available on all DataNodes in the cluster. | YES |
+| DROPPING | Intermediate state of executing `DROP TRIGGER`, the cluster is in the process of dropping the trigger. | NO |
+| TRANSFERRING | The cluster is migrating the location of this trigger instance. | NO |
diff --git a/docs/zh/UserGuide/Trigger/Configuration-Parameters.md b/docs/zh/UserGuide/Trigger/Configuration-Parameters.md
new file mode 100644
index 0000000000..4e47a6a28e
--- /dev/null
+++ b/docs/zh/UserGuide/Trigger/Configuration-Parameters.md
@@ -0,0 +1,29 @@
+<!--
+
+ 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.
+
+-->
+
+
+
+# 配置参数
+
+| 配置项 | 含义 |
+| ------------------------------------------------- | ---------------------------------------------- |
+| *trigger_lib_dir* | 保存触发器 jar 包的目录位置 |
+| *stateful\_trigger\_retry\_num\_when\_not\_found* | 有状态触发器触发无法找到触发器实例时的重试次数 |
\ No newline at end of file
diff --git a/docs/zh/UserGuide/Trigger/Trigger.md b/docs/zh/UserGuide/Trigger/Implement-Trigger.md
similarity index 51%
rename from docs/zh/UserGuide/Trigger/Trigger.md
rename to docs/zh/UserGuide/Trigger/Implement-Trigger.md
index e5da136b6d..42b09a66aa 100644
--- a/docs/zh/UserGuide/Trigger/Trigger.md
+++ b/docs/zh/UserGuide/Trigger/Implement-Trigger.md
@@ -19,33 +19,11 @@
-->
-# 触发器
-触发器提供了一种侦听序列数据变动的机制。配合用户自定义逻辑，可完成告警、数据转发等功能。
-触发器基于 Java 反射机制实现。用户通过简单实现 Java 接口，即可实现数据侦听。IoTDB 允许用户动态注册、卸载触发器，在注册、卸载期间，无需启停服务器。
+# 编写触发器
-## 使用说明
-
-### 侦听模式
-
-IoTDB 的单个触发器可用于侦听符合特定模式的时间序列的数据变动，如时间序列 root.sg.a 上的数据变动，或者符合路径模式 root.**.a 的时间序列上的数据变动。您在注册触发器时可以通过 SQL 语句指定触发器侦听的路径模式。
-
-### 触发器类型
-
-目前触发器分为两类，您在注册触发器时可以通过 SQL 语句指定类型：
-- 有状态的触发器。该类触发器的执行逻辑可能依赖前后的多条数据，框架会将不同节点写入的数据汇总到同一个触发器实例进行计算，来保留上下文信息，通常用于采样或者统计一段时间的数据聚合信息。集群中只有一个节点持有有状态触发器的实例。
-- 无状态的触发器。触发器的执行逻辑只和当前输入的数据有关，框架无需将不同节点的数据汇总到同一个触发器实例中，通常用于单行数据的计算和异常检测等。集群中每个节点均持有无状态触发器的实例。
-
-### 触发时机
-
-触发器的触发时机目前有两种，后续会拓展其它触发时机。您在注册触发器时可以通过 SQL 语句指定触发时机：
-- BEFORE INSERT，即在数据持久化之前触发。请注意，目前触发器并不支持数据清洗，不会对要持久化的数据本身进行变动。
-- AFTER INSERT，即在数据持久化之后触发。
-
-## 编写触发器
-
-### 触发器依赖
+## 触发器依赖
触发器的逻辑需要您编写 Java 类进行实现。
在编写触发器逻辑时，需要使用到下面展示的依赖。如果您使用 [Maven](http://search.maven.org/)，则可以直接从 [Maven 库](http://search.maven.org/)中搜索到它们。请注意选择和目标服务器版本相同的依赖版本。
@@ -59,7 +37,7 @@ IoTDB 的单个触发器可用于侦听符合特定模式的时间序列的数
</dependency>
```
-### 接口说明
+## 接口说明
编写一个触发器需要实现 `org.apache.iotdb.trigger.api.Trigger` 类。
@@ -128,18 +106,18 @@ public interface Trigger {
下面是所有可供用户进行实现的接口的说明。
-#### 生命周期相关接口
+### 生命周期相关接口
-| 接口定义 | 描述 |
-|-------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| *default void validate(TriggerAttributes attributes) throws Exception {}* | 用户在使用 `CREATE TRIGGER` 语句创建触发器时，可以指定触发器需要使用的参数，该接口会用于验证参数正确性。 |
-| *default void onCreate(TriggerAttributes attributes) throws Exception {}* | 当您使用`CREATE TRIGGER`语句创建触发器后，该接口会被调用一次。在每一个触发器实例的生命周期内，该接口会且仅会被调用一次。该接口主要有如下作用：帮助用户解析 SQL 语句中的自定义属性（使用`TriggerAttributes`）。 可以创建或申请资源，如建立外部链接、打开文件等。 |
-| *default void onDrop() throws Exception {}* | 当您使用`DROP TRIGGER`语句删除触发器后，该接口会被调用。在每一个触发器实例的生命周期内，该接口会且仅会被调用一次。该接口主要有如下作用：可以进行资源释放的操作。可以用于持久化触发器计算的结果。 |
-| *default void restore() throws Exception {}* | 当重启 DataNode 时，集群会恢复 DataNode 上已经注册的触发器实例，在此过程中会为该 DataNode 上的有状态触发器调用一次该接口。有状态触发器实例所在的 DataNode 宕机后，集群会在另一个可用 DataNode 上恢复该触发器的实例，在此过程中会调用一次该接口。该接口可以用于自定义恢复逻辑。 |
+| 接口定义 | 描述 |
+| ------------------------------------------------------------ | ------------------------------------------------------------ |
+| *default void validate(TriggerAttributes attributes) throws Exception {}* | 用户在使用 `CREATE TRIGGER` 语句创建触发器时，可以指定触发器需要使用的参数，该接口会用于验证参数正确性。 |
+| *default void onCreate(TriggerAttributes attributes) throws Exception {}* | 当您使用`CREATE TRIGGER`语句创建触发器后，该接口会被调用一次。在每一个触发器实例的生命周期内，该接口会且仅会被调用一次。该接口主要有如下作用：帮助用户解析 SQL 语句中的自定义属性（使用`TriggerAttributes`）。 可以创建或申请资源，如建立外部链接、打开文件等。 |
+| *default void onDrop() throws Exception {}* | 当您使用`DROP TRIGGER`语句删除触发器后，该接口会被调用。在每一个触发器实例的生命周期内，该接口会且仅会被调用一次。该接口主要有如下作用：可以进行资源释放的操作。可以用于持久化触发器计算的结果。 |
+| *default void restore() throws Exception {}* | 当重启 DataNode 时，集群会恢复 DataNode 上已经注册的触发器实例，在此过程中会为该 DataNode 上的有状态触发器调用一次该接口。有状态触发器实例所在的 DataNode 宕机后，集群会在另一个可用 DataNode 上恢复该触发器的实例，在此过程中会调用一次该接口。该接口可以用于自定义恢复逻辑。 |
-#### 数据变动侦听相关接口
+### 数据变动侦听相关接口
-##### 侦听接口
+#### 侦听接口
```java
/**
@@ -157,6 +135,7 @@ public interface Trigger {
数据变动时，触发器以 Tablet 作为触发操作的单位。您可以通过 Tablet 获取相应序列的元数据和数据，然后进行相应的触发操作，触发成功则返回值应当为 true。该接口返回 false 或是抛出异常我们均认为触发失败。在触发失败时，我们会根据侦听策略接口进行相应的操作。
进行一次 INSERT 操作时，对于其中的每条时间序列，我们会检测是否有侦听该路径模式的触发器，然后将符合同一个触发器所侦听的路径模式的时间序列数据组装成一个新的 Tablet 用于触发器的 fire 接口。可以理解成：
+
```java
Map<PartialPath, List<Trigger>> pathToTriggerListMap => Map<Trigger, Tablet>
```
@@ -166,24 +145,27 @@ Map<PartialPath, List<Trigger>> pathToTriggerListMap => Map<Trigger, Tablet>
下面是示例：
假设有三个触发器，触发器的触发时机均为 BEFORE INSERT
+
- 触发器 Trigger1 侦听路径模式：root.sg.*
- 触发器 Trigger2 侦听路径模式：root.sg.a
- 触发器 Trigger3 侦听路径模式：root.sg.b
-
写入语句：
+
```sql
insert into root.sg(time, a, b) values (1, 1, 1);
```
序列 root.sg.a 匹配 Trigger1 和 Trigger2，序列 root.sg.b 匹配 Trigger1 和 Trigger3，那么：
+
- root.sg.a 和 root.sg.b 的数据会被组装成一个新的 tablet1，在相应的触发时机进行 Trigger1.fire(tablet1)
- root.sg.a 的数据会被组装成一个新的 tablet2，在相应的触发时机进行 Trigger2.fire(tablet2)
- root.sg.b 的数据会被组装成一个新的 tablet3，在相应的触发时机进行 Trigger3.fire(tablet3)
-##### 侦听策略接口
+#### 侦听策略接口
在触发器触发失败时，我们会根据侦听策略接口设置的策略进行相应的操作，您可以通过下述接口设置 `org.apache.iotdb.trigger.api.enums.FailureStrategy`，目前有乐观和悲观两种策略：
+
- 乐观策略：触发失败的触发器不影响后续触发器的触发，也不影响写入流程，即我们不对触发失败涉及的序列做额外处理，仅打日志记录失败，最后返回用户写入数据成功，但触发部分失败。
- 悲观策略：失败触发器影响后续所有 Pipeline 的处理，即我们认为该 Trigger 触发失败会导致后续所有触发流程不再进行。如果该触发器的触发时机为 BEFORE INSERT，那么写入也不再进行，直接返回写入失败。
@@ -206,7 +188,7 @@ insert into root.sg(time, a, b) values (1, 1, 1);
<img src="https://github.com/apache/iotdb-bin-resources/blob/main/docs/UserGuide/Process-Data/Triggers/Trigger_Process_Strategy.jpg?raw=true">
-### 示例
+## 示例
如果您使用 [Maven](http://search.maven.org/)，可以参考我们编写的示例项目 trigger-example。您可以在 [这里](https://github.com/apache/iotdb/tree/master/example/trigger) 找到它。后续我们会加入更多的示例项目供您参考。
@@ -313,145 +295,3 @@ public class ClusterAlertingExample implements Trigger {
}
}
```
-
-## 管理触发器
-
-您可以通过 SQL 语句注册和卸载一个触发器实例，您也可以通过 SQL 语句查询到所有已经注册的触发器。
-
-**我们建议您在注册触发器时停止写入。**
-
-### 注册触发器
-
-触发器可以注册在任意路径模式上。被注册有触发器的序列将会被触发器侦听，当序列上有数据变动时，触发器中对应的触发方法将会被调用。
-
-注册一个触发器可以按如下流程进行：
-1. 按照编写触发器章节的说明，实现一个完整的 Trigger 类，假定这个类的全类名为 `org.apache.iotdb.trigger.ClusterAlertingExample`
-2. 将项目打成 JAR 包。
-3. 使用 SQL 语句注册该触发器。注册过程中会仅只会调用一次触发器的 `validate` 和 `onCreate` 接口，具体请参考编写触发器章节。
-
-
-完整 SQL 语法如下：
-```sql
-// Create Trigger
-createTrigger
- : CREATE triggerType TRIGGER triggerName=identifier triggerEventClause ON pathPattern AS className=STRING_LITERAL uriClause? triggerAttributeClause?
- ;
-
-triggerType
- : STATELESS | STATEFUL
- ;
-
-triggerEventClause
- : (BEFORE | AFTER) INSERT
- ;
-
-uriClause
- : USING URI uri
- ;
-
-uri
- : STRING_LITERAL
- ;
-
-triggerAttributeClause
- : WITH LR_BRACKET triggerAttribute (COMMA triggerAttribute)* RR_BRACKET
- ;
-
-triggerAttribute
- : key=attributeKey operator_eq value=attributeValue
- ;
-```
-
-下面对 SQL 语法进行说明，您可以结合使用说明章节进行理解：
-- triggerName：触发器 ID，该 ID 是全局唯一的，用于区分不同触发器，大小写敏感。
-- triggerType：触发器类型，分为无状态（STATELESS）和有状态（STATEFUL）两类。
-- triggerEventClause：触发时机，目前仅支持写入前（BEFORE INSERT）和写入后（AFTER INSERT）两种。
-- pathPattern：触发器侦听的路径模式，可以包含通配符 * 和 **。
-- className：触发器实现类的类名。
-- uriClause：可选项，当不指定该选项时，我们默认 DBA 已经在各个 DataNode 节点的 trigger_root_dir 目录（配置项，默认为 IOTDB_HOME/ext/trigger）下放置好创建该触发器需要的 JAR 包。当指定该选项时，我们会将该 URI 对应的文件资源下载并分发到各 DataNode 的 trigger_root_dir/install 目录下。
-- triggerAttributeClause：用于指定触发器实例创建时需要设置的参数，SQL 语法中该部分是可选项。
-
-
-下面是一个帮助您理解的 SQL 语句示例：
-```sql
-CREATE STATELESS TRIGGER triggerTest
-BEFORE INSERT
-ON root.sg.**
-AS 'org.apache.iotdb.trigger.ClusterAlertingExample'
-USING URI 'http://jar/ClusterAlertingExample.jar'
-WITH (
- "name" = "trigger",
- "limit" = "100"
-)
-```
-
-上述 SQL 语句创建了一个名为 triggerTest 的触发器：
-- 该触发器是无状态的（STATELESS）
-- 在写入前触发（BEFORE INSERT）
-- 该触发器侦听路径模式为 root.sg.**
-- 所编写的触发器类名为 org.apache.iotdb.trigger.ClusterAlertingExample
-- JAR 包的 URI 为 http://jar/ClusterAlertingExample.jar
-- 创建该触发器实例时会传入 name 和 limit 两个参数。
-
-### 卸载触发器
-
-可以通过指定触发器 ID 的方式卸载触发器，卸载触发器的过程中会且仅会调用一次触发器的 `onDrop` 接口。
-
-卸载触发器的 SQL 语法如下：
-```sql
-// Drop Trigger
-dropTrigger
- : DROP TRIGGER triggerName=identifier
-;
-```
-
-下面是示例语句：
-```sql
-DROP TRIGGER triggerTest1
-```
-
-上述语句将会卸载 ID 为 triggerTest1 的触发器。
-
-### 查询触发器
-
-可以通过 SQL 语句查询集群中存在的触发器的信息。SQL 语法如下：
-```sql
-SHOW TRIGGERS
-```
-
-该语句的结果集格式如下：
-
-| TriggerName | Event | Type | State | PathPattern | ClassName | NodeId |
-| ------------ |------------------------------|----------------------|---------------------------------------------| ----------- | --------------------------------------- |-----------------------------------------|
-| triggerTest1 | BEFORE_INSERT / AFTER_INSERT | STATELESS / STATEFUL | INACTIVE / ACTIVE / DROPPING / TRANSFFERING | root.** | org.apache.iotdb.trigger.TriggerExample | ALL(STATELESS) / DATA_NODE_ID(STATEFUL) |
-
-
-### 触发器状态说明
-
-在集群中注册以及卸载触发器的过程中，我们维护了触发器的状态，下面是对这些状态的说明：
-
-| 状态 | 描述 | 是否建议写入进行 |
-| ------------ | ------------------------------------------------------------ | ---------------- |
-| INACTIVE | 执行 `CREATE TRIGGER` 的中间状态，集群刚在 ConfigNode 上记录该触发器的信息，还未在任何 DataNode 上激活该触发器 | 否 |
-| ACTIVE | 执行 `CREATE TRIGGE` 成功后的状态，集群所有 DataNode 上的该触发器都已经可用 | 是 |
-| DROPPING | 执行 `DROP TRIGGER` 的中间状态，集群正处在卸载该触发器的过程中 | 否 |
-| TRANSFERRING | 集群正在进行该触发器实例位置的迁移 | 否 |
-
-
-## 重要注意事项
-
-- 触发器从注册时开始生效，不对已有的历史数据进行处理。**即只有成功注册触发器之后发生的写入请求才会被触发器侦听到。**
-- 触发器目前采用**同步触发**，所以编写时需要保证触发器效率，否则可能会大幅影响写入性能。**您需要自己保证触发器内部的并发安全性**。
-- 集群中**不能注册过多触发器**。因为触发器信息全量保存在 ConfigNode 中，并且在所有 DataNode 都有一份该信息的副本。
-- **建议注册触发器时停止写入**。注册触发器并不是一个原子操作，注册触发器时，会出现集群内部分节点已经注册了该触发器，部分节点尚未注册成功的中间状态。为了避免部分节点上的写入请求被触发器侦听到，部分节点上没有被侦听到的情况，我们建议注册触发器时不要执行写入。
-- 触发器将作为进程内程序执行，如果您的触发器编写不慎，内存占用过多，由于 IoTDB 并没有办法监控触发器所使用的内存，所以有 OOM 的风险。
-- 持有有状态触发器实例的节点宕机时，我们会尝试在另外的节点上恢复相应实例，在恢复过程中我们会调用一次触发器类的 restore 接口，您可以在该接口中实现恢复触发器所维护的状态的逻辑。
-- 触发器 JAR 包有大小限制，必须小于 min(`config_node_ratis_log_appender_buffer_size_max`, 2G)，其中 `config_node_ratis_log_appender_buffer_size_max` 是一个配置项，具体含义可以参考 IOTDB 配置项说明。
-- **不同的 JAR 包中最好不要有全类名相同但功能实现不一样的类**。例如：触发器 trigger1、trigger2 分别对应资源 trigger1.jar、trigger2.jar。如果两个 JAR 包里都包含一个 `org.apache.iotdb.trigger.example.AlertListener` 类，当 `CREATE TRIGGER` 使用到这个类时，系统会随机加载其中一个 JAR 包中的类，最终导致触发器执行行为不一致以及其他的问题。
-
-## 配置参数
-
-| 配置项 | 含义 |
-| ----------------- | --------------------------- |
-| *trigger_lib_dir* | 保存触发器 jar 包的目录位置 |
-
diff --git a/docs/zh/UserGuide/Trigger/Instructions.md b/docs/zh/UserGuide/Trigger/Instructions.md
new file mode 100644
index 0000000000..d3fb7f88e9
--- /dev/null
+++ b/docs/zh/UserGuide/Trigger/Instructions.md
@@ -0,0 +1,46 @@
+<!--
+
+ 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.
+
+-->
+
+
+
+# 使用说明
+
+触发器提供了一种侦听序列数据变动的机制。配合用户自定义逻辑，可完成告警、数据转发等功能。
+
+触发器基于 Java 反射机制实现。用户通过简单实现 Java 接口，即可实现数据侦听。IoTDB 允许用户动态注册、卸载触发器，在注册、卸载期间，无需启停服务器。
+
+## 侦听模式
+
+IoTDB 的单个触发器可用于侦听符合特定模式的时间序列的数据变动，如时间序列 root.sg.a 上的数据变动，或者符合路径模式 root.**.a 的时间序列上的数据变动。您在注册触发器时可以通过 SQL 语句指定触发器侦听的路径模式。
+
+## 触发器类型
+
+目前触发器分为两类，您在注册触发器时可以通过 SQL 语句指定类型：
+
+- 有状态的触发器。该类触发器的执行逻辑可能依赖前后的多条数据，框架会将不同节点写入的数据汇总到同一个触发器实例进行计算，来保留上下文信息，通常用于采样或者统计一段时间的数据聚合信息。集群中只有一个节点持有有状态触发器的实例。
+- 无状态的触发器。触发器的执行逻辑只和当前输入的数据有关，框架无需将不同节点的数据汇总到同一个触发器实例中，通常用于单行数据的计算和异常检测等。集群中每个节点均持有无状态触发器的实例。
+
+## 触发时机
+
+触发器的触发时机目前有两种，后续会拓展其它触发时机。您在注册触发器时可以通过 SQL 语句指定触发时机：
+
+- BEFORE INSERT，即在数据持久化之前触发。请注意，目前触发器并不支持数据清洗，不会对要持久化的数据本身进行变动。
+- AFTER INSERT，即在数据持久化之后触发。
diff --git a/docs/zh/UserGuide/Trigger/Notes.md b/docs/zh/UserGuide/Trigger/Notes.md
new file mode 100644
index 0000000000..153fb16e36
--- /dev/null
+++ b/docs/zh/UserGuide/Trigger/Notes.md
@@ -0,0 +1,33 @@
+<!--
+
+ 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.
+
+-->
+
+
+
+# 重要注意事项
+
+- 触发器从注册时开始生效，不对已有的历史数据进行处理。**即只有成功注册触发器之后发生的写入请求才会被触发器侦听到。**
+- 触发器目前采用**同步触发**，所以编写时需要保证触发器效率，否则可能会大幅影响写入性能。**您需要自己保证触发器内部的并发安全性**。
+- 集群中**不能注册过多触发器**。因为触发器信息全量保存在 ConfigNode 中，并且在所有 DataNode 都有一份该信息的副本。
+- **建议注册触发器时停止写入**。注册触发器并不是一个原子操作，注册触发器时，会出现集群内部分节点已经注册了该触发器，部分节点尚未注册成功的中间状态。为了避免部分节点上的写入请求被触发器侦听到，部分节点上没有被侦听到的情况，我们建议注册触发器时不要执行写入。
+- 触发器将作为进程内程序执行，如果您的触发器编写不慎，内存占用过多，由于 IoTDB 并没有办法监控触发器所使用的内存，所以有 OOM 的风险。
+- 持有有状态触发器实例的节点宕机时，我们会尝试在另外的节点上恢复相应实例，在恢复过程中我们会调用一次触发器类的 restore 接口，您可以在该接口中实现恢复触发器所维护的状态的逻辑。
+- 触发器 JAR 包有大小限制，必须小于 min(`config_node_ratis_log_appender_buffer_size_max`, 2G)，其中 `config_node_ratis_log_appender_buffer_size_max` 是一个配置项，具体含义可以参考 IOTDB 配置项说明。
+- **不同的 JAR 包中最好不要有全类名相同但功能实现不一样的类**。例如：触发器 trigger1、trigger2 分别对应资源 trigger1.jar、trigger2.jar。如果两个 JAR 包里都包含一个 `org.apache.iotdb.trigger.example.AlertListener` 类，当 `CREATE TRIGGER` 使用到这个类时，系统会随机加载其中一个 JAR 包中的类，最终导致触发器执行行为不一致以及其他的问题。
\ No newline at end of file
diff --git a/docs/zh/UserGuide/Trigger/Trigger-Management.md b/docs/zh/UserGuide/Trigger/Trigger-Management.md
new file mode 100644
index 0000000000..d0faa3ed25
--- /dev/null
+++ b/docs/zh/UserGuide/Trigger/Trigger-Management.md
@@ -0,0 +1,152 @@
+<!--
+
+ 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.
+
+-->
+
+
+
+# 管理触发器
+
+您可以通过 SQL 语句注册和卸载一个触发器实例，您也可以通过 SQL 语句查询到所有已经注册的触发器。
+
+**我们建议您在注册触发器时停止写入。**
+
+## 注册触发器
+
+触发器可以注册在任意路径模式上。被注册有触发器的序列将会被触发器侦听，当序列上有数据变动时，触发器中对应的触发方法将会被调用。
+
+注册一个触发器可以按如下流程进行：
+
+1. 按照编写触发器章节的说明，实现一个完整的 Trigger 类，假定这个类的全类名为 `org.apache.iotdb.trigger.ClusterAlertingExample`
+2. 将项目打成 JAR 包。
+3. 使用 SQL 语句注册该触发器。注册过程中会仅只会调用一次触发器的 `validate` 和 `onCreate` 接口，具体请参考编写触发器章节。
+
+完整 SQL 语法如下：
+
+```sql
+// Create Trigger
+createTrigger
+ : CREATE triggerType TRIGGER triggerName=identifier triggerEventClause ON pathPattern AS className=STRING_LITERAL uriClause? triggerAttributeClause?
+ ;
+
+triggerType
+ : STATELESS | STATEFUL
+ ;
+
+triggerEventClause
+ : (BEFORE | AFTER) INSERT
+ ;
+
+uriClause
+ : USING URI uri
+ ;
+
+uri
+ : STRING_LITERAL
+ ;
+
+triggerAttributeClause
+ : WITH LR_BRACKET triggerAttribute (COMMA triggerAttribute)* RR_BRACKET
+ ;
+
+triggerAttribute
+ : key=attributeKey operator_eq value=attributeValue
+ ;
+```
+
+下面对 SQL 语法进行说明，您可以结合使用说明章节进行理解：
+
+- triggerName：触发器 ID，该 ID 是全局唯一的，用于区分不同触发器，大小写敏感。
+- triggerType：触发器类型，分为无状态（STATELESS）和有状态（STATEFUL）两类。
+- triggerEventClause：触发时机，目前仅支持写入前（BEFORE INSERT）和写入后（AFTER INSERT）两种。
+- pathPattern：触发器侦听的路径模式，可以包含通配符 * 和 **。
+- className：触发器实现类的类名。
+- uriClause：可选项，当不指定该选项时，我们默认 DBA 已经在各个 DataNode 节点的 trigger_root_dir 目录（配置项，默认为 IOTDB_HOME/ext/trigger）下放置好创建该触发器需要的 JAR 包。当指定该选项时，我们会将该 URI 对应的文件资源下载并分发到各 DataNode 的 trigger_root_dir/install 目录下。
+- triggerAttributeClause：用于指定触发器实例创建时需要设置的参数，SQL 语法中该部分是可选项。
+
+下面是一个帮助您理解的 SQL 语句示例：
+
+```sql
+CREATE STATELESS TRIGGER triggerTest
+BEFORE INSERT
+ON root.sg.**
+AS 'org.apache.iotdb.trigger.ClusterAlertingExample'
+USING URI 'http://jar/ClusterAlertingExample.jar'
+WITH (
+ "name" = "trigger",
+ "limit" = "100"
+)
+```
+
+上述 SQL 语句创建了一个名为 triggerTest 的触发器：
+
+- 该触发器是无状态的（STATELESS）
+- 在写入前触发（BEFORE INSERT）
+- 该触发器侦听路径模式为 root.sg.**
+- 所编写的触发器类名为 org.apache.iotdb.trigger.ClusterAlertingExample
+- JAR 包的 URI 为 http://jar/ClusterAlertingExample.jar
+- 创建该触发器实例时会传入 name 和 limit 两个参数。
+
+## 卸载触发器
+
+可以通过指定触发器 ID 的方式卸载触发器，卸载触发器的过程中会且仅会调用一次触发器的 `onDrop` 接口。
+
+卸载触发器的 SQL 语法如下：
+
+```sql
+// Drop Trigger
+dropTrigger
+ : DROP TRIGGER triggerName=identifier
+;
+```
+
+下面是示例语句：
+
+```sql
+DROP TRIGGER triggerTest1
+```
+
+上述语句将会卸载 ID 为 triggerTest1 的触发器。
+
+## 查询触发器
+
+可以通过 SQL 语句查询集群中存在的触发器的信息。SQL 语法如下：
+
+```sql
+SHOW TRIGGERS
+```
+
+该语句的结果集格式如下：
+
+| TriggerName | Event | Type | State | PathPattern | ClassName | NodeId |
+| ------------ | ---------------------------- | -------------------- | ------------------------------------------- | ----------- | --------------------------------------- | --------------------------------------- |
+| triggerTest1 | BEFORE_INSERT / AFTER_INSERT | STATELESS / STATEFUL | INACTIVE / ACTIVE / DROPPING / TRANSFFERING | root.** | org.apache.iotdb.trigger.TriggerExample | ALL(STATELESS) / DATA_NODE_ID(STATEFUL) |
+
+
+## 触发器状态说明
+
+在集群中注册以及卸载触发器的过程中，我们维护了触发器的状态，下面是对这些状态的说明：
+
+| 状态 | 描述 | 是否建议写入进行 |
+| ------------ | ------------------------------------------------------------ | ---------------- |
+| INACTIVE | 执行 `CREATE TRIGGER` 的中间状态，集群刚在 ConfigNode 上记录该触发器的信息，还未在任何 DataNode 上激活该触发器 | 否 |
+| ACTIVE | 执行 `CREATE TRIGGE` 成功后的状态，集群所有 DataNode 上的该触发器都已经可用 | 是 |
+| DROPPING | 执行 `DROP TRIGGER` 的中间状态，集群正处在卸载该触发器的过程中 | 否 |
+| TRANSFERRING | 集群正在进行该触发器实例位置的迁移 | 否 |
+
diff --git a/site/src/main/.vuepress/config.js b/site/src/main/.vuepress/config.js
index 0033ba3865..d6bb3a0bde 100644
--- a/site/src/main/.vuepress/config.js
+++ b/site/src/main/.vuepress/config.js
@@ -938,8 +938,18 @@ var config = {
children: [
['Process-Data/UDF-User-Defined-Function','UDF (User Defined Function)'],
['Process-Data/Select-Into','Query Write-back (SELECT INTO)'],
- ['Process-Data/Continuous-Query','CQ (Continuous Query)'],
- ['Process-Data/Triggers','Triggers'],
+ ['Process-Data/Continuous-Query','CQ (Continuous Query)']
+ ]
+ },
+ {
+ title: 'Trigger',
+ sidebarDepth: 1,
+ children: [
+ ['Trigger/Instructions','Instructions'],
+ ['Trigger/Implement-Trigger','How to implement a trigger'],
+ ['Trigger/Trigger-Management','Trigger Management'],
+ ['Trigger/Notes','Notes'],
+ ['Trigger/Configuration-Parameters','Configuration-Parameters'],
]
},
{
@@ -1925,7 +1935,11 @@ var config = {
title: '触发器',
sidebarDepth: 1,
children: [
- ['Trigger/Trigger','触发器'],
+ ['Trigger/Instructions','使用说明'],
+ ['Trigger/Implement-Trigger','编写触发器'],
+ ['Trigger/Trigger-Management','管理触发器'],
+ ['Trigger/Notes','重要注意事项'],
+ ['Trigger/Configuration-Parameters','配置参数'],
]
},
{