Document calendar CQ durations

Author: DaZuiZui

src/UserGuide/Master/Tree/User-Manual/Database-Programming.md

@@ -60,18 +60,32 @@ END
 ### 2.1 Descriptions of parameters in CQ syntax
 
 - `<cq_id>` specifies the globally unique id of CQ.
-- `<every_interval>` specifies the query execution time interval. We currently support the units of ns, us, ms, s, m, h, d, w, and its value should not be lower than the minimum threshold configured by the user, which is `continuous_query_min_every_interval`. It's an optional parameter, default value is set to `group_by_interval` in group by clause.
-- `<start_time_offset>` specifies the start time of each query execution as `now()-<start_time_offset>`. We currently support the units of ns, us, ms, s, m, h, d, w.It's an optional parameter, default value is set to `every_interval` in resample clause.
-- `<end_time_offset>` specifies the end time of each query execution as `now()-<end_time_offset>`. We currently support the units of ns, us, ms, s, m, h, d, w.It's an optional parameter, default value is set to `0`.
+- `<every_interval>` specifies the query execution time interval. The supported units are ns, us, ms, s, m, h, d, w, `mo` (calendar month), and `y` (12 calendar months). Calendar units are evaluated in the CQ time zone and are not converted to a fixed number of days. Its value should not be lower than the minimum threshold configured by the user, which is `continuous_query_min_every_interval`. It's an optional parameter, default value is set to `group_by_interval` in group by clause.
+- `<start_time_offset>` specifies the start time of each query execution as `now()-<start_time_offset>`. The supported units are ns, us, ms, s, m, h, d, w, `mo`, and `y`. Calendar offsets are evaluated from the original execution boundary. It's an optional parameter, default value is set to `every_interval` in resample clause.
+- `<end_time_offset>` specifies the end time of each query execution as `now()-<end_time_offset>`. The supported units are ns, us, ms, s, m, h, d, w, `mo`, and `y`. It's an optional parameter, default value is set to `0`.
 - `<execution_boundary_time>` is a date that represents the execution time of a certain cq task.
     - `<execution_boundary_time>` can be earlier than, equals to, later than **current time**.
-    - This parameter is optional. If not specified, it is equal to `BOUNDARY 0`。
+    - This parameter is optional. For a calendar-based `EVERY` interval, an omitted boundary is `1970-01-01 00:00:00` in the CQ time zone. For fixed-only intervals it remains `BOUNDARY 0` (the Unix epoch). An explicitly supplied `BOUNDARY 0` always means the Unix epoch.
     - **The start time of the first time window** is `<execution_boundary_time> - <start_time_offset>`.
     - **The end time of the first time window** is `<execution_boundary_time> - <end_time_offset>`.
     - The **time range** of the `i (1 <= i)th` window is `[<execution_boundary_time> - <start_time_offset> + (i - 1) * <every_interval>, <execution_boundary_time> - <end_time_offset> + (i - 1) * <every_interval>)`.
     - If the **current time** is earlier than or equal to `execution_boundary_time`, then the first execution moment of the continuous query is `execution_boundary_time`.
     - If the **current time** is later than `execution_boundary_time`, then the first execution moment of the continuous query is the first `execution_boundary_time + i * <every_interval>` that is later than or equal to the current time .
 
+For calendar durations, each occurrence and range endpoint is calculated from the original boundary. Calendar months are applied first and the fixed part is applied afterwards, so a schedule anchored on January 31 reaches February 29 (in a leap year), then March 31, instead of drifting to March 29. For example:
+
+```sql
+CREATE CONTINUOUS QUERY cq_monthly
+RESAMPLE EVERY 1mo RANGE 1mo
+BEGIN
+  SELECT max_value(s) INTO root.result.d(max_s)
+  FROM root.source.d
+  GROUP BY(1mo)
+END;
+```
+
+This CQ runs on calendar-month boundaries and its February window has the actual number of days in that February.
+
 > - `<every_interval>`，`<start_time_offset>` and `<group_by_interval>` should all be greater than `0`.
 > - The value of `<group_by_interval>` should be less than or equal to the value of `<start_time_offset>`, otherwise the system will throw an error.
 > - Users should specify the appropriate `<start_time_offset>` and `<every_interval>` according to actual needs.
