Skip to content

Commit 28869f9

Browse files
suyx1999suyx1999
authored
Update Cluster UDF in UDF-Libraries (#1072)
1 parent 33f21d8 commit 28869f9

8 files changed

Lines changed: 690 additions & 0 deletions

File tree

‎src/UserGuide/V1.3.x/SQL-Manual/UDF-Libraries_apache.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4917,3 +4917,89 @@ Output Series:
49174917
+-----------------------------+---------------------------+
49184918
```
49194919

4920+
### Cluster
4921+
4922+
#### Registration statement
4923+
4924+
```sql
4925+
create function cluster as 'org.apache.iotdb.library.dlearn.UDTFCluster'
4926+
```
4927+
4928+
#### Usage
4929+
4930+
This function takes a **single input time series**, splits it into **non-overlapping** contiguous subsequences (windows) of fixed length `l`, and clusters those subsequences into `k` groups.
4931+
4932+
**Name:** Cluster
4933+
4934+
**Input Series:** Only support single input numeric series. The type is INT32 / INT64 / FLOAT / DOUBLE. Points are read in time order; trailing samples that do not fill a full window are dropped (only `⌊n/l⌋` windows are used, where `n` is the number of valid points).
4935+
4936+
**Parameters:**
4937+
4938+
| Name | Meaning | Default | Notes |
4939+
|------|---------|---------|--------|
4940+
| `l` | Subsequence (window) length | (required) | Positive integer; each window has `l` consecutive samples. |
4941+
| `k` | Number of clusters | (required) | Integer ≥ 2. |
4942+
| `method` | Clustering algorithm | `kmeans` | Optional: `kmeans`, `kshape`, `medoidshape` (case-insensitive). Defaults to k-means if omitted. |
4943+
| `norm` | Z-score normalize each subsequence | `true` | Boolean; if `true`, each subsequence is standardized before clustering. |
4944+
| `maxiter` | Maximum iterations | `200` | Positive integer. |
4945+
| `output` | Output mode | `label` | `label`: one cluster id per window; `centroid`: concatenate the `k` centroid vectors in cluster order. |
4946+
| `sample_rate` | Greedy sampling rate | `0.3` | Used only when **`method` = `medoidshape`**; must be in `(0, 1]`. |
4947+
4948+
4949+
**`method` details:**
4950+
4951+
- **kmeans**: k-means in Euclidean space (optionally after per-window normalization).
4952+
- **kshape**: Assign by shape-based distance (SBD from normalized cross-correlation, NCC); centroids updated via SVD on the cluster matrix.
4953+
- **medoidshape**: Coarsely cluster, then greedy selection of `k` representative subsequences; `sample_rate` controls how many candidates are sampled each round.
4954+
4955+
**Output Series:** Controlled by `output`:
4956+
4957+
- **`output` = `label` (default):** One output series, type **INT32**. Number of points = number of full windows, `⌊n/l⌋`. Timestamp of each point = **time of the first sample** in that window; value = cluster id **0 … k−1**.
4958+
- **`output` = `centroid`:** One output series, type **DOUBLE**. Number of points = **`k × l`**: for clusters **0 → k−1**, emit the `l` components of each centroid in order (concatenated). Timestamps are `0, 1, 2, …` (placeholders only, no physical time meaning).
4959+
4960+
**Note:**
4961+
4962+
- Require valid point count `n ≥ l` and window count `⌊n/l⌋ ≥ k`.
4963+
4964+
#### Examples
4965+
4966+
##### KShape: window length 3, k = 2
4967+
4968+
Nine samples `{1,2,3,10,20,30,1,5,1}` form three non-overlapping windows `{1,2,3}`, `{10,20,30}`, `{1,5,1}`. With **`method` = `kshape`** (default `norm` = `true`), each output row is the cluster id for one window; timestamps are the window start times. Resulting labels: **0, 0, 1**.
4969+
4970+
Input Series:
4971+
4972+
```
4973+
+-----------------------------+---------------+
4974+
| Time|root.test.d0.s0|
4975+
+-----------------------------+---------------+
4976+
|2020-01-01T00:00:01.000+08:00| 1.0|
4977+
|2020-01-01T00:00:02.000+08:00| 2.0|
4978+
|2020-01-01T00:00:03.000+08:00| 3.0|
4979+
|2020-01-01T00:00:04.000+08:00| 10.0|
4980+
|2020-01-01T00:00:05.000+08:00| 20.0|
4981+
|2020-01-01T00:00:06.000+08:00| 30.0|
4982+
|2020-01-01T00:00:07.000+08:00| 1.0|
4983+
|2020-01-01T00:00:08.000+08:00| 5.0|
4984+
|2020-01-01T00:00:09.000+08:00| 1.0|
4985+
+-----------------------------+---------------+
4986+
```
4987+
4988+
SQL for query:
4989+
4990+
```sql
4991+
select cluster(s0, "l"="3", "k"="2", "method"="kshape", "output"="label")
4992+
from root.test.d0
4993+
```
4994+
4995+
Output Series:
4996+
4997+
```
4998+
+-----------------------------+----------------------------------------------------------------------------+
4999+
| Time|cluster(root.test.d0.s0,"l"="3","k"="2","method"="kshape","output"="label")|
5000+
+-----------------------------+----------------------------------------------------------------------------+
5001+
|2020-01-01T00:00:01.000+08:00| 0|
5002+
|2020-01-01T00:00:04.000+08:00| 0|
5003+
|2020-01-01T00:00:07.000+08:00| 1|
5004+
+-----------------------------+----------------------------------------------------------------------------+
5005+
```

‎src/UserGuide/V1.3.x/SQL-Manual/UDF-Libraries_timecho.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4976,3 +4976,89 @@ Output Series:
49764976
```
49774977

49784978

4979+
### Cluster
4980+
4981+
#### Registration statement
4982+
4983+
```sql
4984+
create function cluster as 'org.apache.iotdb.library.dlearn.UDTFCluster'
4985+
```
4986+
4987+
#### Usage
4988+
4989+
This function takes a **single input time series**, splits it into **non-overlapping** contiguous subsequences (windows) of fixed length `l`, and clusters those subsequences into `k` groups.
4990+
4991+
**Name:** Cluster
4992+
4993+
**Input Series:** Only support single input numeric series. The type is INT32 / INT64 / FLOAT / DOUBLE. Points are read in time order; trailing samples that do not fill a full window are dropped (only `⌊n/l⌋` windows are used, where `n` is the number of valid points).
4994+
4995+
**Parameters:**
4996+
4997+
| Name | Meaning | Default | Notes |
4998+
|------|---------|---------|--------|
4999+
| `l` | Subsequence (window) length | (required) | Positive integer; each window has `l` consecutive samples. |
5000+
| `k` | Number of clusters | (required) | Integer ≥ 2. |
5001+
| `method` | Clustering algorithm | `kmeans` | Optional: `kmeans`, `kshape`, `medoidshape` (case-insensitive). Defaults to k-means if omitted. |
5002+
| `norm` | Z-score normalize each subsequence | `true` | Boolean; if `true`, each subsequence is standardized before clustering. |
5003+
| `maxiter` | Maximum iterations | `200` | Positive integer. |
5004+
| `output` | Output mode | `label` | `label`: one cluster id per window; `centroid`: concatenate the `k` centroid vectors in cluster order. |
5005+
| `sample_rate` | Greedy sampling rate | `0.3` | Used only when **`method` = `medoidshape`**; must be in `(0, 1]`. |
5006+
5007+
5008+
**`method` details:**
5009+
5010+
- **kmeans**: k-means in Euclidean space (optionally after per-window normalization).
5011+
- **kshape**: Assign by shape-based distance (SBD from normalized cross-correlation, NCC); centroids updated via SVD on the cluster matrix.
5012+
- **medoidshape**: Coarsely cluster, then greedy selection of `k` representative subsequences; `sample_rate` controls how many candidates are sampled each round.
5013+
5014+
**Output Series:** Controlled by `output`:
5015+
5016+
- **`output` = `label` (default):** One output series, type **INT32**. Number of points = number of full windows, `⌊n/l⌋`. Timestamp of each point = **time of the first sample** in that window; value = cluster id **0 … k−1**.
5017+
- **`output` = `centroid`:** One output series, type **DOUBLE**. Number of points = **`k × l`**: for clusters **0 → k−1**, emit the `l` components of each centroid in order (concatenated). Timestamps are `0, 1, 2, …` (placeholders only, no physical time meaning).
5018+
5019+
**Note:**
5020+
5021+
- Require valid point count `n ≥ l` and window count `⌊n/l⌋ ≥ k`.
5022+
5023+
#### Examples
5024+
5025+
##### KShape: window length 3, k = 2
5026+
5027+
Nine samples `{1,2,3,10,20,30,1,5,1}` form three non-overlapping windows `{1,2,3}`, `{10,20,30}`, `{1,5,1}`. With **`method` = `kshape`** (default `norm` = `true`), each output row is the cluster id for one window; timestamps are the window start times. Resulting labels: **0, 0, 1**.
5028+
5029+
Input Series:
5030+
5031+
```
5032+
+-----------------------------+---------------+
5033+
| Time|root.test.d0.s0|
5034+
+-----------------------------+---------------+
5035+
|2020-01-01T00:00:01.000+08:00| 1.0|
5036+
|2020-01-01T00:00:02.000+08:00| 2.0|
5037+
|2020-01-01T00:00:03.000+08:00| 3.0|
5038+
|2020-01-01T00:00:04.000+08:00| 10.0|
5039+
|2020-01-01T00:00:05.000+08:00| 20.0|
5040+
|2020-01-01T00:00:06.000+08:00| 30.0|
5041+
|2020-01-01T00:00:07.000+08:00| 1.0|
5042+
|2020-01-01T00:00:08.000+08:00| 5.0|
5043+
|2020-01-01T00:00:09.000+08:00| 1.0|
5044+
+-----------------------------+---------------+
5045+
```
5046+
5047+
SQL for query:
5048+
5049+
```sql
5050+
select cluster(s0, "l"="3", "k"="2", "method"="kshape", "output"="label")
5051+
from root.test.d0
5052+
```
5053+
5054+
Output Series:
5055+
5056+
```
5057+
+-----------------------------+----------------------------------------------------------------------------+
5058+
| Time|cluster(root.test.d0.s0,"l"="3","k"="2","method"="kshape","output"="label")|
5059+
+-----------------------------+----------------------------------------------------------------------------+
5060+
|2020-01-01T00:00:01.000+08:00| 0|
5061+
|2020-01-01T00:00:04.000+08:00| 0|
5062+
|2020-01-01T00:00:07.000+08:00| 1|
5063+
+-----------------------------+----------------------------------------------------------------------------+
5064+
```

‎src/UserGuide/latest/SQL-Manual/UDF-Libraries_apache.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4894,3 +4894,89 @@ Output Series:
48944894
|1970-01-01T08:00:00.002+08:00| -0.2571|
48954895
+-----------------------------+---------------------------+
48964896
```
4897+
4898+
### 9.2 Cluster
4899+
4900+
#### Registration statement
4901+
4902+
```sql
4903+
create function cluster as 'org.apache.iotdb.library.dlearn.UDTFCluster'
4904+
```
4905+
4906+
#### Usage
4907+
4908+
This function takes a **single input time series**, splits it into **non-overlapping** contiguous subsequences (windows) of fixed length `l`, and clusters those subsequences into `k` groups.
4909+
4910+
**Name:** Cluster
4911+
4912+
**Input Series:** Only support single input numeric series. The type is INT32 / INT64 / FLOAT / DOUBLE. Points are read in time order; trailing samples that do not fill a full window are dropped (only `⌊n/l⌋` windows are used, where `n` is the number of valid points).
4913+
4914+
**Parameters:**
4915+
4916+
| Name | Meaning | Default | Notes |
4917+
|------|---------|---------|--------|
4918+
| `l` | Subsequence (window) length | (required) | Positive integer; each window has `l` consecutive samples. |
4919+
| `k` | Number of clusters | (required) | Integer ≥ 2. |
4920+
| `method` | Clustering algorithm | `kmeans` | Optional: `kmeans`, `kshape`, `medoidshape` (case-insensitive). Defaults to k-means if omitted. |
4921+
| `norm` | Z-score normalize each subsequence | `true` | Boolean; if `true`, each subsequence is standardized before clustering. |
4922+
| `maxiter` | Maximum iterations | `200` | Positive integer. |
4923+
| `output` | Output mode | `label` | `label`: one cluster id per window; `centroid`: concatenate the `k` centroid vectors in cluster order. |
4924+
| `sample_rate` | Greedy sampling rate | `0.3` | Used only when **`method` = `medoidshape`**; must be in `(0, 1]`. |
4925+
4926+
4927+
**`method` details:**
4928+
4929+
- **kmeans**: k-means in Euclidean space (optionally after per-window normalization).
4930+
- **kshape**: Assign by shape-based distance (SBD from normalized cross-correlation, NCC); centroids updated via SVD on the cluster matrix.
4931+
- **medoidshape**: Coarsely cluster, then greedy selection of `k` representative subsequences; `sample_rate` controls how many candidates are sampled each round.
4932+
4933+
**Output Series:** Controlled by `output`:
4934+
4935+
- **`output` = `label` (default):** One output series, type **INT32**. Number of points = number of full windows, `⌊n/l⌋`. Timestamp of each point = **time of the first sample** in that window; value = cluster id **0 … k−1**.
4936+
- **`output` = `centroid`:** One output series, type **DOUBLE**. Number of points = **`k × l`**: for clusters **0 → k−1**, emit the `l` components of each centroid in order (concatenated). Timestamps are `0, 1, 2, …` (placeholders only, no physical time meaning).
4937+
4938+
**Note:**
4939+
4940+
- Require valid point count `n ≥ l` and window count `⌊n/l⌋ ≥ k`.
4941+
4942+
#### Examples
4943+
4944+
##### KShape: window length 3, k = 2
4945+
4946+
Nine samples `{1,2,3,10,20,30,1,5,1}` form three non-overlapping windows `{1,2,3}`, `{10,20,30}`, `{1,5,1}`. With **`method` = `kshape`** (default `norm` = `true`), each output row is the cluster id for one window; timestamps are the window start times. Resulting labels: **0, 0, 1**.
4947+
4948+
Input Series:
4949+
4950+
```
4951+
+-----------------------------+---------------+
4952+
| Time|root.test.d0.s0|
4953+
+-----------------------------+---------------+
4954+
|2020-01-01T00:00:01.000+08:00| 1.0|
4955+
|2020-01-01T00:00:02.000+08:00| 2.0|
4956+
|2020-01-01T00:00:03.000+08:00| 3.0|
4957+
|2020-01-01T00:00:04.000+08:00| 10.0|
4958+
|2020-01-01T00:00:05.000+08:00| 20.0|
4959+
|2020-01-01T00:00:06.000+08:00| 30.0|
4960+
|2020-01-01T00:00:07.000+08:00| 1.0|
4961+
|2020-01-01T00:00:08.000+08:00| 5.0|
4962+
|2020-01-01T00:00:09.000+08:00| 1.0|
4963+
+-----------------------------+---------------+
4964+
```
4965+
4966+
SQL for query:
4967+
4968+
```sql
4969+
select cluster(s0, "l"="3", "k"="2", "method"="kshape", "output"="label")
4970+
from root.test.d0
4971+
```
4972+
4973+
Output Series:
4974+
4975+
```
4976+
+-----------------------------+----------------------------------------------------------------------------+
4977+
| Time|cluster(root.test.d0.s0,"l"="3","k"="2","method"="kshape","output"="label")|
4978+
+-----------------------------+----------------------------------------------------------------------------+
4979+
|2020-01-01T00:00:01.000+08:00| 0|
4980+
|2020-01-01T00:00:04.000+08:00| 0|
4981+
|2020-01-01T00:00:07.000+08:00| 1|
4982+
+-----------------------------+----------------------------------------------------------------------------+

‎src/UserGuide/latest/SQL-Manual/UDF-Libraries_timecho.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4975,3 +4975,89 @@ Output Series:
49754975
+-----------------------------+---------------------------+
49764976
```
49774977

4978+
### 9.2 Cluster
4979+
4980+
#### Registration statement
4981+
4982+
```sql
4983+
create function cluster as 'org.apache.iotdb.library.dlearn.UDTFCluster'
4984+
```
4985+
4986+
#### Usage
4987+
4988+
This function takes a **single input time series**, splits it into **non-overlapping** contiguous subsequences (windows) of fixed length `l`, and clusters those subsequences into `k` groups.
4989+
4990+
**Name:** Cluster
4991+
4992+
**Input Series:** Only support single input numeric series. The type is INT32 / INT64 / FLOAT / DOUBLE. Points are read in time order; trailing samples that do not fill a full window are dropped (only `⌊n/l⌋` windows are used, where `n` is the number of valid points).
4993+
4994+
**Parameters:**
4995+
4996+
| Name | Meaning | Default | Notes |
4997+
|------|---------|---------|--------|
4998+
| `l` | Subsequence (window) length | (required) | Positive integer; each window has `l` consecutive samples. |
4999+
| `k` | Number of clusters | (required) | Integer ≥ 2. |
5000+
| `method` | Clustering algorithm | `kmeans` | Optional: `kmeans`, `kshape`, `medoidshape` (case-insensitive). Defaults to k-means if omitted. |
5001+
| `norm` | Z-score normalize each subsequence | `true` | Boolean; if `true`, each subsequence is standardized before clustering. |
5002+
| `maxiter` | Maximum iterations | `200` | Positive integer. |
5003+
| `output` | Output mode | `label` | `label`: one cluster id per window; `centroid`: concatenate the `k` centroid vectors in cluster order. |
5004+
| `sample_rate` | Greedy sampling rate | `0.3` | Used only when **`method` = `medoidshape`**; must be in `(0, 1]`. |
5005+
5006+
5007+
**`method` details:**
5008+
5009+
- **kmeans**: k-means in Euclidean space (optionally after per-window normalization).
5010+
- **kshape**: Assign by shape-based distance (SBD from normalized cross-correlation, NCC); centroids updated via SVD on the cluster matrix.
5011+
- **medoidshape**: Coarsely cluster, then greedy selection of `k` representative subsequences; `sample_rate` controls how many candidates are sampled each round.
5012+
5013+
**Output Series:** Controlled by `output`:
5014+
5015+
- **`output` = `label` (default):** One output series, type **INT32**. Number of points = number of full windows, `⌊n/l⌋`. Timestamp of each point = **time of the first sample** in that window; value = cluster id **0 … k−1**.
5016+
- **`output` = `centroid`:** One output series, type **DOUBLE**. Number of points = **`k × l`**: for clusters **0 → k−1**, emit the `l` components of each centroid in order (concatenated). Timestamps are `0, 1, 2, …` (placeholders only, no physical time meaning).
5017+
5018+
**Note:**
5019+
5020+
- Require valid point count `n ≥ l` and window count `⌊n/l⌋ ≥ k`.
5021+
5022+
#### Examples
5023+
5024+
##### KShape: window length 3, k = 2
5025+
5026+
Nine samples `{1,2,3,10,20,30,1,5,1}` form three non-overlapping windows `{1,2,3}`, `{10,20,30}`, `{1,5,1}`. With **`method` = `kshape`** (default `norm` = `true`), each output row is the cluster id for one window; timestamps are the window start times. Resulting labels: **0, 0, 1**.
5027+
5028+
Input Series:
5029+
5030+
```
5031+
+-----------------------------+---------------+
5032+
| Time|root.test.d0.s0|
5033+
+-----------------------------+---------------+
5034+
|2020-01-01T00:00:01.000+08:00| 1.0|
5035+
|2020-01-01T00:00:02.000+08:00| 2.0|
5036+
|2020-01-01T00:00:03.000+08:00| 3.0|
5037+
|2020-01-01T00:00:04.000+08:00| 10.0|
5038+
|2020-01-01T00:00:05.000+08:00| 20.0|
5039+
|2020-01-01T00:00:06.000+08:00| 30.0|
5040+
|2020-01-01T00:00:07.000+08:00| 1.0|
5041+
|2020-01-01T00:00:08.000+08:00| 5.0|
5042+
|2020-01-01T00:00:09.000+08:00| 1.0|
5043+
+-----------------------------+---------------+
5044+
```
5045+
5046+
SQL for query:
5047+
5048+
```sql
5049+
select cluster(s0, "l"="3", "k"="2", "method"="kshape", "output"="label")
5050+
from root.test.d0
5051+
```
5052+
5053+
Output Series:
5054+
5055+
```
5056+
+-----------------------------+----------------------------------------------------------------------------+
5057+
| Time|cluster(root.test.d0.s0,"l"="3","k"="2","method"="kshape","output"="label")|
5058+
+-----------------------------+----------------------------------------------------------------------------+
5059+
|2020-01-01T00:00:01.000+08:00| 0|
5060+
|2020-01-01T00:00:04.000+08:00| 0|
5061+
|2020-01-01T00:00:07.000+08:00| 1|
5062+
+-----------------------------+----------------------------------------------------------------------------+
5063+
```

0 commit comments

Comments
 (0)