feat(parser): add support for QUARTER duration alias and related tests

docs/en/14-reference/03-taos-sql/01-datatype.md

@@ -2,6 +2,26 @@
 title: Data Types
 ---
 
+## Time Units
+
+Wherever a time duration is required in TDengine SQL (time arithmetic, INTERVAL, EVERY, SLIDING, etc.), a single-character suffix is used to denote the unit. Supported time units, from smallest to largest, are:
+
+| Unit | Meaning        | Notes                                                        |
+| :--: | -------------- | ------------------------------------------------------------ |
+| `b`  | Nanoseconds    | Smallest precision unit; meaningful only when database precision is nanoseconds |
+| `u`  | Microseconds   | Meaningful only when database precision is microseconds or nanoseconds |
+| `a`  | Milliseconds   | Default database precision                                   |
+| `s`  | Seconds        |                                                              |
+| `m`  | Minutes        |                                                              |
+| `h`  | Hours          |                                                              |
+| `d`  | Days           |                                                              |
+| `w`  | Weeks (7 days) |                                                              |
+| `n`  | Natural month  | Calendar unit; only allowed in INTERVAL windows, not in time arithmetic, EVERY, SURROUND, etc. |
+| `q`  | Natural quarter | Calendar unit; equivalent to 3 natural months; only allowed in INTERVAL windows, not in time arithmetic, EVERY, SURROUND, etc. |
+| `y`  | Natural year   | Calendar unit; only allowed in INTERVAL windows, not in time arithmetic, EVERY, SURROUND, etc. |
+
+Unit letters are case-insensitive (e.g., `1S` equals `1s`).
+
 ## Timestamp
 
 Using TDengine, the most important aspect is the timestamp. When creating and inserting records, or querying historical records, specifying the timestamp is necessary. The rules for timestamps are as follows:
@@ -10,7 +30,7 @@ Using TDengine, the most important aspect is the timestamp. When creating and in
 - The internal function NOW represents the current time of the client
 - When inserting records, if the timestamp is NOW, the current time of the client submitting the record is used
 - Epoch Time: The timestamp can also be a long integer, representing the number of milliseconds since UTC time 1970-01-01 00:00:00. Accordingly, if the time precision of the Database is set to "microseconds", the meaning of the long integer format timestamp corresponds to the number of microseconds since UTC time 1970-01-01 00:00:00; the logic for nanoseconds precision is similar.