@@ -589,4 +603,3 @@ SELECT avg(count_s1) from root.sg_count.d;
 | :------------------------------------------ | ------------------------------------------------------------ | --------- | ------------- |
 | `continuous_query_submit_thread_count`            | The number of threads in the scheduled thread pool that submit continuous query tasks periodically | int32     | 2             |
 | `continuous_query_min_every_interval_in_ms` | The minimum value of the continuous query execution time interval | duration  | 1000          |
-

src/UserGuide/latest/User-Manual/Database-Programming.md

@@ -60,18 +60,32 @@ END
 ### 2.1 Descriptions of parameters in CQ syntax
 
 - `<cq_id>` specifies the globally unique id of CQ.
-- `<every_interval>` specifies the query execution time interval. We currently support the units of ns, us, ms, s, m, h, d, w, and its value should not be lower than the minimum threshold configured by the user, which is `continuous_query_min_every_interval`. It's an optional parameter, default value is set to `group_by_interval` in group by clause.
-- `<start_time_offset>` specifies the start time of each query execution as `now()-<start_time_offset>`. We currently support the units of ns, us, ms, s, m, h, d, w.It's an optional parameter, default value is set to `every_interval` in resample clause.
-- `<end_time_offset>` specifies the end time of each query execution as `now()-<end_time_offset>`. We currently support the units of ns, us, ms, s, m, h, d, w.It's an optional parameter, default value is set to `0`.
+- `<every_interval>` specifies the query execution time interval. The supported units are ns, us, ms, s, m, h, d, w, `mo` (calendar month), and `y` (12 calendar months). Calendar units are evaluated in the CQ time zone and are not converted to a fixed number of days. Its value should not be lower than the minimum threshold configured by the user, which is `continuous_query_min_every_interval`. It's an optional parameter, default value is set to `group_by_interval` in group by clause.
+- `<start_time_offset>` specifies the start time of each query execution as `now()-<start_time_offset>`. The supported units are ns, us, ms, s, m, h, d, w, `mo`, and `y`. Calendar offsets are evaluated from the original execution boundary. It's an optional parameter, default value is set to `every_interval` in resample clause.
+- `<end_time_offset>` specifies the end time of each query execution as `now()-<end_time_offset>`. The supported units are ns, us, ms, s, m, h, d, w, `mo`, and `y`. It's an optional parameter, default value is set to `0`.
 - `<execution_boundary_time>` is a date that represents the execution time of a certain cq task.
     - `<execution_boundary_time>` can be earlier than, equals to, later than **current time**.
-    - This parameter is optional. If not specified, it is equal to `BOUNDARY 0`。
+    - This parameter is optional. For a calendar-based `EVERY` interval, an omitted boundary is `1970-01-01 00:00:00` in the CQ time zone. For fixed-only intervals it remains `BOUNDARY 0` (the Unix epoch). An explicitly supplied `BOUNDARY 0` always means the Unix epoch.
     - **The start time of the first time window** is `<execution_boundary_time> - <start_time_offset>`.
     - **The end time of the first time window** is `<execution_boundary_time> - <end_time_offset>`.
     - The **time range** of the `i (1 <= i)th` window is `[<execution_boundary_time> - <start_time_offset> + (i - 1) * <every_interval>, <execution_boundary_time> - <end_time_offset> + (i - 1) * <every_interval>)`.
     - If the **current time** is earlier than or equal to `execution_boundary_time`, then the first execution moment of the continuous query is `execution_boundary_time`.
     - If the **current time** is later than `execution_boundary_time`, then the first execution moment of the continuous query is the first `execution_boundary_time + i * <every_interval>` that is later than or equal to the current time .
 
