Merge pull request #20324 from taosdata/docs/wade-event-window

docs: add event window

docs/en/12-taos-sql/12-distinguished.md

@@ -32,15 +32,15 @@ The most common usage of PARTITION BY is partitioning the data in subtables by t
 
 ## Windowed Queries
 
-Aggregation by time window is supported in TDengine. For example, in the case where temperature sensors report the temperature every seconds, the average temperature for every 10 minutes can be retrieved by performing a query with a time window. Window related clauses are used to divide the data set to be queried into subsets and then aggregation is performed across the subsets. There are three kinds of windows: time window, status window, and session window. There are two kinds of time windows: sliding window and flip time/tumbling window. The query syntax is as follows:
+Aggregation by time window is supported in TDengine. For example, in the case where temperature sensors report the temperature every seconds, the average temperature for every 10 minutes can be retrieved by performing a query with a time window. Window related clauses are used to divide the data set to be queried into subsets and then aggregation is performed across the subsets. There are four kinds of windows: time window, status window, session window, and event window. There are two kinds of time windows: sliding window and flip time/tumbling window. The syntax of window clause is as follows:
 
 ```sql
-SELECT select_list FROM tb_name
-  [WHERE where_condition]
-  [SESSION(ts_col, tol_val)]
-  [STATE_WINDOW(col)]
-  [INTERVAL(interval [, offset]) [SLIDING sliding]]
-  [FILL({NONE | VALUE | PREV | NULL | LINEAR | NEXT})]
+window_clause: {
+    SESSION(ts_col, tol_val)
+  | STATE_WINDOW(col)
+  | INTERVAL(interval [, offset]) [SLIDING sliding] [FILL({NONE | VALUE | PREV | NULL | LINEAR | NEXT})]
+  | EVENT_WINDOW START WITH start_trigger_condition END WITH end_trigger_condition
+}
 ```
 
 The following restrictions apply:
@@ -146,6 +146,26 @@ If the time interval between two continuous rows are within the time interval sp
 SELECT COUNT(*), FIRST(ts) FROM temp_tb_1 SESSION(ts, tol_val);
 ```
 
+### Event Window
+
+Event window is determined according to the window start condition and the window close condition. The window is started when `start_trigger_condition` is evaluated to true, the window is closed when `end_trigger_condition` is evaluated to true. `start_trigger_condition` and `end_trigger_condition` can be any conditional expressions supported by TDengine and can include multiple columns.
+
+There may be only one row of data in an event window, when a row meets both the `start_trigger_condition` and the `end_trigger_condition`. 
+
+The window is treated as invalid or non-existing if the `end_trigger_condition` can't be met. There will be no output in case that a window can't be closed. 
+
+If the event window query is performed on a super table, TDengine consolidates all the data of all child tables into a single timeline then perform event window based query.
+
+If you want to perform event window based query on the result set of a sub-query, the result set of the sub-query should be arranged in the order of timestamp and include the column of timestamp.
+
+For example, the diagram below illustrates the event windows generated by the query below:
+
+```sql
+select _wstart, _wend, count(*) from t start with c1 > 0 end with c2 < 10 
+```
+
+![Event Window Illustration](./event_window.webp)
+
 ### Examples
 
 A table of intelligent meters can be created by the SQL statement below：

docs/zh/12-taos-sql/12-distinguished.md

@@ -31,7 +31,7 @@ select max(current) from meters partition by location interval(10m)
 
 ## 窗口切分查询
 
-TDengine 支持按时间窗口切分方式进行聚合结果查询，比如温度传感器每秒采集一次数据，但需查询每隔 10 分钟的温度平均值。这种场景下可以使用窗口子句来获得需要的查询结果。窗口子句用于针对查询的数据集合按照窗口切分成为查询子集并进行聚合，窗口包含时间窗口（time window）、状态窗口（status window）、会话窗口（session window）三种窗口。其中时间窗口又可划分为滑动时间窗口和翻转时间窗口。
+TDengine 支持按时间窗口切分方式进行聚合结果查询，比如温度传感器每秒采集一次数据，但需查询每隔 10 分钟的温度平均值。这种场景下可以使用窗口子句来获得需要的查询结果。窗口子句用于针对查询的数据集合按照窗口切分成为查询子集并进行聚合，窗口包含时间窗口（time window）、状态窗口（status window）、会话窗口（session window）、条件窗口（event window）四种窗口。其中时间窗口又可划分为滑动时间窗口和翻转时间窗口。
 
 窗口子句语法如下：