-- Time can be added or subtracted, such as NOW-2h, which indicates pushing the query time forward by 2 hours (the last 2 hours). The time unit after the number can be b (nanoseconds), u (microseconds), a (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks). For example `SELECT * FROM t1 WHERE ts > NOW-2w AND ts <= NOW-1w`, represents querying data for a whole week two weeks ago. When specifying the time window (Interval) for Down Sampling operations, the time unit can also use n (natural month) and y (natural year).
+- Time can be added or subtracted, such as NOW-2h, which indicates pushing the query time forward by 2 hours (the last 2 hours). Supported time units are described in the [Time Units](#time-units) section. For example `SELECT * FROM t1 WHERE ts > NOW-2w AND ts <= NOW-1w`, represents querying data for a whole week two weeks ago.
 
 TDengine's default timestamp precision is milliseconds, but microseconds and nanoseconds are also supported by passing the `PRECISION` parameter during `CREATE DATABASE`.
 

docs/en/14-reference/03-taos-sql/20-select.md

@@ -106,29 +106,17 @@ true_for_expr: {
 - from_clause: Specify the data source for the query, which can be a single table (super table, sub table, regular table, virtual table), a view, support multiple table association queries.
 - table_reference: Specify the name of a single table (including views), and optionally specify an alias for the table.
 - table_expr: Specify the query data source, which can be table name, view name, or subquery.
-- join_clause: Join query, supports sub tables, regular tables, super tables, and sub queries. In window join, WINDOW_OFFSET uses start_offset and end_offset to specify the offset of the left and right boundaries of the window relative to the primary keys of the left and right tables. There is no size correlation between the two, this is a required field. Precision can be selected from 1n (nanoseconds), 1u (microseconds), 1a (milliseconds), 1s (seconds), 1m (minutes), 1h (hours), 1d (days), and 1w (weeks), such as window_offset (-1a, 1a). JLIMIT limits the maximum number of rows for single line matching, with a default value of 1 and a value range of [0,1024]. For detailed information, please refer to the join query chapter [TDengine Join Queries](25-join.md).
+- join_clause: Join query, supports sub tables, regular tables, super tables, and sub queries. In window join, WINDOW_OFFSET uses start_offset and end_offset to specify the offset of the left and right boundaries of the window relative to the primary keys of the left and right tables. There is no size correlation between the two, this is a required field. Precision options are listed in [Time Units](./01-datatype.md#time-units) (months/quarters/years not supported), such as window_offset (-1a, 1a). JLIMIT limits the maximum number of rows for single line matching, with a default value of 1 and a value range of [0, 1024]. For detailed information, please refer to the join query chapter [TDengine Join Queries](25-join.md).
 - window_clause: Specifies data to be split and aggregated according to the window, it is a distinctive query of time-series databases. For detailed information, please refer to the distinctive query chapter [TDengine Distinctive Queries](24-distinguished.md).
-  - SESSION: Session window, ts_col specifies the timestamp primary key column, tol_val specifies the time interval, positive value, and time precision can be selected from 1n, 1u, 1a, 1s, 1m, 1h, 1d, 1w, such as SESSION (ts, 12s).
-  - STATE_WINDOW: State window, using one or more state keys to divide windows. Multiple state keys are supported from v3.4.2.0. `state_expr` can be a column reference or an expression such as `CASE WHEN`, `IF`, or `CAST`, and its result type must be integer, boolean, or `VARCHAR`; tag columns are not supported. A window is cut when any state key changes. `EXTEND(extend_val)` specifies the boundary extension strategy: `0` is the default behavior; `EXTEND(1)` keeps the window start unchanged and extends the window end forward to just before the next window starts; `EXTEND(2)` keeps the window end unchanged and extends the window start backward to just after the previous window ends. If all state-key columns are `NULL`, the row follows the existing `NULL` behavior of state windows. If only some state-key columns are `NULL`, consecutive partial-`NULL` rows are handled as a whole and, depending on `EXTEND(0|1|2)`, may merge into the previous window, merge into the next window, or become an independent window. `ZEROTH_STATE(...)` specifies the zero state; the number of arguments must match the number of state keys. Any argument other than `NO_ZEROTH` must be a constant and convertible to the corresponding state-key type. `NO_ZEROTH` means the corresponding position is ignored in zero-state matching. A window is filtered only when all constrained positions match their zero-state values. TRUE_FOR specifies the filtering condition for windows. Supports the following four modes:
-    - `TRUE_FOR(duration_time)`: Filters based on duration only. The window duration must be greater than or equal to `duration_time`.
-    - `TRUE_FOR(COUNT n)`: Filters based on row count only. The window row count must be greater than or equal to `n`.
-    - `TRUE_FOR(duration_time AND COUNT n)`: Both duration and row count conditions must be satisfied.
-    - `TRUE_FOR(duration_time OR COUNT n)`: Either duration or row count condition must be satisfied.
-
-    Where `duration_time` is a positive time value with supported units: 1n (nanoseconds), 1u (microseconds), 1a (milliseconds), 1s (seconds), 1m (minutes), 1h (hours), 1d (days), 1w (weeks). Examples: `TRUE_FOR(1a)`, `TRUE_FOR(COUNT 100)`, `TRUE_FOR(10m AND COUNT 50)`, `TRUE_FOR(5m OR COUNT 20)`.
-  - INTERVAL: Time window, interval_val specifies the window size, sliding_val specifies the window sliding time, sliding_val time is limited to the interval_val range, interval_val and sliding_val time ranges are positive values, and precision can be selected from 1n, 1u, 1a, 1s, 1m, 1h, 1d, and 1w, such as interval_val (2d) and SLIDING (1d).
-  - EVENT_WINDOW: The event window uses start_trigger_condition and end_trigger_condition to specify start and end conditions, supports any expression, and can specify different columns. TRUE_FOR specifies the filtering condition for windows. Supports the following four modes:
-    - `TRUE_FOR(duration_time)`: Filters based on duration only. The window duration must be greater than or equal to `duration_time`.
-    - `TRUE_FOR(COUNT n)`: Filters based on row count only. The window row count must be greater than or equal to `n`.
-    - `TRUE_FOR(duration_time AND COUNT n)`: Both duration and row count conditions must be satisfied.
-    - `TRUE_FOR(duration_time OR COUNT n)`: Either duration or row count condition must be satisfied.
-
-    Where `duration_time` is a positive time value with supported units: 1n (nanoseconds), 1u (microseconds), 1a (milliseconds), 1s (seconds), 1m (minutes), 1h (hours), 1d (days), 1w (weeks). Examples: `TRUE_FOR(10m)`, `TRUE_FOR(COUNT 100)`, `TRUE_FOR(10m AND COUNT 50)`, `TRUE_FOR(5m OR COUNT 20)`.
-  - COUNT_WINDOW: Count window, specifying the division of the window by the number of rows, count_val window contains the maximum number of rows, with a range of [2,2147483647]. The sliding quantity of the window is [1, count_val].The col_name parameter starts to be supported after version 3.3.7.0. col_name specifies one or more columns. When counting in the count_window, for each row of data in the window, at least one of the specified columns must be non-null; otherwise, that row of data is not included in the counting window. If col_name is not specified, it means there is no non-null restriction.
+  - SESSION: Session window, ts_col specifies the timestamp primary key column, tol_val specifies the time interval, positive value. Supported time units are listed in [Time Units](./01-datatype.md#time-units) (milliseconds through weeks only), such as SESSION (ts, 12s).
+  - STATE_WINDOW: State window, using one or more state keys to divide windows. Multiple state keys are supported from v3.4.2.0. `EXTEND(extend_val)` specifies the boundary extension strategy. `ZEROTH_STATE(...)` specifies the zero state. TRUE_FOR specifies the filtering condition for windows.
+  - INTERVAL: Time window, interval_val specifies the window size, sliding_val specifies the window sliding time, sliding_val time is limited to the interval_val range, interval_val and sliding_val time ranges are positive values. Supported time units are listed in [Time Units](./01-datatype.md#time-units), such as interval_val (2d) and SLIDING (1d).
+  - EVENT_WINDOW: The event window uses start_trigger_condition and end_trigger_condition to specify start and end conditions, supports any expression, and can specify different columns. TRUE_FOR specifies the filtering condition for windows.
+  - COUNT_WINDOW: Count window, specifying the division of the window by the number of rows, count_val window contains the maximum number of rows, with a range of [2, 2147483647]. The sliding quantity of the window is [1, count_val]. The col_name parameter starts to be supported after version 3.3.7.0. col_name specifies one or more columns. When counting in the count_window, for each row of data in the window, at least one of the specified columns must be non-null; otherwise, that row of data is not included in the counting window. If col_name is not specified, it means there is no non-null restriction.
   - EXTERNAL_WINDOW: External window. The time range of each window is explicitly defined by a subquery instead of being generated by built-in rules. The first two columns of the subquery must be of timestamp type, representing the window start and end times. Columns from the third column onward become window attribute columns and can be referenced through `window_alias.column_name`. The outer query calculates aggregate results independently within each window. It supports PARTITION BY alignment, HAVING filtering, nested usage, and `FILL` for empty windows. For details, see [TDengine Distinctive Queries](24-distinguished.md#external-window).
 - interp_clause: Interp clause, used in conjunction with the interp function, specifying the recorded value or interpolation of the time section, can specify the time range of interpolation, output time interval, and interpolation type.
-  - RANGE: Specify a single or start end time value, the end time must be greater than the start time. ts_val is a standard timestamp type. Such as ```RANGE('2023-10-01T00:00:00.000')``` or ```RANGE('2023-10-01T00:00:00.000', '2023-10-01T23:59:59.999')```.
-  - EVERY: Time interval range, with every_val being a positive value and precision options of 1n, 1u, 1a, 1s, 1m, 1h, 1d, and 1w, such as EVERY (1s).
+  - RANGE: Specify a single or start end time value, the end time must be greater than the start time. ts_val is a standard timestamp type. surrounding_time_val is optional, specifying the time range for valid data, as a positive value. Supported time units are listed in [Time Units](./01-datatype.md#time-units) (months/quarters/years not supported). Such as ```RANGE('2023-10-01T00:00:00.000')``` or ```RANGE('2023-10-01T00:00:00.000', '2023-10-01T23:59:59.999')```.
+  - EVERY: Time interval range, with every_val being a positive value. Supported time units are listed in [Time Units](./01-datatype.md#time-units) (milliseconds through weeks only), such as EVERY (1s).
 - fill_clause: Fill clause, can be used with the interp function, INTERVAL window, or EXTERNAL_WINDOW to specify the data filling method when data is missing. The supported modes differ by context.
 - group_by_expr: Specify data grouping and aggregation rules. Supports expressions, functions, positions, columns, and aliases. When using positional syntax, it must appear in the selection column, such as `select ts, current from meters order by ts desc, 2`, where 2 corresponds to the current column.
 - partition_by_expr: Specify the data slicing conditions, and calculate the data independently within the slice. Supports expressions, functions, positions, columns, and aliases. When using positional syntax, it must appear in the selection column, such as `select current from meters partition by 1`, where 1 corresponds to the current column.
@@ -335,7 +323,7 @@ TDengine supports INNER JOIN based on the timestamp primary key, with the follow
 The INTERP clause is a dedicated syntax for the [INTERP function](./22-function.md#interp). When an SQL statement contains an INTERP clause, it can only query the INTERP function and cannot be used with other functions. Additionally, the INTERP clause cannot be used simultaneously with window clauses (window_clause) or group by clauses (group_by_clause). The INTERP function must be used with the RANGE, EVERY, and FILL clauses.
 
 - The output time range for INTERP is specified by the RANGE(timestamp1, timestamp2) field, which must satisfy timestamp1 \<= timestamp2. Here, timestamp1 is the start value of the output time range, i.e., if the conditions for interpolation are met at timestamp1, then timestamp1 is the first record output, and timestamp2 is the end value of the output time range, i.e., the timestamp of the last record output cannot be greater than timestamp2.
-- INTERP determines the number of results within the output time range based on the EVERY(time_unit) field, starting from timestamp1 and interpolating at fixed intervals of time (time_unit value), where time_unit can be time units: 1a (milliseconds), 1s (seconds), 1m (minutes), 1h (hours), 1d (days), 1w (weeks). For example, EVERY(500a) will interpolate the specified data every 500 milliseconds.
+- INTERP determines the number of results within the output time range based on the EVERY(time_unit) field, starting from timestamp1 and interpolating at fixed intervals of time (time_unit value). The time_unit options are listed in [Time Units](./01-datatype.md#time-units), supporting milliseconds through weeks only (months/quarters/years not allowed). For example, EVERY(500a) will interpolate the specified data every 500 milliseconds.
 - INTERP determines how to interpolate at each time point that meets the output conditions based on the FILL field. For how to use the FILL clause, refer to [FILL Clause](./20-select.md#fill-clause). Note: The sampled data used for interpolation is not limited to the constraints of the RANGE field, but rather to all data that meets the conditions of the WHERE clause; if no WHERE clause is specified, the entire table data is used. When the parameter of the FILL clause is PREV/NEXT/NEAR, adjacent valid data will be used for interpolation. Whether NULL data is considered valid data depends on the ignore_null_values parameter of the INTERP function. To limit the scope of sampled data, you can use the SURROUND clause.
 - INTERP can interpolate at a single time point specified in the RANGE field, in which case the EVERY field can be omitted. For example: `SELECT INTERP(col) FROM tb RANGE('2023-01-01 00:00:00') FILL(linear)`.
 - INTERP query supports NEAR FILL mode, i.e., when FILL is needed, it uses the valid data closest to the current time point for interpolation. When the timestamps before and after are equally close to the current time slice, FILL the previous row's value. This mode is not supported in window queries. For example: `SELECT INTERP(col) FROM tb RANGE('2023-01-01 00:00:00', '2023-01-01 00:10:00') FILL(NEAR)` (Supported from version 3.3.4.9).
@@ -381,7 +369,7 @@ For EXTERNAL_WINDOW queries, the supported modes are `NONE`, `NULL`, `NULL_F`, `
 
 The SURROUND clause is used to limit the filling range of the FILL clause. It can only be used in PREV, NEXT, NEAR (only supported in INTERP queries) modes.
 
-The SURROUNDING_TIME_VAL parameter specifies the time range that the valid data must meet. It takes a positive number and the unit can be any time unit except for month(n) and year(y).
+The SURROUNDING_TIME_VAL parameter specifies the time range that the valid data must meet. It takes a positive number and the unit can be any time unit except for month(n), quarter(q), and year(y).
 In an INTERVAL window query, its value must be greater than or equal to the time length of the INTERVAL window.
 
 In an INTERP query, if the time difference between a valid data row and the current row exceeds this parameter, that row will not be used; instead, `FILL_VALS` is used to fill the gap.