+For calendar durations, each occurrence and range endpoint is calculated from the original boundary. Calendar months are applied first and the fixed part is applied afterwards, so a schedule anchored on January 31 reaches February 29 (in a leap year), then March 31, instead of drifting to March 29. For example:
+
+```sql
+CREATE CONTINUOUS QUERY cq_monthly
+RESAMPLE EVERY 1mo RANGE 1mo
+BEGIN
+  SELECT max_value(s) INTO root.result.d(max_s)
+  FROM root.source.d
+  GROUP BY(1mo)
+END;
+```
+
+This CQ runs on calendar-month boundaries and its February window has the actual number of days in that February.
+
 > - `<every_interval>`，`<start_time_offset>` and `<group_by_interval>` should all be greater than `0`.
 > - The value of `<group_by_interval>` should be less than or equal to the value of `<start_time_offset>`, otherwise the system will throw an error.
 > - Users should specify the appropriate `<start_time_offset>` and `<every_interval>` according to actual needs.
@@ -589,4 +603,3 @@ SELECT avg(count_s1) from root.sg_count.d;
 | :------------------------------------------ | ------------------------------------------------------------ | --------- | ------------- |
 | `continuous_query_submit_thread_count`            | The number of threads in the scheduled thread pool that submit continuous query tasks periodically | int32     | 2             |
 | `continuous_query_min_every_interval_in_ms` | The minimum value of the continuous query execution time interval | duration  | 1000          |
-

src/zh/UserGuide/Master/Tree/User-Manual/Database-Programming.md

@@ -57,18 +57,32 @@ END
 ### 2.1 连续查询语法中参数含义的描述
 
 - `<cq_id>` 为连续查询指定一个全局唯一的标识。
-- `<every_interval>` 指定了连续查询周期性执行的间隔。现在支持的时间单位有：ns, us, ms, s, m, h, d, w, 并且它的值不能小于用户在`iotdb-system.properties`配置文件中指定的`continuous_query_min_every_interval`。这是一个可选参数，默认等于group by子句中的`group_by_interval`。
-- `<start_time_offset>` 指定了每次查询执行窗口的开始时间，即`now()-<start_time_offset>`。现在支持的时间单位有：ns, us, ms, s, m, h, d, w。这是一个可选参数，默认等于`EVERY`子句中的`every_interval`。
-- `<end_time_offset>` 指定了每次查询执行窗口的结束时间，即`now()-<end_time_offset>`。现在支持的时间单位有：ns, us, ms, s, m, h, d, w。这是一个可选参数，默认等于`0`.
+- `<every_interval>` 指定了连续查询周期性执行的间隔。支持的时间单位有：ns、us、ms、s、m、h、d、w、`mo`（日历月）和 `y`（12 个日历月）。日历单位按照 CQ 时区计算，不会转换为固定天数。它的值不能小于用户在`iotdb-system.properties`配置文件中指定的`continuous_query_min_every_interval`。这是一个可选参数，默认等于 group by 子句中的`group_by_interval`。
+- `<start_time_offset>` 指定了每次查询执行窗口的开始时间，即`now()-<start_time_offset>`。支持的时间单位有：ns、us、ms、s、m、h、d、w、`mo` 和 `y`。日历偏移量从原始执行边界计算。这是一个可选参数，默认等于`EVERY`子句中的`every_interval`。
+- `<end_time_offset>` 指定了每次查询执行窗口的结束时间，即`now()-<end_time_offset>`。支持的时间单位有：ns、us、ms、s、m、h、d、w、`mo` 和 `y`。这是一个可选参数，默认等于`0`。
 - `<execution_boundary_time>` 表示用户期待的连续查询的首个周期任务的执行时间。（因为连续查询只会对当前实时的数据流做计算，所以该连续查询实际首个周期任务的执行时间并不一定等于用户指定的时间，具体计算逻辑如下所示）
     - `<execution_boundary_time>` 可以早于、等于或者迟于当前时间。
