docs: document FFT table function

src/UserGuide/Master/Table/SQL-Manual/Featured-Functions_apache.md

@@ -693,3 +693,81 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM CUMULAT
 |2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|    AAPL|101.66666666666667|
 +-----------------------------+-----------------------------+--------+------------------+
 ```
+
+## 4. `FFT` Function
+
+### 4.1 Function Description
+
+`FFT` is a table-valued function that calculates the complex discrete Fourier transform of one or more numeric columns. It processes each partition independently and returns one row for every frequency bin.
+
+### 4.2 Function Definition
+
+```sql
+FFT(
+  DATA => table_reference
+    [PARTITION BY partition_column [, ...]]
+    ORDER BY time_column,
+  [SAMPLE_INTERVAL => duration],
+  [N => positive_integer],
+  [NORM => 'backward' | 'forward' | 'ortho'],
+  [TIMECOL => 'time_column_name']
+)
+```
+
+`DATA` is a set-semantic table argument. Its `ORDER BY` clause is required and must contain exactly the time column in ascending order. `PARTITION BY` is optional; without it, all input rows are processed as one partition.
+
+### 4.3 Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `DATA` | Table | Required | Input table or query. The input must contain a `TIMESTAMP` column and at least one numeric column. |
+| `SAMPLE_INTERVAL` | Duration | Inferred | Sampling interval. If omitted, IoTDB infers the average interval from the first and last timestamps in each partition. |
+| `N` | Positive integer | Number of input rows | FFT transform length. If `N` is greater than the number of rows, the input is zero-padded; if it is smaller, only the first `N` rows are transformed. `N` cannot exceed 65,536. |
+| `NORM` | String | `'backward'` | Normalization mode: `backward` (no scaling), `forward` (divide by `N`), or `ortho` (divide by `sqrt(N)`). Values are case-insensitive. |
+| `TIMECOL` | String | `'time'` | Name of the timestamp column in `DATA`. |
+
+### 4.4 Input Requirements and Limitations
+
+* Supported FFT input types are `INT32`, `INT64`, `FLOAT`, and `DOUBLE`. Other non-partition, non-time columns are ignored.
+* Every numeric input value must be non-`NULL`.
+* Timestamps must be strictly ascending within each partition.
+* If `SAMPLE_INTERVAL` is omitted, each partition must contain at least two rows. For regularly sampled data, explicitly specifying the interval is recommended.
+* FFT assumes equally spaced samples. For irregular timestamps, the implementation uses the average interval (or the supplied interval), so the frequency axis is an approximation.
+* The total number of spectrum values (`2 × N × number of numeric columns`) is limited to 16,777,216 in addition to the `N <= 65,536` limit.
+
+### 4.5 Returned Results
+
+The result contains the following columns in order:
+
+1. Columns listed in `PARTITION BY` (if any).
+2. `frequency_index` (`INT64`): frequency-bin index from `0` to `N - 1`.
+3. `frequency` (`DOUBLE`): signed frequency in hertz; the upper half of the bins represents negative frequencies.
+4. For every numeric input column `value`, two `DOUBLE` columns: `value_real` and `value_imag`.
+
+The magnitude of a bin can be calculated as `sqrt(value_real * value_real + value_imag * value_imag)`.
+
+### 4.6 Usage Example
+
+The following query calculates a four-point FFT for each stock. The `price` values are sampled every minute and are normalized with the orthogonal convention.
+
+```sql
+SELECT *
+FROM FFT(
+  DATA => bid PARTITION BY stock_id ORDER BY time,
+  SAMPLE_INTERVAL => 1m,
+  N => 4,
+  NORM => 'ortho'
+);
+```
+
+For a table with a timestamp column named `event_time`, specify `TIMECOL` explicitly:
+
+```sql
+SELECT *
+FROM FFT(
+  DATA => (SELECT event_time, device_id, temperature FROM sensor_data)
+    PARTITION BY device_id ORDER BY event_time,
+  SAMPLE_INTERVAL => 1s,
+  TIMECOL => 'event_time'
+);
+```

src/UserGuide/Master/Table/User-Manual/User-defined-function.md

@@ -448,6 +448,12 @@ The result set of a table function consists of two parts:
    * If no pass-through but PARTITION BY is specified: Only partition columns are included.
    * If neither is specified: No additional columns are added.
 
+#### 3.4.7 Built-in FFT Table Function
+
+IoTDB provides the built-in `FFT` table function for computing a fast Fourier transform of numeric columns in a table argument. The `DATA` argument must specify an ascending `ORDER BY` on the time column; `PARTITION BY` can be used to calculate each device or tag independently. See [FFT in Featured Functions](../SQL-Manual/Featured-Functions_apache.md#4-fft-function) for the complete parameter list, output schema, and examples.
+
+`FFT` supports `INT32`, `INT64`, `FLOAT`, and `DOUBLE` value columns. Numeric values cannot be `NULL`, and timestamps must be strictly ascending within each partition. FFT treats input as equally spaced samples; when `SAMPLE_INTERVAL` is omitted, the interval is inferred from the average span of each partition, so irregular timestamps produce an approximate frequency axis.
+
 ### 3.5 Complete Maven Project Example
 
 For Maven-based implementations, refer to the sample project: [udf-example](https://github.com/apache/iotdb/tree/master/example/udf).

src/UserGuide/latest-Table/SQL-Manual/Featured-Functions_apache.md

@@ -694,3 +694,80 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM CUMULAT
 +-----------------------------+-----------------------------+--------+------------------+
 ```
 