-    - 这个参数是可选的，默认等于`0`。
+    - 这个参数是可选的。对于包含日历单位的 `EVERY`，省略 boundary 时使用 CQ 时区中的 `1970-01-01 00:00:00`；仅包含固定时长时仍使用 `BOUNDARY 0`（Unix epoch）。显式指定 `BOUNDARY 0` 始终表示 Unix epoch。
     - 首次查询执行窗口的开始时间为`<execution_boundary_time> - <start_time_offset>`.
     - 首次查询执行窗口的结束时间为`<execution_boundary_time> - <end_time_offset>`.
     - 第i个查询执行窗口的时间范围是`[<execution_boundary_time> - <start_time_offset> + (i - 1) * <every_interval>, <execution_boundary_time> - <end_time_offset> + (i - 1) * <every_interval>)`。
     - 如果当前时间早于或等于, 那连续查询的首个周期任务的执行时间就是用户指定的`execution_boundary_time`.
     - 如果当前时间迟于用户指定的`execution_boundary_time`，那么连续查询的首个周期任务的执行时间就是`execution_boundary_time + i * <every_interval>`中第一个大于或等于当前时间的值。
 
+对于日历 duration，每次执行时间和 RANGE 端点都从原始 boundary 计算。先应用日历月，再应用固定时长，因此以 1 月 31 日为锚点时，闰年会依次得到 2 月 29 日、3 月 31 日，不会因为 2 月截断而漂移到 3 月 29 日。例如：
+
+```sql
+CREATE CONTINUOUS QUERY cq_monthly
+RESAMPLE EVERY 1mo RANGE 1mo
+BEGIN
+  SELECT max_value(s) INTO root.result.d(max_s)
+  FROM root.source.d
+  GROUP BY(1mo)
+END;
+```
+
+该 CQ 按自然月边界执行，二月窗口会根据实际年份包含相应天数。
+
 > - <every_interval>，<start_time_offset> 和 <group_by_interval> 都应该大于 0
 > - <group_by_interval>应该小于等于<start_time_offset>
 > - 用户应该根据实际需求，为<start_time_offset> 和 <every_interval> 指定合适的值
@@ -583,4 +597,4 @@ SELECT avg(count_s1) from root.sg_count.d;
 | 参数名 | 描述                   | 类型 | 默认值 |
 | :---------------------------------- |----------------------|----------|---------------|
 | `continuous_query_submit_thread_count` | 用于周期性提交连续查询执行任务的线程数  | int32    | 2             |
-| `continuous_query_min_every_interval_in_ms` | 系统允许的连续查询最小的周期性时间间隔  | duration | 1000          |
+| `continuous_query_min_every_interval_in_ms` | 系统允许的连续查询最小的周期性时间间隔  | duration | 1000          |

src/zh/UserGuide/latest/User-Manual/Database-Programming.md

@@ -57,18 +57,32 @@ END
 ### 2.1 连续查询语法中参数含义的描述
 
 - `<cq_id>` 为连续查询指定一个全局唯一的标识。
-- `<every_interval>` 指定了连续查询周期性执行的间隔。现在支持的时间单位有：ns, us, ms, s, m, h, d, w, 并且它的值不能小于用户在`iotdb-system.properties`配置文件中指定的`continuous_query_min_every_interval`。这是一个可选参数，默认等于group by子句中的`group_by_interval`。
-- `<start_time_offset>` 指定了每次查询执行窗口的开始时间，即`now()-<start_time_offset>`。现在支持的时间单位有：ns, us, ms, s, m, h, d, w。这是一个可选参数，默认等于`EVERY`子句中的`every_interval`。
-- `<end_time_offset>` 指定了每次查询执行窗口的结束时间，即`now()-<end_time_offset>`。现在支持的时间单位有：ns, us, ms, s, m, h, d, w。这是一个可选参数，默认等于`0`.
+- `<every_interval>` 指定了连续查询周期性执行的间隔。支持的时间单位有：ns、us、ms、s、m、h、d、w、`mo`（日历月）和 `y`（12 个日历月）。日历单位按照 CQ 时区计算，不会转换为固定天数。它的值不能小于用户在`iotdb-system.properties`配置文件中指定的`continuous_query_min_every_interval`。这是一个可选参数，默认等于 group by 子句中的`group_by_interval`。
+- `<start_time_offset>` 指定了每次查询执行窗口的开始时间，即`now()-<start_time_offset>`。支持的时间单位有：ns、us、ms、s、m、h、d、w、`mo` 和 `y`。日历偏移量从原始执行边界计算。这是一个可选参数，默认等于`EVERY`子句中的`every_interval`。
+- `<end_time_offset>` 指定了每次查询执行窗口的结束时间，即`now()-<end_time_offset>`。支持的时间单位有：ns、us、ms、s、m、h、d、w、`mo` 和 `y`。这是一个可选参数，默认等于`0`。
 - `<execution_boundary_time>` 表示用户期待的连续查询的首个周期任务的执行时间。（因为连续查询只会对当前实时的数据流做计算，所以该连续查询实际首个周期任务的执行时间并不一定等于用户指定的时间，具体计算逻辑如下所示）
     - `<execution_boundary_time>` 可以早于、等于或者迟于当前时间。
-    - 这个参数是可选的，默认等于`0`。
+    - 这个参数是可选的。对于包含日历单位的 `EVERY`，省略 boundary 时使用 CQ 时区中的 `1970-01-01 00:00:00`；仅包含固定时长时仍使用 `BOUNDARY 0`（Unix epoch）。显式指定 `BOUNDARY 0` 始终表示 Unix epoch。
     - 首次查询执行窗口的开始时间为`<execution_boundary_time> - <start_time_offset>`.
     - 首次查询执行窗口的结束时间为`<execution_boundary_time> - <end_time_offset>`.
     - 第i个查询执行窗口的时间范围是`[<execution_boundary_time> - <start_time_offset> + (i - 1) * <every_interval>, <execution_boundary_time> - <end_time_offset> + (i - 1) * <every_interval>)`。
     - 如果当前时间早于或等于, 那连续查询的首个周期任务的执行时间就是用户指定的`execution_boundary_time`.
     - 如果当前时间迟于用户指定的`execution_boundary_time`，那么连续查询的首个周期任务的执行时间就是`execution_boundary_time + i * <every_interval>`中第一个大于或等于当前时间的值。
 
+对于日历 duration，每次执行时间和 RANGE 端点都从原始 boundary 计算。先应用日历月，再应用固定时长，因此以 1 月 31 日为锚点时，闰年会依次得到 2 月 29 日、3 月 31 日，不会因为 2 月截断而漂移到 3 月 29 日。例如：
+
+```sql
+CREATE CONTINUOUS QUERY cq_monthly
+RESAMPLE EVERY 1mo RANGE 1mo
+BEGIN
+  SELECT max_value(s) INTO root.result.d(max_s)
+  FROM root.source.d
+  GROUP BY(1mo)
+END;
+```
+
+该 CQ 按自然月边界执行，二月窗口会根据实际年份包含相应天数。
+
 > - <every_interval>，<start_time_offset> 和 <group_by_interval> 都应该大于 0
 > - <group_by_interval>应该小于等于<start_time_offset>
 > - 用户应该根据实际需求，为<start_time_offset> 和 <every_interval> 指定合适的值
@@ -583,4 +597,4 @@ SELECT avg(count_s1) from root.sg_count.d;
 | 参数名 | 描述                   | 类型 | 默认值 |
 | :---------------------------------- |----------------------|----------|---------------|
 | `continuous_query_submit_thread_count` | 用于周期性提交连续查询执行任务的线程数  | int32    | 2             |
-| `continuous_query_min_every_interval_in_ms` | 系统允许的连续查询最小的周期性时间间隔  | duration | 1000          |
+| `continuous_query_min_every_interval_in_ms` | 系统允许的连续查询最小的周期性时间间隔  | duration | 1000          |