+## 4. `FFT` Function
+
+### 4.1 Function Description
+
+`FFT` is a table-valued function that calculates the complex discrete Fourier transform of one or more numeric columns. It processes each partition independently and returns one row for every frequency bin.
+
+### 4.2 Function Definition
+
+```sql
+FFT(
+  DATA => table_reference
+    [PARTITION BY partition_column [, ...]]
+    ORDER BY time_column,
+  [SAMPLE_INTERVAL => duration],
+  [N => positive_integer],
+  [NORM => 'backward' | 'forward' | 'ortho'],
+  [TIMECOL => 'time_column_name']
+)
+```
+
+`DATA` is a set-semantic table argument. Its `ORDER BY` clause is required and must contain exactly the time column in ascending order. `PARTITION BY` is optional; without it, all input rows are processed as one partition.
+
+### 4.3 Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `DATA` | Table | Required | Input table or query. The input must contain a `TIMESTAMP` column and at least one numeric column. |
+| `SAMPLE_INTERVAL` | Duration | Inferred | Sampling interval. If omitted, IoTDB infers the average interval from the first and last timestamps in each partition. |
+| `N` | Positive integer | Number of input rows | FFT transform length. If `N` is greater than the number of rows, the input is zero-padded; if it is smaller, only the first `N` rows are transformed. `N` cannot exceed 65,536. |
+| `NORM` | String | `'backward'` | Normalization mode: `backward` (no scaling), `forward` (divide by `N`), or `ortho` (divide by `sqrt(N)`). Values are case-insensitive. |
+| `TIMECOL` | String | `'time'` | Name of the timestamp column in `DATA`. |
+
+### 4.4 Input Requirements and Limitations
+
+* Supported FFT input types are `INT32`, `INT64`, `FLOAT`, and `DOUBLE`. Other non-partition, non-time columns are ignored.
+* Every numeric input value must be non-`NULL`.
+* Timestamps must be strictly ascending within each partition.
+* If `SAMPLE_INTERVAL` is omitted, each partition must contain at least two rows. For regularly sampled data, explicitly specifying the interval is recommended.
+* FFT assumes equally spaced samples. For irregular timestamps, the implementation uses the average interval (or the supplied interval), so the frequency axis is an approximation.
+* The total number of spectrum values (`2 × N × number of numeric columns`) is limited to 16,777,216 in addition to the `N <= 65,536` limit.
+
+### 4.5 Returned Results
+
+The result contains the following columns in order:
+
+1. Columns listed in `PARTITION BY` (if any).
+2. `frequency_index` (`INT64`): frequency-bin index from `0` to `N - 1`.
+3. `frequency` (`DOUBLE`): signed frequency in hertz; the upper half of the bins represents negative frequencies.
+4. For every numeric input column `value`, two `DOUBLE` columns: `value_real` and `value_imag`.
+
+The magnitude of a bin can be calculated as `sqrt(value_real * value_real + value_imag * value_imag)`.
+
+### 4.6 Usage Example
+
+The following query calculates a four-point FFT for each stock. The `price` values are sampled every minute and are normalized with the orthogonal convention.
+
+```sql
+SELECT *
+FROM FFT(
+  DATA => bid PARTITION BY stock_id ORDER BY time,
+  SAMPLE_INTERVAL => 1m,
+  N => 4,
+  NORM => 'ortho'
+);
+```
+
+For a table with a timestamp column named `event_time`, specify `TIMECOL` explicitly:
+
+```sql
+SELECT *
+FROM FFT(
+  DATA => (SELECT event_time, device_id, temperature FROM sensor_data)
+    PARTITION BY device_id ORDER BY event_time,
+  SAMPLE_INTERVAL => 1s,
+  TIMECOL => 'event_time'
+);
+```

src/UserGuide/latest-Table/User-Manual/User-defined-function.md

@@ -448,6 +448,12 @@ The result set of a table function consists of two parts:
    * If no pass-through but PARTITION BY is specified: Only partition columns are included.
    * If neither is specified: No additional columns are added.
 
+#### 3.4.7 Built-in FFT Table Function
+
+IoTDB provides the built-in `FFT` table function for computing a fast Fourier transform of numeric columns in a table argument. The `DATA` argument must specify an ascending `ORDER BY` on the time column; `PARTITION BY` can be used to calculate each device or tag independently. See [FFT in Featured Functions](../SQL-Manual/Featured-Functions_apache.md#4-fft-function) for the complete parameter list, output schema, and examples.
+
+`FFT` supports `INT32`, `INT64`, `FLOAT`, and `DOUBLE` value columns. Numeric values cannot be `NULL`, and timestamps must be strictly ascending within each partition. FFT treats input as equally spaced samples; when `SAMPLE_INTERVAL` is omitted, the interval is inferred from the average span of each partition, so irregular timestamps produce an approximate frequency axis.
+
 ### 3.5 Complete Maven Project Example
 
 For Maven-based implementations, refer to the sample project: [udf-example](https://github.com/apache/iotdb/tree/master/example/udf).

src/zh/UserGuide/latest-Table/SQL-Manual/Featured-Functions_apache.md

@@ -695,3 +695,80 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM CUMULAT
 +-----------------------------+-----------------------------+--------+------------------+
 ```
 
+## 4. `FFT` 函数
+
+### 4.1 功能概述
+
+`FFT` 是一个表值函数，用于对一个或多个数值列计算复数离散傅里叶变换。函数会分别处理每个分区，并为每个频率箱返回一行结果。
+
+### 4.2 函数定义
+
+```sql
+FFT(
+  DATA => table_reference
+    [PARTITION BY partition_column [, ...]]
+    ORDER BY time_column,
+  [SAMPLE_INTERVAL => duration],
+  [N => positive_integer],
+  [NORM => 'backward' | 'forward' | 'ortho'],
+  [TIMECOL => 'time_column_name']
+)
+```
+
+`DATA` 是组语义表参数，必须指定 `ORDER BY`，且该子句只能包含升序排列的时间列。`PARTITION BY` 为可选项；未指定时，所有输入行作为一个分区处理。
+
+### 4.3 参数说明
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `DATA` | 表 | 必填 | 输入表或查询。输入必须包含一个 `TIMESTAMP` 列以及至少一个数值列。 |
+| `SAMPLE_INTERVAL` | 时间间隔 | 自动推断 | 采样间隔。省略时，IoTDB 根据每个分区的首尾时间戳计算平均间隔。 |
+| `N` | 正整数 | 输入行数 | FFT 变换长度。`N` 大于输入行数时使用零填充；小于输入行数时只对前 `N` 行进行变换。`N` 不能超过 65,536。 |
+| `NORM` | 字符串 | `'backward'` | 归一化模式：`backward`（不缩放）、`forward`（除以 `N`）或 `ortho`（除以 `sqrt(N)`）。值不区分大小写。 |
+| `TIMECOL` | 字符串 | `'time'` | `DATA` 中时间戳列的名称。 |
+
+### 4.4 输入要求与限制
+
+* 支持的 FFT 输入类型为 `INT32`、`INT64`、`FLOAT` 和 `DOUBLE`，其他非分区、非时间列会被忽略。
+* 所有数值输入都不能为 `NULL`。
+* 每个分区内的时间戳必须严格递增。
+* 省略 `SAMPLE_INTERVAL` 时，每个分区至少需要两行数据。对于等间隔采样数据，建议显式指定采样间隔。
+* FFT 假设样本等间隔。对于时间戳不规则的数据，函数使用平均间隔（或用户提供的间隔），因此频率轴结果是近似值。
+* 除了 `N <= 65,536` 的限制外，频谱值总数（`2 × N × 数值列数`）不能超过 16,777,216。
+
+### 4.5 返回结果
+
+返回列按以下顺序排列：
+
+1. `PARTITION BY` 中指定的列（如果指定）。
+2. `frequency_index`（`INT64`）：从 `0` 到 `N - 1` 的频率箱索引。
+3. `frequency`（`DOUBLE`）：以赫兹为单位的有符号频率，后半部分频率箱表示负频率。
+4. 对每个数值输入列 `value`，返回两个 `DOUBLE` 列：`value_real` 和 `value_imag`。
+
+频率箱的幅值可以通过 `sqrt(value_real * value_real + value_imag * value_imag)` 计算。
+
+### 4.6 使用示例
+
+以下查询按股票分别计算 4 点 FFT。`price` 每分钟采样一次，并使用正交归一化方式。
+
+```sql
+SELECT *
+FROM FFT(
+  DATA => bid PARTITION BY stock_id ORDER BY time,
+  SAMPLE_INTERVAL => 1m,
+  N => 4,
+  NORM => 'ortho'
+);
+```
+
+如果表中的时间戳列名为 `event_time`，可以显式指定 `TIMECOL`：
+
+```sql
+SELECT *
+FROM FFT(
+  DATA => (SELECT event_time, device_id, temperature FROM sensor_data)
+    PARTITION BY device_id ORDER BY event_time,
+  SAMPLE_INTERVAL => 1s,
+  TIMECOL => 'event_time'
+);
+```

src/zh/UserGuide/latest-Table/User-Manual/User-defined-function.md

@@ -430,6 +430,12 @@ IoTDB 中的表函数为多态表值函数，支持参数类型如下所示：
    * 如果没有指定为列穿透但指定了 PartitionBy，则是 PartitionBy 的列；
    * 如果均未指定，则不根据表参数自动构建列。
 
+#### 3.4.7 内置 FFT 表函数
+
+IoTDB 内置 `FFT` 表函数，用于对表参数中的数值列计算快速傅里叶变换。调用时必须在 `DATA` 参数上指定按时间列升序排列的 `ORDER BY`，并可使用 `PARTITION BY` 对不同设备或标签分别计算。函数的参数、输出列和数据约束请参阅 [特色函数中的 FFT 说明](../SQL-Manual/Featured-Functions_apache.md#4-fft-函数)。
+
+`FFT` 支持 `INT32`、`INT64`、`FLOAT` 和 `DOUBLE` 数值列，数值列不能包含 `NULL`，每个分区内的时间戳必须严格递增。FFT 将输入视为等间隔采样；省略 `SAMPLE_INTERVAL` 时按分区首尾时间戳的平均间隔计算，因此不规则时间戳只能得到近似频率结果。
+
 
 
 ### 3.5 完整Maven项目示例