From 7691bc352d4ee6e480e001f02df167cfd73c2c3d Mon Sep 17 00:00:00 2001 From: leto-bbq Date: Tue, 3 Nov 2026 10:09:26 +0800 Subject: [PATCH] docs: update table aggregate functions for V2.0.12 --- .../Table/SQL-Manual/Basis-Function_apache.md | 482 ++++-------------- .../SQL-Manual/Basis-Function_apache.md | 482 ++++-------------- .../Table/SQL-Manual/Basis-Function_apache.md | 481 ++++------------- .../SQL-Manual/Basis-Function_apache.md | 481 ++++------------- 4 files changed, 436 insertions(+), 1490 deletions(-) diff --git a/src/UserGuide/Master/Table/SQL-Manual/Basis-Function_apache.md b/src/UserGuide/Master/Table/SQL-Manual/Basis-Function_apache.md index 15f392c82..08bd234df 100644 --- a/src/UserGuide/Master/Table/SQL-Manual/Basis-Function_apache.md +++ b/src/UserGuide/Master/Table/SQL-Manual/Basis-Function_apache.md @@ -163,6 +163,7 @@ SELECT LEAST(temperature,humidity) FROM table2; | APPROX_COUNT_DISTINCT | The APPROX_COUNT_DISTINCT(x[, maxStandardError]) function provides an approximation of COUNT(DISTINCT x), returning the estimated number of distinct input values. | `x`: The target column to be calculated, supports all data types.
`maxStandardError` (optional): Specifies the maximum standard error allowed for the function's result. Valid range is [0.0040625, 0.26]. Defaults to 0.023 if not specified. | INT64 | | APPROX_MOST_FREQUENT | The APPROX_MOST_FREQUENT(x, k, capacity) function is used to approximately calculate the top k most frequent elements in a dataset. It returns a JSON-formatted string where the keys are the element values and the values are their corresponding approximate frequencies. （Available since V2.0.5.1) | `x` : The column to be calculated, supporting all existing data types in IoTDB;
`k`: The number of top-k most frequent values to return;
`capacity`: The number of buckets used for computation, which relates to memory usage—a larger value reduces error but consumes more memory, while a smaller value increases error but uses less memory. | STRING | | APPROX_PERCENTILE | The APPROX_PERCENTILE function calculates the value at a specified percentile in a dataset, helping quickly understand data distribution (e.g., median, quartiles). It supports weighted percentile calculation. If the percentile does not point to an exact position, it returns a linear interpolation of adjacent values at that position.Memory usage depends on the number of centroids, and the maximum number of centroids can be limited using the compression parameter. Error can be estimated using empirical formulas.Note: This function is supported since V2.0.10. | Unweighted Version: APPROX_PERCENTILE(x, percentage)
x: Column to compute. Supports all numeric types: INT32, INT64, FLOAT, DOUBLE, TIMESTAMP.
percentage: Target percentile, DOUBLE type.
Weighted Version: APPROX_PERCENTILE(x, w, percentage)
x: Column to compute. Supports all numeric types: INT32, INT64, FLOAT, DOUBLE, TIMESTAMP.
w: Weight column, integer type (must align with the length of x; NULL or 0 means the row is ignored).
percentage: Target percentile, DOUBLE type. | Same as the input column x. | +| PERCENTILE | `PERCENTILE(x, percentage)` calculates an exact percentile using linear interpolation to help describe the data distribution.
`percentage` must be in `[0, 1]`.
Supported since V2.0.12. | `x`: numeric types, including `INT32`, `INT64`, `FLOAT`, `DOUBLE`, and `TIMESTAMP`.
`percentage`: `DOUBLE`. | Same as the input `x` type | | SUM | Calculates the sum. | INT32 INT64 FLOAT DOUBLE | DOUBLE | | AVG | Calculates the average. | INT32 INT64 FLOAT DOUBLE | DOUBLE | | MAX | Finds the maximum value. | All types | Same as input type | @@ -175,12 +176,30 @@ SELECT LEAST(temperature,humidity) FROM table2; | VARIANCE | Alias for VAR_SAMP, calculates the sample variance. | INT32 INT64 FLOAT DOUBLE | DOUBLE | | VAR_POP | Calculates the population variance. | INT32 INT64 FLOAT DOUBLE | DOUBLE | | VAR_SAMP | Calculates the sample variance. | INT32 INT64 FLOAT DOUBLE | DOUBLE | +| CORR | `CORR(x, y)` calculates the Pearson correlation coefficient of two variables, in the range `[-1, 1]`.
Pairs containing `NULL` are ignored. Returns `NULL` if there are fewer than two valid pairs or either variable has a standard deviation of 0.
Supported since V2.0.12. | `x`, `y`: numeric types, including `INT32`, `INT64`, `FLOAT`, `DOUBLE`, and `TIMESTAMP`. | DOUBLE | +| COVAR_POP | `COVAR_POP(x, y)` calculates the population covariance of two variables.
Pairs containing `NULL` are ignored. Returns `NULL` if there are no valid pairs, or `0.0` if there is only one valid pair.
Supported since V2.0.12. | `x`, `y`: numeric types, including `INT32`, `INT64`, `FLOAT`, `DOUBLE`, and `TIMESTAMP`. | DOUBLE | +| COVAR_SAMP | `COVAR_SAMP(x, y)` calculates the sample covariance of two variables.
Pairs containing `NULL` are ignored. Returns `NULL` if there are fewer than two valid pairs.
Supported since V2.0.12. | `x`, `y`: numeric types, including `INT32`, `INT64`, `FLOAT`, `DOUBLE`, and `TIMESTAMP`. | DOUBLE | +| REGR_SLOPE | `REGR_SLOPE(y, x)` calculates the slope of the least-squares regression line, with `x` as the independent variable and `y` as the dependent variable.
Pairs containing `NULL` are ignored. Returns `NULL` if there are fewer than two valid pairs or `x` has a standard deviation of 0.
Supported since V2.0.12. | `y`, `x`: numeric types, including `INT32`, `INT64`, `FLOAT`, `DOUBLE`, and `TIMESTAMP`. | DOUBLE | +| REGR_INTERCEPT | `REGR_INTERCEPT(y, x)` calculates the intercept of the least-squares regression line, with `x` as the independent variable and `y` as the dependent variable.
Pairs containing `NULL` are ignored. Returns `NULL` if there are fewer than two valid pairs or `x` has a standard deviation of 0.
Supported since V2.0.12. | `y`, `x`: numeric types, including `INT32`, `INT64`, `FLOAT`, `DOUBLE`, and `TIMESTAMP`. | DOUBLE | +| KURTOSIS | `KURTOSIS(x)` calculates the sample excess kurtosis to describe the peakedness and tail weight of a distribution. Ignores `NULL`.
Returns `NULL` if there are fewer than four valid values or the standard deviation is 0.
Supported since V2.0.12. | `x`: numeric types, including `INT32`, `INT64`, `FLOAT`, `DOUBLE`, and `TIMESTAMP`. | DOUBLE | +| SKEWNESS | `SKEWNESS(x)` calculates the sample skewness to describe the asymmetry of a distribution. Ignores `NULL`.
Returns `NULL` if there are fewer than three valid values or the standard deviation is 0.
Supported since V2.0.12. | `x`: numeric types, including `INT32`, `INT64`, `FLOAT`, `DOUBLE`, and `TIMESTAMP`. | DOUBLE | | EXTREME | Finds the value with the largest absolute value. If the largest absolute values of positive and negative values are equal, returns the positive value. | INT32 INT64 FLOAT DOUBLE | Same as input type | | MODE | Finds the mode. Note: 1. There is a risk of memory exception when the number of distinct values in the input sequence is too large; 2. If all elements have the same frequency, i.e., there is no mode, a random element is returned; 3. If there are multiple modes, a random mode is returned; 4. NULL values are also counted in frequency, so even if not all values in the input sequence are NULL, the final result may still be NULL. | All types | Same as input type | | MAX_BY | MAX_BY(x, y) finds the value of x corresponding to the maximum y in the binary input x and y. MAX_BY(time, x) returns the timestamp when x is at its maximum. | x and y can be of any type | Same as the data type of the first input x | | MIN_BY | MIN_BY(x, y) finds the value of x corresponding to the minimum y in the binary input x and y. MIN_BY(time, x) returns the timestamp when x is at its minimum. | x and y can be of any type | Same as the data type of the first input x | | FIRST_BY | FIRST_BY(x, y) finds the value of x in the same row when y is the first non-null value. | x and y can be of any type | Same as the data type of the first input x | | LAST_BY | LAST_BY(x, y) finds the value of x in the same row when y is the last non-null value. | x and y can be of any type | Same as the data type of the first input x | +| RATE | `RATE(value_col, time_col, window_start, window_end)` sorts samples by `time_col` and calculates the average per-second growth rate using all valid samples in `[window_start, window_end)`. Decreases between adjacent samples are treated as counter resets. Applies boundary extrapolation and prevents extrapolation past the counter zero point at the left boundary. Samples in each aggregation group should belong to a single logical counter time series.
Returns `NULL` if there are fewer than two valid non-`NULL` samples.
Supported since V2.0.12. | `value_col`: `INT32`, `INT64`, `FLOAT`, or `DOUBLE`. Non-`NULL` values must be finite and nonnegative; `NULL` values are ignored.
`time_col`, `window_start`, `window_end`: `TIMESTAMP` or `INT64`. `INT64` values are interpreted using the current system `timestamp_precision`.
Requires `window_start < window_end` and `window_start <= time_col < window_end`. Window boundaries must be identical within a group, and valid `time_col` values must be unique. When `value_col` is non-`NULL`, the other arguments must also be non-`NULL`. | `DOUBLE`, in input value units per second | +| IRATE | `IRATE(value_col, time_col)` sorts samples by `time_col` and calculates the instantaneous per-second rate using only the last two valid samples in the current aggregation group. If the latest value is smaller than the previous value, treats this as a counter reset and uses the latest value as the confirmed increase. Does not extrapolate to window boundaries. Samples in each aggregation group should belong to a single logical counter time series.
Returns `NULL` if there are fewer than two valid non-`NULL` samples.
Supported since V2.0.12. | `value_col`: `INT32`, `INT64`, `FLOAT`, or `DOUBLE`. Non-`NULL` values must be finite and nonnegative; `NULL` values are ignored.
`time_col`: `TIMESTAMP` or `INT64`. `INT64` values are interpreted using the current system `timestamp_precision`.
When `value_col` is non-`NULL`, `time_col` must also be non-`NULL`. Valid `time_col` values must be unique within a group. | `DOUBLE`, in input value units per second | +| INCREASE | `INCREASE(value_col, time_col, window_start, window_end)` sorts samples by `time_col` and calculates the total increase over the window using all valid samples in `[window_start, window_end)`. Decreases between adjacent samples are treated as counter resets. Applies boundary extrapolation and prevents extrapolation past the counter zero point at the left boundary. Samples in each aggregation group should belong to a single logical counter time series.
Returns `NULL` if there are fewer than two valid non-`NULL` samples.
Supported since V2.0.12. | `value_col`: `INT32`, `INT64`, `FLOAT`, or `DOUBLE`. Non-`NULL` values must be finite and nonnegative; `NULL` values are ignored.
`time_col`, `window_start`, `window_end`: `TIMESTAMP` or `INT64`. `INT64` values are interpreted using the current system `timestamp_precision`.
Requires `window_start < window_end` and `window_start <= time_col < window_end`. Window boundaries must be identical within a group, and valid `time_col` values must be unique. When `value_col` is non-`NULL`, the other arguments must also be non-`NULL`. | `DOUBLE`, in the same units as `value_col` | +| DELTA | `DELTA(value_col, time_col, window_start, window_end)` sorts samples by `time_col` and calculates the change over the window using all valid samples in `[window_start, window_end)`. Decreases are treated as normal gauge changes, without counter reset correction. Applies boundary extrapolation without counter zero-point protection.
Returns `NULL` if there are fewer than two valid non-`NULL` samples.
Supported since V2.0.12. | `value_col`: `INT32`, `INT64`, `FLOAT`, or `DOUBLE`. Non-`NULL` values must be finite and may be negative; `NULL` values are ignored.
`time_col`, `window_start`, `window_end`: `TIMESTAMP` or `INT64`. `INT64` values are interpreted using the current system `timestamp_precision`.
Requires `window_start < window_end` and `window_start <= time_col < window_end`. Window boundaries must be identical within a group, and valid `time_col` values must be unique. When `value_col` is non-`NULL`, the other arguments must also be non-`NULL`. | `DOUBLE`, in the same units as `value_col`; may be negative | + + +**Notes:** + +1. **Counter reset handling**: A decrease between adjacent samples of a monotonically increasing counter is treated as a counter reset. The increase is corrected to avoid a false negative growth rate. + +2. **Boundary extrapolation**: Based on the average sampling interval within the window, the result is extrapolated toward the window boundaries to estimate the rate, increase, or change over the complete window. ### 2.3 Examples @@ -414,6 +433,96 @@ It costs 0.244s ``` +#### 2.3.13 Rate + +This example uses the `table1` data from Section 2.3.1 and queries `temperature` for `device_id = '100'` between `2024-11-28 08:00:00` and `12:00:00`. The window contains three valid values (`85.0`, `85.0`, and `88.0`); the `NULL` at `09:00:00` is ignored. The `window_start` and `window_end` generated by `TUMBLE()` can be passed directly to `rate()`, `increase()`, and `delta()` as window boundaries. `irate()` only requires the value column and time column. + +```SQL +SELECT + device_id, + window_start, + window_end, + rate(temperature, time, window_start, window_end) AS temperature_rate, + increase(temperature, time, window_start, window_end) AS temperature_increase, + irate(temperature, time) AS temperature_irate, + delta(temperature, time, window_start, window_end) AS temperature_delta +FROM TUMBLE( + DATA => ( + SELECT time, device_id, temperature + FROM table1 + WHERE device_id = '100' + AND time >= 2024-11-28T08:00:00.000+08:00 + AND time < 2024-11-28T12:00:00.000+08:00 + ), + TIMECOL => 'time', + SIZE => 4h +) +GROUP BY device_id, window_start, window_end; +``` + +Result: + +```SQL ++---------+-----------------------------+-----------------------------+--------------------+--------------------+--------------------+-----------------+ +|device_id| window_start| window_end| temperature_rate|temperature_increase| temperature_irate|temperature_delta| ++---------+-----------------------------+-----------------------------+--------------------+--------------------+--------------------+-----------------+ +| 100|2024-11-28T08:00:00.000+08:00|2024-11-28T12:00:00.000+08:00|2.777777777777778E-4| 4.0|8.333333333333334E-4| 4.0| ++---------+-----------------------------+-----------------------------+--------------------+--------------------+--------------------+-----------------+ +Total line number = 1 +It costs 0.132s +``` + +#### 2.3.14 Corr + +The following examples use the `table1` data from Section 2.3.1 to calculate correlation, covariance, linear regression, kurtosis, skewness, and exact percentiles. For bivariate statistics, rows where either `temperature` or `humidity` is `NULL` are ignored. There are eight valid pairs in this example. + +Calculate the correlation coefficient, population covariance, and sample covariance of `temperature` and `humidity`, and the regression slope and intercept of `humidity` with respect to `temperature`: + +```SQL +SELECT + CORR(temperature, humidity), + COVAR_POP(temperature, humidity), + COVAR_SAMP(temperature, humidity), + REGR_SLOPE(humidity, temperature), + REGR_INTERCEPT(humidity, temperature) +FROM table1; +``` + +Result: + +```SQL ++--------------------+------------------+-------------------+-------------------+-----------------+ +| _col0| _col1| _col2| _col3| _col4| ++--------------------+------------------+-------------------+-------------------+-----------------+ +|-0.10559449853747326|-0.737500190734855|-0.8428573608398342|-0.1638889312744123|50.90417003631576| ++--------------------+------------------+-------------------+-------------------+-----------------+ +Total line number = 1 +It costs 0.107s +``` + +After ignoring `NULL`, use the 12 valid `temperature` values to calculate the sample excess kurtosis, sample skewness, and exact 50th percentile: + +```SQL +SELECT + KURTOSIS(temperature), + SKEWNESS(temperature), + PERCENTILE(temperature, 0.5) +FROM table1; +``` + +Result: + +```SQL ++-------------------+------------------+-----+ +| _col0| _col1|_col2| ++-------------------+------------------+-----+ +|-2.2909322273541326|0.1321189313100222| 86.5| ++-------------------+------------------+-----+ +Total line number = 1 +It costs 0.131s +``` + + ## 3. Logical operators ### 3.1 Overview @@ -2016,376 +2125,3 @@ SELECT regexp_like('1a 2b 14m', '^\\d+b$'); -- false - `\d+` means "one or more digits". - `b` represents the letter b. - `'1a 2b 14m'` does not match this pattern because it does not start with digits and does not end with `b`, so it returns `false`. - -## 12. Timeseries Windowing Functions - -The sample data is as follows: - -```SQL -IoTDB> SELECT * FROM bid; -+-----------------------------+--------+-----+ -| time|stock_id|price| -+-----------------------------+--------+-----+ -|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -|2021-01-01T09:15:00.000+08:00| TESL|195.0| -+-----------------------------+--------+-----+ - --- Create table statement -CREATE TABLE bid(time TIMESTAMP TIME, stock_id STRING TAG, price FLOAT FIELD); --- Insert data -INSERT INTO bid(time, stock_id, price) VALUES('2021-01-01T09:05:00','AAPL',100.0),('2021-01-01T09:06:00','TESL',200.0),('2021-01-01T09:07:00','AAPL',103.0),('2021-01-01T09:07:00','TESL',202.0),('2021-01-01T09:09:00','AAPL',102.0),('2021-01-01T09:15:00','TESL',195.0); -``` - -### 12.1 HOP - -#### 12.1.1 Function Description - -The HOP function segments data into overlapping time windows for analysis, assigning each row to all windows that overlap with its timestamp. If windows overlap (when SLIDE < SIZE), data will be duplicated across multiple windows. - -#### 12.1.2 Function Definition - -```SQL -HOP(data, timecol, size, slide[, origin]) -``` - -#### 12.1.3 Parameter Description - -| Parameter | Type | Attributes | Description | -| ----------- | -------- | --------------------------------- | ------------------------- | -| DATA | Table | ROW SEMANTIC, PASS THROUGH | Input table | -| TIMECOL | Scalar | String (default: 'time') | Time column | -| SIZE | Scalar | Long integer | Window size | -| SLIDE | Scalar | Long integer | Sliding step | -| ORIGIN | Scalar | Timestamp (default: Unix epoch) | First window start time | - - -#### 12.1.4 Returned Results - -The HOP function returns: - -* `window_start`: Window start time (inclusive) -* `window_end`: Window end time (exclusive) -* Pass-through columns: All input columns from DATA - -#### 12.1.5 Usage Example - -```SQL -IoTDB> SELECT * FROM HOP(DATA => bid,TIMECOL => 'time',SLIDE => 5m,SIZE => 10m); -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -| window_start| window_end| time|stock_id|price| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:25:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ - --- Equivalent to tree mode's GROUP BY TIME when combined with GROUP BY -IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM HOP(DATA => bid,TIMECOL => 'time',SLIDE => 5m,SIZE => 10m) GROUP BY window_start, window_end, stock_id; -+-----------------------------+-----------------------------+--------+------------------+ -| window_start| window_end|stock_id| avg| -+-----------------------------+-----------------------------+--------+------------------+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| TESL| 201.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL| 201.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00| TESL| 195.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:25:00.000+08:00| TESL| 195.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| AAPL|101.66666666666667| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00| AAPL|101.66666666666667| -+-----------------------------+-----------------------------+--------+------------------+ -``` - -### 12.2 SESSION - -#### 12.2.1 Function Description - -The SESSION function groups data into sessions based on time intervals. It checks the time gap between consecutive rows—rows with gaps smaller than the threshold (GAP) are grouped into the current window, while larger gaps trigger a new window. - -#### 12.2.2 Function Definition - -```SQL -SESSION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], timecol, gap) -``` -#### 12.2.3 Parameter Description - -| Parameter | Type | Attributes | Description | -| ----------- | -------- | ---------------------------- | -------------------------------------- | -| DATA | Table | SET SEMANTIC, PASS THROUGH | Input table with partition/sort keys | -| TIMECOL | Scalar | String (default: 'time') | Time column name | -| GAP | Scalar | Long integer | Session gap threshold | - -#### 12.2.4 Returned Results - -The SESSION function returns: - -* `window_start`: Time of the first row in the session -* `window_end`: Time of the last row in the session -* Pass-through columns: All input columns from DATA - -#### 12.2.5 Usage Example - -```SQL -IoTDB> SELECT * FROM SESSION(DATA => bid PARTITION BY stock_id ORDER BY time,TIMECOL => 'time',GAP => 2m); -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -| window_start| window_end| time|stock_id|price| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:06:00.000+08:00|2021-01-01T09:07:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:06:00.000+08:00|2021-01-01T09:07:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:09:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:09:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:09:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ - --- Equivalent to tree mode's GROUP BY SESSION when combined with GROUP BY -IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM SESSION(DATA => bid PARTITION BY stock_id ORDER BY time,TIMECOL => 'time',GAP => 2m) GROUP BY window_start, window_end, stock_id; -+-----------------------------+-----------------------------+--------+------------------+ -| window_start| window_end|stock_id| avg| -+-----------------------------+-----------------------------+--------+------------------+ -|2021-01-01T09:06:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL| 201.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL| 195.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|101.66666666666667| -+-----------------------------+-----------------------------+--------+------------------+ -``` - -### 12.3 VARIATION - -#### 12.3.1 Function Description - -The VARIATION function groups data based on value differences. The first row becomes the baseline for the first window. Subsequent rows are compared to the baseline—if the difference is within the threshold (DELTA), they join the current window; otherwise, a new window starts with that row as the new baseline. - -#### 12.3.2 Function Definition - -```sql -VARIATION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], col, delta) -``` - -#### 12.3.3 Parameter Description - -| Parameter | Type | Attributes | Description | -| ----------- | -------- | ---------------------------- | -------------------------------------- | -| DATA | Table | SET SEMANTIC, PASS THROUGH | Input table with partition/sort keys | -| COL | Scalar | String | Column for difference calculation | -| DELTA | Scalar | Float | Difference threshold | - -#### 12.3.4 Returned Results - -The VARIATION function returns: - -* `window_index`: Window identifier -* Pass-through columns: All input columns from DATA - -#### 12.3.5 Usage Example - -```sql -IoTDB> SELECT * FROM VARIATION(DATA => bid PARTITION BY stock_id ORDER BY time,COL => 'price',DELTA => 2.0); -+------------+-----------------------------+--------+-----+ -|window_index| time|stock_id|price| -+------------+-----------------------------+--------+-----+ -| 0|2021-01-01T09:06:00.000+08:00| TESL|200.0| -| 0|2021-01-01T09:07:00.000+08:00| TESL|202.0| -| 1|2021-01-01T09:15:00.000+08:00| TESL|195.0| -| 0|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -| 1|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -| 1|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+------------+-----------------------------+--------+-----+ - --- Equivalent to tree mode's GROUP BY VARIATION when combined with GROUP BY -IoTDB> SELECT first(time) as window_start, last(time) as window_end, stock_id, avg(price) as avg FROM VARIATION(DATA => bid PARTITION BY stock_id ORDER BY time,COL => 'price', DELTA => 2.0) GROUP BY window_index, stock_id; -+-----------------------------+-----------------------------+--------+-----+ -| window_start| window_end|stock_id| avg| -+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:06:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|201.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:07:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.5| -+-----------------------------+-----------------------------+--------+-----+ -``` - -### 12.4 CAPACITY - -#### 12.4.1 Function Description - -The CAPACITY function groups data into fixed-size windows, where each window contains up to SIZE rows. - -#### 12.4.2 Function Definition - -```sql -CAPACITY(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], size) -``` - -#### 12.4.3 Parameter Description - -| Parameter | Type | Attributes | Description | -| ----------- | -------- | ---------------------------- | -------------------------------------- | -| DATA | Table | SET SEMANTIC, PASS THROUGH | Input table with partition/sort keys | -| SIZE | Scalar | Long integer | Window size (row count) | - -#### 12.4.4 Returned Results - -The CAPACITY function returns: - -* `window_index`: Window identifier -* Pass-through columns: All input columns from DATA - -#### 12.4.5 Usage Example - -```sql -IoTDB> SELECT * FROM CAPACITY(DATA => bid PARTITION BY stock_id ORDER BY time, SIZE => 2); -+------------+-----------------------------+--------+-----+ -|window_index| time|stock_id|price| -+------------+-----------------------------+--------+-----+ -| 0|2021-01-01T09:06:00.000+08:00| TESL|200.0| -| 0|2021-01-01T09:07:00.000+08:00| TESL|202.0| -| 1|2021-01-01T09:15:00.000+08:00| TESL|195.0| -| 0|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -| 0|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -| 1|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+------------+-----------------------------+--------+-----+ - --- Equivalent to tree mode's GROUP BY COUNT when combined with GROUP BY -IoTDB> SELECT first(time) as start_time, last(time) as end_time, stock_id, avg(price) as avg FROM CAPACITY(DATA => bid PARTITION BY stock_id ORDER BY time, SIZE => 2) GROUP BY window_index, stock_id; -+-----------------------------+-----------------------------+--------+-----+ -| start_time| end_time|stock_id| avg| -+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:06:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|201.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|101.5| -|2021-01-01T09:09:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+-----------------------------+-----------------------------+--------+-----+ -``` - -### 12.5 TUMBLE - -#### 12.5.1 Function Description - -The TUMBLE function assigns each row to a non-overlapping, fixed-size time window based on a timestamp attribute. - -#### 12.5.2 Function Definition - -```sql -TUMBLE(data, timecol, size[, origin]) -``` -#### 12.5.3 Parameter Description - -| Parameter | Type | Attributes | Description | -| ----------- | -------- | --------------------------------- | ------------------------- | -| DATA | Table | ROW SEMANTIC, PASS THROUGH | Input table | -| TIMECOL | Scalar | String (default: 'time') | Time column | -| SIZE | Scalar | Long integer (positive) | Window size | -| ORIGIN | Scalar | Timestamp (default: Unix epoch) | First window start time | - -#### 12.5.4 Returned Results - -The TUMBLE function returns: - -* `window_start`: Window start time (inclusive) -* `window_end`: Window end time (exclusive) -* Pass-through columns: All input columns from DATA - -#### 12.5.5 Usage Example - -```SQL -IoTDB> SELECT * FROM TUMBLE( DATA => bid, TIMECOL => 'time', SIZE => 10m); -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -| window_start| window_end| time|stock_id|price| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ - --- Equivalent to tree mode's GROUP BY TIME when combined with GROUP BY -IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM TUMBLE(DATA => bid, TIMECOL => 'time', SIZE => 10m) GROUP BY window_start, window_end, stock_id; -+-----------------------------+-----------------------------+--------+------------------+ -| window_start| window_end|stock_id| avg| -+-----------------------------+-----------------------------+--------+------------------+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| TESL| 201.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00| TESL| 195.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| AAPL|101.66666666666667| -+-----------------------------+-----------------------------+--------+------------------+ -``` - -### 12.6 CUMULATE - -#### 12.6.1 Function Description - -The CUMULATE function creates expanding windows from an initial window, maintaining the same start time while incrementally extending the end time by STEP until reaching SIZE. Each window contains all elements within its range. For example, with a 1-hour STEP and 24-hour SIZE, daily windows would be: `[00:00, 01:00)`, `[00:00, 02:00)`, ..., `[00:00, 24:00)`. - -#### 12.6.2 Function Definition - -```sql -CUMULATE(data, timecol, size, step[, origin]) -``` - -#### 12.6.3 Parameter Description - -| Parameter | Type | Attributes | Description | -| ----------- | -------- | --------------------------------- | --------------------------------------------------- | -| DATA | Table | ROW SEMANTIC, PASS THROUGH | Input table | -| TIMECOL | Scalar | String (default: 'time') | Time column | -| SIZE | Scalar | Long integer (positive) | Window size (must be an integer multiple of STEP) | -| STEP | Scalar | Long integer (positive) | Expansion step | -| ORIGIN | Scalar | Timestamp (default: Unix epoch) | First window start time | - -> Note: An error `Cumulative table function requires size must be an integral multiple of step` occurs if SIZE is not divisible by STEP. - -#### 12.6.4 Returned Results - -The CUMULATE function returns: - -* `window_start`: Window start time (inclusive) -* `window_end`: Window end time (exclusive) -* Pass-through columns: All input columns from DATA - -#### 12.6.5 Usage Example - -```sql -IoTDB> SELECT * FROM CUMULATE(DATA => bid,TIMECOL => 'time',STEP => 2m,SIZE => 10m); -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -| window_start| window_end| time|stock_id|price| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:16:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:18:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:06:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ - --- Equivalent to tree mode's GROUP BY TIME when combined with GROUP BY -IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM CUMULATE(DATA => bid,TIMECOL => 'time',STEP => 2m, SIZE => 10m) GROUP BY window_start, window_end, stock_id; -+-----------------------------+-----------------------------+--------+------------------+ -| window_start| window_end|stock_id| avg| -+-----------------------------+-----------------------------+--------+------------------+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00| TESL| 201.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| TESL| 201.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:16:00.000+08:00| TESL| 195.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:18:00.000+08:00| TESL| 195.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00| TESL| 195.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:06:00.000+08:00| AAPL| 100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00| AAPL| 101.5| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| AAPL|101.66666666666667| -+-----------------------------+-----------------------------+--------+------------------+ -``` diff --git a/src/UserGuide/latest-Table/SQL-Manual/Basis-Function_apache.md b/src/UserGuide/latest-Table/SQL-Manual/Basis-Function_apache.md index 15f392c82..08bd234df 100644 --- a/src/UserGuide/latest-Table/SQL-Manual/Basis-Function_apache.md +++ b/src/UserGuide/latest-Table/SQL-Manual/Basis-Function_apache.md @@ -163,6 +163,7 @@ SELECT LEAST(temperature,humidity) FROM table2; | APPROX_COUNT_DISTINCT | The APPROX_COUNT_DISTINCT(x[, maxStandardError]) function provides an approximation of COUNT(DISTINCT x), returning the estimated number of distinct input values. | `x`: The target column to be calculated, supports all data types.
`maxStandardError` (optional): Specifies the maximum standard error allowed for the function's result. Valid range is [0.0040625, 0.26]. Defaults to 0.023 if not specified. | INT64 | | APPROX_MOST_FREQUENT | The APPROX_MOST_FREQUENT(x, k, capacity) function is used to approximately calculate the top k most frequent elements in a dataset. It returns a JSON-formatted string where the keys are the element values and the values are their corresponding approximate frequencies. （Available since V2.0.5.1) | `x` : The column to be calculated, supporting all existing data types in IoTDB;
`k`: The number of top-k most frequent values to return;
`capacity`: The number of buckets used for computation, which relates to memory usage—a larger value reduces error but consumes more memory, while a smaller value increases error but uses less memory. | STRING | | APPROX_PERCENTILE | The APPROX_PERCENTILE function calculates the value at a specified percentile in a dataset, helping quickly understand data distribution (e.g., median, quartiles). It supports weighted percentile calculation. If the percentile does not point to an exact position, it returns a linear interpolation of adjacent values at that position.Memory usage depends on the number of centroids, and the maximum number of centroids can be limited using the compression parameter. Error can be estimated using empirical formulas.Note: This function is supported since V2.0.10. | Unweighted Version: APPROX_PERCENTILE(x, percentage)
x: Column to compute. Supports all numeric types: INT32, INT64, FLOAT, DOUBLE, TIMESTAMP.
percentage: Target percentile, DOUBLE type.
Weighted Version: APPROX_PERCENTILE(x, w, percentage)
x: Column to compute. Supports all numeric types: INT32, INT64, FLOAT, DOUBLE, TIMESTAMP.
w: Weight column, integer type (must align with the length of x; NULL or 0 means the row is ignored).
percentage: Target percentile, DOUBLE type. | Same as the input column x. | +| PERCENTILE | `PERCENTILE(x, percentage)` calculates an exact percentile using linear interpolation to help describe the data distribution.
`percentage` must be in `[0, 1]`.
Supported since V2.0.12. | `x`: numeric types, including `INT32`, `INT64`, `FLOAT`, `DOUBLE`, and `TIMESTAMP`.
`percentage`: `DOUBLE`. | Same as the input `x` type | | SUM | Calculates the sum. | INT32 INT64 FLOAT DOUBLE | DOUBLE | | AVG | Calculates the average. | INT32 INT64 FLOAT DOUBLE | DOUBLE | | MAX | Finds the maximum value. | All types | Same as input type | @@ -175,12 +176,30 @@ SELECT LEAST(temperature,humidity) FROM table2; | VARIANCE | Alias for VAR_SAMP, calculates the sample variance. | INT32 INT64 FLOAT DOUBLE | DOUBLE | | VAR_POP | Calculates the population variance. | INT32 INT64 FLOAT DOUBLE | DOUBLE | | VAR_SAMP | Calculates the sample variance. | INT32 INT64 FLOAT DOUBLE | DOUBLE | +| CORR | `CORR(x, y)` calculates the Pearson correlation coefficient of two variables, in the range `[-1, 1]`.
Pairs containing `NULL` are ignored. Returns `NULL` if there are fewer than two valid pairs or either variable has a standard deviation of 0.
Supported since V2.0.12. | `x`, `y`: numeric types, including `INT32`, `INT64`, `FLOAT`, `DOUBLE`, and `TIMESTAMP`. | DOUBLE | +| COVAR_POP | `COVAR_POP(x, y)` calculates the population covariance of two variables.
Pairs containing `NULL` are ignored. Returns `NULL` if there are no valid pairs, or `0.0` if there is only one valid pair.
Supported since V2.0.12. | `x`, `y`: numeric types, including `INT32`, `INT64`, `FLOAT`, `DOUBLE`, and `TIMESTAMP`. | DOUBLE | +| COVAR_SAMP | `COVAR_SAMP(x, y)` calculates the sample covariance of two variables.
Pairs containing `NULL` are ignored. Returns `NULL` if there are fewer than two valid pairs.
Supported since V2.0.12. | `x`, `y`: numeric types, including `INT32`, `INT64`, `FLOAT`, `DOUBLE`, and `TIMESTAMP`. | DOUBLE | +| REGR_SLOPE | `REGR_SLOPE(y, x)` calculates the slope of the least-squares regression line, with `x` as the independent variable and `y` as the dependent variable.
Pairs containing `NULL` are ignored. Returns `NULL` if there are fewer than two valid pairs or `x` has a standard deviation of 0.
Supported since V2.0.12. | `y`, `x`: numeric types, including `INT32`, `INT64`, `FLOAT`, `DOUBLE`, and `TIMESTAMP`. | DOUBLE | +| REGR_INTERCEPT | `REGR_INTERCEPT(y, x)` calculates the intercept of the least-squares regression line, with `x` as the independent variable and `y` as the dependent variable.
Pairs containing `NULL` are ignored. Returns `NULL` if there are fewer than two valid pairs or `x` has a standard deviation of 0.
Supported since V2.0.12. | `y`, `x`: numeric types, including `INT32`, `INT64`, `FLOAT`, `DOUBLE`, and `TIMESTAMP`. | DOUBLE | +| KURTOSIS | `KURTOSIS(x)` calculates the sample excess kurtosis to describe the peakedness and tail weight of a distribution. Ignores `NULL`.
Returns `NULL` if there are fewer than four valid values or the standard deviation is 0.
Supported since V2.0.12. | `x`: numeric types, including `INT32`, `INT64`, `FLOAT`, `DOUBLE`, and `TIMESTAMP`. | DOUBLE | +| SKEWNESS | `SKEWNESS(x)` calculates the sample skewness to describe the asymmetry of a distribution. Ignores `NULL`.
Returns `NULL` if there are fewer than three valid values or the standard deviation is 0.
Supported since V2.0.12. | `x`: numeric types, including `INT32`, `INT64`, `FLOAT`, `DOUBLE`, and `TIMESTAMP`. | DOUBLE | | EXTREME | Finds the value with the largest absolute value. If the largest absolute values of positive and negative values are equal, returns the positive value. | INT32 INT64 FLOAT DOUBLE | Same as input type | | MODE | Finds the mode. Note: 1. There is a risk of memory exception when the number of distinct values in the input sequence is too large; 2. If all elements have the same frequency, i.e., there is no mode, a random element is returned; 3. If there are multiple modes, a random mode is returned; 4. NULL values are also counted in frequency, so even if not all values in the input sequence are NULL, the final result may still be NULL. | All types | Same as input type | | MAX_BY | MAX_BY(x, y) finds the value of x corresponding to the maximum y in the binary input x and y. MAX_BY(time, x) returns the timestamp when x is at its maximum. | x and y can be of any type | Same as the data type of the first input x | | MIN_BY | MIN_BY(x, y) finds the value of x corresponding to the minimum y in the binary input x and y. MIN_BY(time, x) returns the timestamp when x is at its minimum. | x and y can be of any type | Same as the data type of the first input x | | FIRST_BY | FIRST_BY(x, y) finds the value of x in the same row when y is the first non-null value. | x and y can be of any type | Same as the data type of the first input x | | LAST_BY | LAST_BY(x, y) finds the value of x in the same row when y is the last non-null value. | x and y can be of any type | Same as the data type of the first input x | +| RATE | `RATE(value_col, time_col, window_start, window_end)` sorts samples by `time_col` and calculates the average per-second growth rate using all valid samples in `[window_start, window_end)`. Decreases between adjacent samples are treated as counter resets. Applies boundary extrapolation and prevents extrapolation past the counter zero point at the left boundary. Samples in each aggregation group should belong to a single logical counter time series.
Returns `NULL` if there are fewer than two valid non-`NULL` samples.
Supported since V2.0.12. | `value_col`: `INT32`, `INT64`, `FLOAT`, or `DOUBLE`. Non-`NULL` values must be finite and nonnegative; `NULL` values are ignored.
`time_col`, `window_start`, `window_end`: `TIMESTAMP` or `INT64`. `INT64` values are interpreted using the current system `timestamp_precision`.
Requires `window_start < window_end` and `window_start <= time_col < window_end`. Window boundaries must be identical within a group, and valid `time_col` values must be unique. When `value_col` is non-`NULL`, the other arguments must also be non-`NULL`. | `DOUBLE`, in input value units per second | +| IRATE | `IRATE(value_col, time_col)` sorts samples by `time_col` and calculates the instantaneous per-second rate using only the last two valid samples in the current aggregation group. If the latest value is smaller than the previous value, treats this as a counter reset and uses the latest value as the confirmed increase. Does not extrapolate to window boundaries. Samples in each aggregation group should belong to a single logical counter time series.
Returns `NULL` if there are fewer than two valid non-`NULL` samples.
Supported since V2.0.12. | `value_col`: `INT32`, `INT64`, `FLOAT`, or `DOUBLE`. Non-`NULL` values must be finite and nonnegative; `NULL` values are ignored.
`time_col`: `TIMESTAMP` or `INT64`. `INT64` values are interpreted using the current system `timestamp_precision`.
When `value_col` is non-`NULL`, `time_col` must also be non-`NULL`. Valid `time_col` values must be unique within a group. | `DOUBLE`, in input value units per second | +| INCREASE | `INCREASE(value_col, time_col, window_start, window_end)` sorts samples by `time_col` and calculates the total increase over the window using all valid samples in `[window_start, window_end)`. Decreases between adjacent samples are treated as counter resets. Applies boundary extrapolation and prevents extrapolation past the counter zero point at the left boundary. Samples in each aggregation group should belong to a single logical counter time series.
Returns `NULL` if there are fewer than two valid non-`NULL` samples.
Supported since V2.0.12. | `value_col`: `INT32`, `INT64`, `FLOAT`, or `DOUBLE`. Non-`NULL` values must be finite and nonnegative; `NULL` values are ignored.
`time_col`, `window_start`, `window_end`: `TIMESTAMP` or `INT64`. `INT64` values are interpreted using the current system `timestamp_precision`.
Requires `window_start < window_end` and `window_start <= time_col < window_end`. Window boundaries must be identical within a group, and valid `time_col` values must be unique. When `value_col` is non-`NULL`, the other arguments must also be non-`NULL`. | `DOUBLE`, in the same units as `value_col` | +| DELTA | `DELTA(value_col, time_col, window_start, window_end)` sorts samples by `time_col` and calculates the change over the window using all valid samples in `[window_start, window_end)`. Decreases are treated as normal gauge changes, without counter reset correction. Applies boundary extrapolation without counter zero-point protection.
Returns `NULL` if there are fewer than two valid non-`NULL` samples.
Supported since V2.0.12. | `value_col`: `INT32`, `INT64`, `FLOAT`, or `DOUBLE`. Non-`NULL` values must be finite and may be negative; `NULL` values are ignored.
`time_col`, `window_start`, `window_end`: `TIMESTAMP` or `INT64`. `INT64` values are interpreted using the current system `timestamp_precision`.
Requires `window_start < window_end` and `window_start <= time_col < window_end`. Window boundaries must be identical within a group, and valid `time_col` values must be unique. When `value_col` is non-`NULL`, the other arguments must also be non-`NULL`. | `DOUBLE`, in the same units as `value_col`; may be negative | + + +**Notes:** + +1. **Counter reset handling**: A decrease between adjacent samples of a monotonically increasing counter is treated as a counter reset. The increase is corrected to avoid a false negative growth rate. + +2. **Boundary extrapolation**: Based on the average sampling interval within the window, the result is extrapolated toward the window boundaries to estimate the rate, increase, or change over the complete window. ### 2.3 Examples @@ -414,6 +433,96 @@ It costs 0.244s ``` +#### 2.3.13 Rate + +This example uses the `table1` data from Section 2.3.1 and queries `temperature` for `device_id = '100'` between `2024-11-28 08:00:00` and `12:00:00`. The window contains three valid values (`85.0`, `85.0`, and `88.0`); the `NULL` at `09:00:00` is ignored. The `window_start` and `window_end` generated by `TUMBLE()` can be passed directly to `rate()`, `increase()`, and `delta()` as window boundaries. `irate()` only requires the value column and time column. + +```SQL +SELECT + device_id, + window_start, + window_end, + rate(temperature, time, window_start, window_end) AS temperature_rate, + increase(temperature, time, window_start, window_end) AS temperature_increase, + irate(temperature, time) AS temperature_irate, + delta(temperature, time, window_start, window_end) AS temperature_delta +FROM TUMBLE( + DATA => ( + SELECT time, device_id, temperature + FROM table1 + WHERE device_id = '100' + AND time >= 2024-11-28T08:00:00.000+08:00 + AND time < 2024-11-28T12:00:00.000+08:00 + ), + TIMECOL => 'time', + SIZE => 4h +) +GROUP BY device_id, window_start, window_end; +``` + +Result: + +```SQL ++---------+-----------------------------+-----------------------------+--------------------+--------------------+--------------------+-----------------+ +|device_id| window_start| window_end| temperature_rate|temperature_increase| temperature_irate|temperature_delta| ++---------+-----------------------------+-----------------------------+--------------------+--------------------+--------------------+-----------------+ +| 100|2024-11-28T08:00:00.000+08:00|2024-11-28T12:00:00.000+08:00|2.777777777777778E-4| 4.0|8.333333333333334E-4| 4.0| ++---------+-----------------------------+-----------------------------+--------------------+--------------------+--------------------+-----------------+ +Total line number = 1 +It costs 0.132s +``` + +#### 2.3.14 Corr + +The following examples use the `table1` data from Section 2.3.1 to calculate correlation, covariance, linear regression, kurtosis, skewness, and exact percentiles. For bivariate statistics, rows where either `temperature` or `humidity` is `NULL` are ignored. There are eight valid pairs in this example. + +Calculate the correlation coefficient, population covariance, and sample covariance of `temperature` and `humidity`, and the regression slope and intercept of `humidity` with respect to `temperature`: + +```SQL +SELECT + CORR(temperature, humidity), + COVAR_POP(temperature, humidity), + COVAR_SAMP(temperature, humidity), + REGR_SLOPE(humidity, temperature), + REGR_INTERCEPT(humidity, temperature) +FROM table1; +``` + +Result: + +```SQL ++--------------------+------------------+-------------------+-------------------+-----------------+ +| _col0| _col1| _col2| _col3| _col4| ++--------------------+------------------+-------------------+-------------------+-----------------+ +|-0.10559449853747326|-0.737500190734855|-0.8428573608398342|-0.1638889312744123|50.90417003631576| ++--------------------+------------------+-------------------+-------------------+-----------------+ +Total line number = 1 +It costs 0.107s +``` + +After ignoring `NULL`, use the 12 valid `temperature` values to calculate the sample excess kurtosis, sample skewness, and exact 50th percentile: + +```SQL +SELECT + KURTOSIS(temperature), + SKEWNESS(temperature), + PERCENTILE(temperature, 0.5) +FROM table1; +``` + +Result: + +```SQL ++-------------------+------------------+-----+ +| _col0| _col1|_col2| ++-------------------+------------------+-----+ +|-2.2909322273541326|0.1321189313100222| 86.5| ++-------------------+------------------+-----+ +Total line number = 1 +It costs 0.131s +``` + + ## 3. Logical operators ### 3.1 Overview @@ -2016,376 +2125,3 @@ SELECT regexp_like('1a 2b 14m', '^\\d+b$'); -- false - `\d+` means "one or more digits". - `b` represents the letter b. - `'1a 2b 14m'` does not match this pattern because it does not start with digits and does not end with `b`, so it returns `false`. - -## 12. Timeseries Windowing Functions - -The sample data is as follows: - -```SQL -IoTDB> SELECT * FROM bid; -+-----------------------------+--------+-----+ -| time|stock_id|price| -+-----------------------------+--------+-----+ -|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -|2021-01-01T09:15:00.000+08:00| TESL|195.0| -+-----------------------------+--------+-----+ - --- Create table statement -CREATE TABLE bid(time TIMESTAMP TIME, stock_id STRING TAG, price FLOAT FIELD); --- Insert data -INSERT INTO bid(time, stock_id, price) VALUES('2021-01-01T09:05:00','AAPL',100.0),('2021-01-01T09:06:00','TESL',200.0),('2021-01-01T09:07:00','AAPL',103.0),('2021-01-01T09:07:00','TESL',202.0),('2021-01-01T09:09:00','AAPL',102.0),('2021-01-01T09:15:00','TESL',195.0); -``` - -### 12.1 HOP - -#### 12.1.1 Function Description - -The HOP function segments data into overlapping time windows for analysis, assigning each row to all windows that overlap with its timestamp. If windows overlap (when SLIDE < SIZE), data will be duplicated across multiple windows. - -#### 12.1.2 Function Definition - -```SQL -HOP(data, timecol, size, slide[, origin]) -``` - -#### 12.1.3 Parameter Description - -| Parameter | Type | Attributes | Description | -| ----------- | -------- | --------------------------------- | ------------------------- | -| DATA | Table | ROW SEMANTIC, PASS THROUGH | Input table | -| TIMECOL | Scalar | String (default: 'time') | Time column | -| SIZE | Scalar | Long integer | Window size | -| SLIDE | Scalar | Long integer | Sliding step | -| ORIGIN | Scalar | Timestamp (default: Unix epoch) | First window start time | - - -#### 12.1.4 Returned Results - -The HOP function returns: - -* `window_start`: Window start time (inclusive) -* `window_end`: Window end time (exclusive) -* Pass-through columns: All input columns from DATA - -#### 12.1.5 Usage Example - -```SQL -IoTDB> SELECT * FROM HOP(DATA => bid,TIMECOL => 'time',SLIDE => 5m,SIZE => 10m); -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -| window_start| window_end| time|stock_id|price| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:25:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ - --- Equivalent to tree mode's GROUP BY TIME when combined with GROUP BY -IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM HOP(DATA => bid,TIMECOL => 'time',SLIDE => 5m,SIZE => 10m) GROUP BY window_start, window_end, stock_id; -+-----------------------------+-----------------------------+--------+------------------+ -| window_start| window_end|stock_id| avg| -+-----------------------------+-----------------------------+--------+------------------+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| TESL| 201.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL| 201.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00| TESL| 195.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:25:00.000+08:00| TESL| 195.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| AAPL|101.66666666666667| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00| AAPL|101.66666666666667| -+-----------------------------+-----------------------------+--------+------------------+ -``` - -### 12.2 SESSION - -#### 12.2.1 Function Description - -The SESSION function groups data into sessions based on time intervals. It checks the time gap between consecutive rows—rows with gaps smaller than the threshold (GAP) are grouped into the current window, while larger gaps trigger a new window. - -#### 12.2.2 Function Definition - -```SQL -SESSION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], timecol, gap) -``` -#### 12.2.3 Parameter Description - -| Parameter | Type | Attributes | Description | -| ----------- | -------- | ---------------------------- | -------------------------------------- | -| DATA | Table | SET SEMANTIC, PASS THROUGH | Input table with partition/sort keys | -| TIMECOL | Scalar | String (default: 'time') | Time column name | -| GAP | Scalar | Long integer | Session gap threshold | - -#### 12.2.4 Returned Results - -The SESSION function returns: - -* `window_start`: Time of the first row in the session -* `window_end`: Time of the last row in the session -* Pass-through columns: All input columns from DATA - -#### 12.2.5 Usage Example - -```SQL -IoTDB> SELECT * FROM SESSION(DATA => bid PARTITION BY stock_id ORDER BY time,TIMECOL => 'time',GAP => 2m); -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -| window_start| window_end| time|stock_id|price| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:06:00.000+08:00|2021-01-01T09:07:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:06:00.000+08:00|2021-01-01T09:07:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:09:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:09:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:09:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ - --- Equivalent to tree mode's GROUP BY SESSION when combined with GROUP BY -IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM SESSION(DATA => bid PARTITION BY stock_id ORDER BY time,TIMECOL => 'time',GAP => 2m) GROUP BY window_start, window_end, stock_id; -+-----------------------------+-----------------------------+--------+------------------+ -| window_start| window_end|stock_id| avg| -+-----------------------------+-----------------------------+--------+------------------+ -|2021-01-01T09:06:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL| 201.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL| 195.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|101.66666666666667| -+-----------------------------+-----------------------------+--------+------------------+ -``` - -### 12.3 VARIATION - -#### 12.3.1 Function Description - -The VARIATION function groups data based on value differences. The first row becomes the baseline for the first window. Subsequent rows are compared to the baseline—if the difference is within the threshold (DELTA), they join the current window; otherwise, a new window starts with that row as the new baseline. - -#### 12.3.2 Function Definition - -```sql -VARIATION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], col, delta) -``` - -#### 12.3.3 Parameter Description - -| Parameter | Type | Attributes | Description | -| ----------- | -------- | ---------------------------- | -------------------------------------- | -| DATA | Table | SET SEMANTIC, PASS THROUGH | Input table with partition/sort keys | -| COL | Scalar | String | Column for difference calculation | -| DELTA | Scalar | Float | Difference threshold | - -#### 12.3.4 Returned Results - -The VARIATION function returns: - -* `window_index`: Window identifier -* Pass-through columns: All input columns from DATA - -#### 12.3.5 Usage Example - -```sql -IoTDB> SELECT * FROM VARIATION(DATA => bid PARTITION BY stock_id ORDER BY time,COL => 'price',DELTA => 2.0); -+------------+-----------------------------+--------+-----+ -|window_index| time|stock_id|price| -+------------+-----------------------------+--------+-----+ -| 0|2021-01-01T09:06:00.000+08:00| TESL|200.0| -| 0|2021-01-01T09:07:00.000+08:00| TESL|202.0| -| 1|2021-01-01T09:15:00.000+08:00| TESL|195.0| -| 0|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -| 1|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -| 1|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+------------+-----------------------------+--------+-----+ - --- Equivalent to tree mode's GROUP BY VARIATION when combined with GROUP BY -IoTDB> SELECT first(time) as window_start, last(time) as window_end, stock_id, avg(price) as avg FROM VARIATION(DATA => bid PARTITION BY stock_id ORDER BY time,COL => 'price', DELTA => 2.0) GROUP BY window_index, stock_id; -+-----------------------------+-----------------------------+--------+-----+ -| window_start| window_end|stock_id| avg| -+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:06:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|201.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:07:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.5| -+-----------------------------+-----------------------------+--------+-----+ -``` - -### 12.4 CAPACITY - -#### 12.4.1 Function Description - -The CAPACITY function groups data into fixed-size windows, where each window contains up to SIZE rows. - -#### 12.4.2 Function Definition - -```sql -CAPACITY(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], size) -``` - -#### 12.4.3 Parameter Description - -| Parameter | Type | Attributes | Description | -| ----------- | -------- | ---------------------------- | -------------------------------------- | -| DATA | Table | SET SEMANTIC, PASS THROUGH | Input table with partition/sort keys | -| SIZE | Scalar | Long integer | Window size (row count) | - -#### 12.4.4 Returned Results - -The CAPACITY function returns: - -* `window_index`: Window identifier -* Pass-through columns: All input columns from DATA - -#### 12.4.5 Usage Example - -```sql -IoTDB> SELECT * FROM CAPACITY(DATA => bid PARTITION BY stock_id ORDER BY time, SIZE => 2); -+------------+-----------------------------+--------+-----+ -|window_index| time|stock_id|price| -+------------+-----------------------------+--------+-----+ -| 0|2021-01-01T09:06:00.000+08:00| TESL|200.0| -| 0|2021-01-01T09:07:00.000+08:00| TESL|202.0| -| 1|2021-01-01T09:15:00.000+08:00| TESL|195.0| -| 0|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -| 0|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -| 1|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+------------+-----------------------------+--------+-----+ - --- Equivalent to tree mode's GROUP BY COUNT when combined with GROUP BY -IoTDB> SELECT first(time) as start_time, last(time) as end_time, stock_id, avg(price) as avg FROM CAPACITY(DATA => bid PARTITION BY stock_id ORDER BY time, SIZE => 2) GROUP BY window_index, stock_id; -+-----------------------------+-----------------------------+--------+-----+ -| start_time| end_time|stock_id| avg| -+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:06:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|201.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|101.5| -|2021-01-01T09:09:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+-----------------------------+-----------------------------+--------+-----+ -``` - -### 12.5 TUMBLE - -#### 12.5.1 Function Description - -The TUMBLE function assigns each row to a non-overlapping, fixed-size time window based on a timestamp attribute. - -#### 12.5.2 Function Definition - -```sql -TUMBLE(data, timecol, size[, origin]) -``` -#### 12.5.3 Parameter Description - -| Parameter | Type | Attributes | Description | -| ----------- | -------- | --------------------------------- | ------------------------- | -| DATA | Table | ROW SEMANTIC, PASS THROUGH | Input table | -| TIMECOL | Scalar | String (default: 'time') | Time column | -| SIZE | Scalar | Long integer (positive) | Window size | -| ORIGIN | Scalar | Timestamp (default: Unix epoch) | First window start time | - -#### 12.5.4 Returned Results - -The TUMBLE function returns: - -* `window_start`: Window start time (inclusive) -* `window_end`: Window end time (exclusive) -* Pass-through columns: All input columns from DATA - -#### 12.5.5 Usage Example - -```SQL -IoTDB> SELECT * FROM TUMBLE( DATA => bid, TIMECOL => 'time', SIZE => 10m); -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -| window_start| window_end| time|stock_id|price| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ - --- Equivalent to tree mode's GROUP BY TIME when combined with GROUP BY -IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM TUMBLE(DATA => bid, TIMECOL => 'time', SIZE => 10m) GROUP BY window_start, window_end, stock_id; -+-----------------------------+-----------------------------+--------+------------------+ -| window_start| window_end|stock_id| avg| -+-----------------------------+-----------------------------+--------+------------------+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| TESL| 201.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00| TESL| 195.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| AAPL|101.66666666666667| -+-----------------------------+-----------------------------+--------+------------------+ -``` - -### 12.6 CUMULATE - -#### 12.6.1 Function Description - -The CUMULATE function creates expanding windows from an initial window, maintaining the same start time while incrementally extending the end time by STEP until reaching SIZE. Each window contains all elements within its range. For example, with a 1-hour STEP and 24-hour SIZE, daily windows would be: `[00:00, 01:00)`, `[00:00, 02:00)`, ..., `[00:00, 24:00)`. - -#### 12.6.2 Function Definition - -```sql -CUMULATE(data, timecol, size, step[, origin]) -``` - -#### 12.6.3 Parameter Description - -| Parameter | Type | Attributes | Description | -| ----------- | -------- | --------------------------------- | --------------------------------------------------- | -| DATA | Table | ROW SEMANTIC, PASS THROUGH | Input table | -| TIMECOL | Scalar | String (default: 'time') | Time column | -| SIZE | Scalar | Long integer (positive) | Window size (must be an integer multiple of STEP) | -| STEP | Scalar | Long integer (positive) | Expansion step | -| ORIGIN | Scalar | Timestamp (default: Unix epoch) | First window start time | - -> Note: An error `Cumulative table function requires size must be an integral multiple of step` occurs if SIZE is not divisible by STEP. - -#### 12.6.4 Returned Results - -The CUMULATE function returns: - -* `window_start`: Window start time (inclusive) -* `window_end`: Window end time (exclusive) -* Pass-through columns: All input columns from DATA - -#### 12.6.5 Usage Example - -```sql -IoTDB> SELECT * FROM CUMULATE(DATA => bid,TIMECOL => 'time',STEP => 2m,SIZE => 10m); -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -| window_start| window_end| time|stock_id|price| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:16:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:18:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:06:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ - --- Equivalent to tree mode's GROUP BY TIME when combined with GROUP BY -IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM CUMULATE(DATA => bid,TIMECOL => 'time',STEP => 2m, SIZE => 10m) GROUP BY window_start, window_end, stock_id; -+-----------------------------+-----------------------------+--------+------------------+ -| window_start| window_end|stock_id| avg| -+-----------------------------+-----------------------------+--------+------------------+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00| TESL| 201.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| TESL| 201.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:16:00.000+08:00| TESL| 195.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:18:00.000+08:00| TESL| 195.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00| TESL| 195.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:06:00.000+08:00| AAPL| 100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00| AAPL| 101.5| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| AAPL|101.66666666666667| -+-----------------------------+-----------------------------+--------+------------------+ -``` diff --git a/src/zh/UserGuide/Master/Table/SQL-Manual/Basis-Function_apache.md b/src/zh/UserGuide/Master/Table/SQL-Manual/Basis-Function_apache.md index 8377ba9aa..af0b9f84e 100644 --- a/src/zh/UserGuide/Master/Table/SQL-Manual/Basis-Function_apache.md +++ b/src/zh/UserGuide/Master/Table/SQL-Manual/Basis-Function_apache.md @@ -162,6 +162,7 @@ SELECT LEAST(temperature,humidity) FROM table2; | APPROX_COUNT_DISTINCT | APPROX_COUNT_DISTINCT(x[,maxStandardError]) 函数提供 COUNT(DISTINCT x) 的近似值，返回不同输入值的近似个数。 | `x`：待计算列，支持所有类型；
`maxStandardError`：指定该函数应产生的最大标准误差，取值范围[0.0040625, 0.26]，未指定值时默认0.023。 | INT64 | | APPROX_MOST_FREQUENT | APPROX_MOST_FREQUENT(x, k, capacity) 函数用于近似计算数据集中出现频率最高的前 k 个元素。它返回一个JSON 格式的字符串，其中键是该元素的值，值是该元素对应的近似频率。（V 2.0.5.1 及以后版本支持） | `x`：待计算列，支持 IoTDB 现有所有的数据类型；
`k`：返回出现频率最高的 k 个值；
`capacity`: 用于计算的桶的数量，跟内存占用相关：其值越大误差越小，但占用内存更大，反之capacity值越小误差越大，但占用内存更小。 | STRING | | APPROX_PERCENTILE | APPROX_PERCENTILE 函数用于计算数据集中指定百分位数的值，帮助快速了解数据分布情况（如中位数、四分位数等），支持基于权重的百分位数计算；若百分位数不指向精确位置，返回相邻数值在该位置的线性插值。内存占用与质心数量相关，可通过 compression 参数限定最大质心数量，误差可通过经验公式预估。注意：该函数自 V2.0.10 起支持 | 单权重版本：APPROX_PERCENTILE (x, percentage)
x：待计算列，支持 INT32、INT64、FLOAT、DOUBLE、TIMESTAMP 等所有数字类型；
percentage：目标分位数，DOUBLE 类型。
带权重版本：APPROX_PERCENTILE (x, w, percentage)
x：待计算列，支持 INT32、INT64、FLOAT、DOUBLE、TIMESTAMP 等所有数字类型；
w：权重列，整型（与待计算列长度对齐，Null 或 0 表示该行忽略）；
percentage：目标分位数，DOUBLE 类型。 | 与待计算列 x 的类型相同 | +| PERCENTILE | `PERCENTILE(x, percentage)` 使用线性插值精确计算指定百分位数，可用于快速了解数据分布情况。
`percentage` 的取值范围为 `[0, 1]`。
注意：该函数自 V2.0.12 起支持。 | `x`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`、`TIMESTAMP` 等所有数字类型；
`percentage`：`DOUBLE`。 | 与输入 `x` 的类型相同 | | SUM | 求和。 | INT32 INT64 FLOAT DOUBLE | DOUBLE | | AVG | 求平均值。 | INT32 INT64 FLOAT DOUBLE | DOUBLE | | MAX | 求最大值。 | 所有类型 | 与输入类型一致 | @@ -174,12 +175,30 @@ SELECT LEAST(temperature,humidity) FROM table2; | VARIANCE | VAR_SAMP 的别名，求样本方差。 | INT32 INT64 FLOAT DOUBLE | DOUBLE | | VAR_POP | 求总体方差。 | INT32 INT64 FLOAT DOUBLE | DOUBLE | | VAR_SAMP | 求样本方差。 | INT32 INT64 FLOAT DOUBLE | DOUBLE | +| CORR | `CORR(x, y)` 计算两个变量的皮尔逊相关系数，结果范围为 `[-1, 1]`。
包含 `NULL` 的数据对不参与计算；有效数据对不足 2 个或任一变量的标准差为 0 时返回 `NULL`。
注意：该函数自 V2.0.12 起支持。 | `x`、`y`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`、`TIMESTAMP` 等所有数字类型。 | DOUBLE | +| COVAR_POP | `COVAR_POP(x, y)` 计算两个变量的总体协方差。
包含 `NULL` 的数据对不参与计算；没有有效数据对时返回 `NULL`，仅有一个有效数据对时返回 `0.0`。
注意：该函数自 V2.0.12 起支持。 | `x`、`y`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`、`TIMESTAMP` 等所有数字类型。 | DOUBLE | +| COVAR_SAMP | `COVAR_SAMP(x, y)` 计算两个变量的样本协方差。
包含 `NULL` 的数据对不参与计算；有效数据对不足 2 个时返回 `NULL`。
注意：该函数自 V2.0.12 起支持。 | `x`、`y`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`、`TIMESTAMP` 等所有数字类型。 | DOUBLE | +| REGR_SLOPE | `REGR_SLOPE(y, x)` 计算以 `x` 为自变量、`y` 为因变量的最小二乘回归直线斜率。
包含 `NULL` 的数据对不参与计算；有效数据对不足 2 个或 `x` 的标准差为 0 时返回 `NULL`。
注意：该函数自 V2.0.12 起支持。 | `y`、`x`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`、`TIMESTAMP` 等所有数字类型。 | DOUBLE | +| REGR_INTERCEPT | `REGR_INTERCEPT(y, x)` 计算以 `x` 为自变量、`y` 为因变量的最小二乘回归直线截距。
包含 `NULL` 的数据对不参与计算；有效数据对不足 2 个或 `x` 的标准差为 0 时返回 `NULL`。
注意：该函数自 V2.0.12 起支持。 | `y`、`x`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`、`TIMESTAMP` 等所有数字类型。 | DOUBLE | +| KURTOSIS | `KURTOSIS(x)` 计算数据的样本超额峰度，用于衡量分布的陡峭程度和尾部厚度。忽略 `NULL`；
有效数据不足 4 个或标准差为 0 时返回 `NULL`。
注意：该函数自 V2.0.12 起支持。 | `x`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`、`TIMESTAMP` 等所有数字类型。 | DOUBLE | +| SKEWNESS | `SKEWNESS(x)` 计算数据的样本偏度，用于衡量分布的不对称程度。忽略 `NULL`；
有效数据不足 3 个或标准差为 0 时返回 `NULL`。
注意：该函数自 V2.0.12 起支持。 | `x`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`、`TIMESTAMP` 等所有数字类型。 | DOUBLE | | EXTREME | 求具有最大绝对值的值。如果正值和负值的最大绝对值相等，则返回正值。 | INT32 INT64 FLOAT DOUBLE | 与输入类型一致 | | MODE | 求众数。注意： 1.输入序列的不同值个数过多时会有内存异常风险; 2.如果所有元素出现的频次相同，即没有众数，则随机返回一个元素; 3.如果有多个众数，则随机返回一个众数； 4. NULL 值也会被统计频次，所以即使输入序列的值不全为 NULL，最终结果也可能为 NULL。 | 所有类型 | 与输入类型一致 | | MAX_BY | MAX_BY(x, y) 求二元输入 x 和 y 在 y 最大时对应的 x 的值。MAX_BY(time, x) 返回 x 取最大值时对应的时间戳。 | x 和 y 可以是任意类型 | 与第一个输入 x 的数据类型一致 | | MIN_BY | MIN_BY(x, y) 求二元输入 x 和 y 在 y 最小时对应的 x 的值。MIN_BY(time, x) 返回 x 取最小值时对应的时间戳。 | x 和 y 可以是任意类型 | 与第一个输入 x 的数据类型一致 | | FIRST_BY | FIRST_BY(x, y) 求当 y 为第一个不为 NULL 的值时，同一行里对应的 x 值。 | x 和 y 可以是任意类型 | 与第一个输入 x 的数据类型一致 | | LAST_BY | LAST_BY(x, y) 求当 y 为最后一个不为 NULL 的值时，同一行里对应的 x 值。 | x 和 y 可以是任意类型 | 与第一个输入 x 的数据类型一致 | +| RATE | `RATE(value_col, time_col, window_start, window_end)`。按 `time_col` 排序，基于 `[window_start, window_end)` 内全部有效样本计算每秒平均增长速率。相邻样本值下降时按 Counter Reset 修正，并进行边界外推和左侧 Counter 零点保护。同一聚合分组内的样本应属于同一条逻辑 Counter 时序。
有效非 `NULL` 样本少于两个时返回 `NULL`。
注意：该函数自 V2.0.12 起支持。 | `value_col`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`，非 `NULL` 值必须为有限数值且大于或等于 0；`NULL` 值忽略。
`time_col`、`window_start`、`window_end`：`TIMESTAMP`、`INT64`，`INT64` 按系统当前 `timestamp_precision` 解释。
必须满足 `window_start < window_end` 和 `window_start <= time_col < window_end`；同一分组内窗口边界必须一致，不能存在重复的有效 `time_col`。当 `value_col` 非 `NULL` 时，其余参数不能为 `NULL`。 | `DOUBLE`，单位为输入值单位/秒。 | +| IRATE | `IRATE(value_col, time_col)`。按 `time_col` 排序，仅使用当前聚合分组内最后两个有效样本计算瞬时每秒速率。后一个样本值小于前一个样本值时按 Counter Reset 处理，使用最新样本值作为可确认增量；不进行边界外推。同一聚合分组内的样本应属于同一条逻辑 Counter 时序。
有效非 `NULL` 样本少于两个时返回 `NULL`。
注意：该函数自 V2.0.12 起支持。 | `value_col`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`，非 `NULL` 值必须为有限数值且大于或等于 0；`NULL` 值忽略。
`time_col`：`TIMESTAMP`、`INT64`，`INT64` 按系统当前 `timestamp_precision` 解释。
当 `value_col` 非 `NULL` 时，`time_col` 不能为 `NULL`；同一分组内不能存在重复的有效 `time_col`。 | `DOUBLE`，单位为输入值单位/秒。 | +| INCREASE | `INCREASE(value_col, time_col, window_start, window_end)`。按 `time_col` 排序，基于 `[window_start, window_end)` 内全部有效样本计算窗口总增量。相邻样本值下降时按 Counter Reset 修正，并进行边界外推和左侧 Counter 零点保护。同一聚合分组内的样本应属于同一条逻辑 Counter 时序。
有效非 `NULL` 样本少于两个时返回 `NULL`。
注意：该函数自 V2.0.12 起支持。 | `value_col`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`，非 `NULL` 值必须为有限数值且大于或等于 0；`NULL` 值忽略。
`time_col`、`window_start`、`window_end`：`TIMESTAMP`、`INT64`，`INT64` 按系统当前 `timestamp_precision` 解释。
必须满足 `window_start < window_end` 和 `window_start <= time_col < window_end`；同一分组内窗口边界必须一致，不能存在重复的有效 `time_col`。当 `value_col` 非 `NULL` 时，其余参数不能为 `NULL`。 | `DOUBLE`，单位与 `value_col` 相同。 | +| DELTA | `DELTA(value_col, time_col, window_start, window_end)`。按 `time_col` 排序，基于 `[window_start, window_end)` 内全部有效样本计算窗口变化量。样本值下降时按 Gauge 的正常变化处理，不进行 Counter Reset 修正；支持边界外推，但不启用 Counter 零点保护。
有效非 `NULL` 样本少于两个时返回 `NULL`。
注意：该函数自 V2.0.12 起支持。 | `value_col`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`，非 `NULL` 值必须为有限数值，允许为负数；`NULL` 值忽略。
`time_col`、`window_start`、`window_end`：`TIMESTAMP`、`INT64`，`INT64` 按系统当前 `timestamp_precision` 解释。
必须满足 `window_start < window_end` 和 `window_start <= time_col < window_end`；同一分组内窗口边界必须一致，不能存在重复的有效 `time_col`。当 `value_col` 非 `NULL` 时，其余参数不能为 `NULL`。 | `DOUBLE`，单位与 `value_col` 相同，允许返回负数。 | + + +**说明：** + +1. **Counter Reset 处理**：当单调递增计数器的相邻样本值下降时，将其识别为计数器重置并修正增量，避免产生虚假的负增长。 + +2. **边界外推**：根据窗口内样本的平均采样间隔，将计算结果向窗口起止边界适当延伸，以估算完整窗口内的速率、增量或变化量。 ### 2.3 示例 @@ -414,6 +433,96 @@ It costs 0.244s ``` +#### 2.3.13 Rate + +以下示例使用 2.3.1 中的 `table1` 数据，查询 `device_id = '100'` 在 `2024-11-28 08:00:00` 至 `12:00:00` 的 `temperature`。窗口内有 3 个有效值（`85.0`、`85.0`、`88.0`），`09:00:00` 的 `NULL` 不参与计算。`TUMBLE()` 生成的 `window_start` 和 `window_end` 可直接作为 `rate()`、`increase()` 和 `delta()` 的窗口边界；`irate()` 只需传入数值列和时间列。 + +```SQL +SELECT + device_id, + window_start, + window_end, + rate(temperature, time, window_start, window_end) AS temperature_rate, + increase(temperature, time, window_start, window_end) AS temperature_increase, + irate(temperature, time) AS temperature_irate, + delta(temperature, time, window_start, window_end) AS temperature_delta +FROM TUMBLE( + DATA => ( + SELECT time, device_id, temperature + FROM table1 + WHERE device_id = '100' + AND time >= 2024-11-28T08:00:00.000+08:00 + AND time < 2024-11-28T12:00:00.000+08:00 + ), + TIMECOL => 'time', + SIZE => 4h +) +GROUP BY device_id, window_start, window_end; +``` + +执行结果如下： + +```SQL ++---------+-----------------------------+-----------------------------+--------------------+--------------------+--------------------+-----------------+ +|device_id| window_start| window_end| temperature_rate|temperature_increase| temperature_irate|temperature_delta| ++---------+-----------------------------+-----------------------------+--------------------+--------------------+--------------------+-----------------+ +| 100|2024-11-28T08:00:00.000+08:00|2024-11-28T12:00:00.000+08:00|2.777777777777778E-4| 4.0|8.333333333333334E-4| 4.0| ++---------+-----------------------------+-----------------------------+--------------------+--------------------+--------------------+-----------------+ +Total line number = 1 +It costs 0.132s +``` + +#### 2.3.14 Corr + +以下示例使用 2.3.1 中 `table1` 的示例数据，演示相关性、协方差、线性回归、峰度、偏度和精确百分位数的计算。计算双变量统计量时，只要 `temperature` 或 `humidity` 为 `NULL`，该行就不会参与计算；本例共有 8 组有效数据对。 + +计算 `temperature` 与 `humidity` 的相关系数、总体协方差和样本协方差，并计算 `humidity` 关于 `temperature` 的回归斜率与截距： + +```SQL +SELECT + CORR(temperature, humidity), + COVAR_POP(temperature, humidity), + COVAR_SAMP(temperature, humidity), + REGR_SLOPE(humidity, temperature), + REGR_INTERCEPT(humidity, temperature) +FROM table1; +``` + +执行结果如下： + +```SQL ++--------------------+------------------+-------------------+-------------------+-----------------+ +| _col0| _col1| _col2| _col3| _col4| ++--------------------+------------------+-------------------+-------------------+-----------------+ +|-0.10559449853747326|-0.737500190734855|-0.8428573608398342|-0.1638889312744123|50.90417003631576| ++--------------------+------------------+-------------------+-------------------+-----------------+ +Total line number = 1 +It costs 0.107s +``` + +忽略 `NULL` 后，使用 12 个有效的 `temperature` 值计算样本超额峰度、样本偏度和 50% 精确百分位数： + +```SQL +SELECT + KURTOSIS(temperature), + SKEWNESS(temperature), + PERCENTILE(temperature, 0.5) +FROM table1; +``` + +执行结果如下： + +```SQL ++-------------------+------------------+-----+ +| _col0| _col1|_col2| ++-------------------+------------------+-----+ +|-2.2909322273541326|0.1321189313100222| 86.5| ++-------------------+------------------+-----+ +Total line number = 1 +It costs 0.131s +``` + + ## 3. 逻辑运算符 ### 3.1 概述 @@ -2295,375 +2404,3 @@ SELECT regexp_like('1a 2b 14m', '^\\d+b$'); -- false - `\d+` 表示“一个或多个数字”。 - `b` 表示字母 `b`。 - `'1a 2b 14m'` 并不符合这个模式，因为它不是从数字开始，也不是以 `b` 结束，所以返回 `false`。 - -## 12. 时序分窗函数 - -原始示例数据如下： - -```SQL -IoTDB> SELECT * FROM bid; -+-----------------------------+--------+-----+ -| time|stock_id|price| -+-----------------------------+--------+-----+ -|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -|2021-01-01T09:15:00.000+08:00| TESL|195.0| -+-----------------------------+--------+-----+ - --- 创建语句 -CREATE TABLE bid(time TIMESTAMP TIME, stock_id STRING TAG, price FLOAT FIELD); --- 插入数据 -INSERT INTO bid(time, stock_id, price) VALUES('2021-01-01T09:05:00','AAPL',100.0),('2021-01-01T09:06:00','TESL',200.0),('2021-01-01T09:07:00','AAPL',103.0),('2021-01-01T09:07:00','TESL',202.0),('2021-01-01T09:09:00','AAPL',102.0),('2021-01-01T09:15:00','TESL',195.0); -``` - -### 12.1 HOP - -#### 12.1.1 功能描述 - -HOP 函数用于按时间分段分窗分析，识别每一行数据所属的时间窗口。该函数通过指定固定窗口大小（size）和窗口滑动步长（SLIDE），将数据按时间戳分配到所有与其时间戳重叠的窗口中。若窗口之间存在重叠（步长 < 窗口大小），数据会自动复制到多个窗口。 - -#### 12.1.2 函数定义 - -```SQL -HOP(data, timecol, size, slide[, origin]) -``` - -#### 12.1.3 参数说明 - -| 参数名 | 参数类型 | 参数属性 | 描述 | -| --------- | ---------- | --------------------------------- | -------------------- | -| DATA | 表参数 | ROW SEMANTICPASS THROUGH | 输入表 | -| TIMECOL | 标量参数 | 字符串类型默认值：time | 时间列 | -| SIZE | 标量参数 | 长整数类型 | 窗口大小 | -| SLIDE | 标量参数 | 长整数类型 | 窗口滑动步长 | -| ORIGIN | 标量参数 | 时间戳类型默认值：Unix 纪元时间 | 第一个窗口起始时间 | - -#### 12.1.4 返回结果 - -HOP 函数的返回结果列包含： - -* window\_start: 窗口开始时间（闭区间） -* window\_end: 窗口结束时间（开区间） -* 映射列：DATA 参数的所有输入列 - -#### 12.1.5 使用示例 - -```SQL -IoTDB> SELECT * FROM HOP(DATA => bid,TIMECOL => 'time',SLIDE => 5m,SIZE => 10m); -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -| window_start| window_end| time|stock_id|price| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:25:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ - --- 结合 GROUP BY 语句，等效于树模型的 GROUP BY TIME -IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM HOP(DATA => bid,TIMECOL => 'time',SLIDE => 5m,SIZE => 10m) GROUP BY window_start, window_end, stock_id; -+-----------------------------+-----------------------------+--------+------------------+ -| window_start| window_end|stock_id| avg| -+-----------------------------+-----------------------------+--------+------------------+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| TESL| 201.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL| 201.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00| TESL| 195.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:25:00.000+08:00| TESL| 195.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| AAPL|101.66666666666667| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00| AAPL|101.66666666666667| -+-----------------------------+-----------------------------+--------+------------------+ -``` - -### 12.2 SESSION - -#### 12.2.1 功能描述 - -SESSION 函数用于按会话间隔对数据进行分窗。系统逐行检查与前一行的时间间隔，小于阈值（GAP）则归入当前窗口，超过则归入下一个窗口。 - -#### 12.2.2 函数定义 - -```SQL -SESSION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], timecol, gap) -``` -#### 12.2.3 参数说明 - -| 参数名 | 参数类型 | 参数属性 | 描述 | -| --------- | ---------- | -------------------------- | ---------------------------------------- | -| DATA | 表参数 | SET SEMANTICPASS THROUGH | 输入表通过 pkeys、okeys 指定分区和排序 | -| TIMECOL | 标量参数 | 字符串类型默认值：'time' | 时间列名 | -| GAP | 标量参数 | 长整数类型 | 会话间隔阈值 | - -#### 12.2.4 返回结果 - -SESSION 函数的返回结果列包含： - -* window\_start: 会话窗口内的第一条数据的时间 -* window\_end: 会话窗口内的最后一条数据的时间 -* 映射列：DATA 参数的所有输入列 - -#### 12.2.5 使用示例 - -```SQL -IoTDB> SELECT * FROM SESSION(DATA => bid PARTITION BY stock_id ORDER BY time,TIMECOL => 'time',GAP => 2m); -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -| window_start| window_end| time|stock_id|price| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:06:00.000+08:00|2021-01-01T09:07:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:06:00.000+08:00|2021-01-01T09:07:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:09:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:09:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:09:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ - --- 结合 GROUP BY 语句，等效于树模型的 GROUP BY SESSION -IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM SESSION(DATA => bid PARTITION BY stock_id ORDER BY time,TIMECOL => 'time',GAP => 2m) GROUP BY window_start, window_end, stock_id; -+-----------------------------+-----------------------------+--------+------------------+ -| window_start| window_end|stock_id| avg| -+-----------------------------+-----------------------------+--------+------------------+ -|2021-01-01T09:06:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL| 201.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL| 195.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|101.66666666666667| -+-----------------------------+-----------------------------+--------+------------------+ -``` - -### 12.3 VARIATION - -#### 12.3.1 功能描述 - -VARIATION 函数用于按数据差值分窗，将第一条数据作为首个窗口的基准值，每个数据点会与基准值进行差值运算，如果差值小于给定的阈值（delta）则加入当前窗口；如果超过阈值，则分为下一个窗口，将该值作为下一个窗口的基准值。 - -#### 12.3.2 函数定义 - -```sql -VARIATION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], col, delta) -``` - -#### 12.3.3 参数说明 - -| 参数名 | 参数类型 | 参数属性 | 描述 | -| -------- | ---------- | -------------------------- | ---------------------------------------- | -| DATA | 表参数 | SET SEMANTICPASS THROUGH | 输入表通过 pkeys、okeys 指定分区和排序 | -| COL | 标量参数 | 字符串类型 | 标识对哪一列计算差值 | -| DELTA | 标量参数 | 浮点数类型 | 差值阈值 | - -#### 12.3.4 返回结果 - -VARIATION 函数的返回结果列包含： - -* window\_index: 窗口编号 -* 映射列：DATA 参数的所有输入列 - -#### 12.3.5 使用示例 - -```sql -IoTDB> SELECT * FROM VARIATION(DATA => bid PARTITION BY stock_id ORDER BY time,COL => 'price',DELTA => 2.0); -+------------+-----------------------------+--------+-----+ -|window_index| time|stock_id|price| -+------------+-----------------------------+--------+-----+ -| 0|2021-01-01T09:06:00.000+08:00| TESL|200.0| -| 0|2021-01-01T09:07:00.000+08:00| TESL|202.0| -| 1|2021-01-01T09:15:00.000+08:00| TESL|195.0| -| 0|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -| 1|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -| 1|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+------------+-----------------------------+--------+-----+ - --- 结合 GROUP BY 语句，等效于树模型的 GROUP BY VARIATION -IoTDB> SELECT first(time) as window_start, last(time) as window_end, stock_id, avg(price) as avg FROM VARIATION(DATA => bid PARTITION BY stock_id ORDER BY time,COL => 'price', DELTA => 2.0) GROUP BY window_index, stock_id; -+-----------------------------+-----------------------------+--------+-----+ -| window_start| window_end|stock_id| avg| -+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:06:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|201.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:07:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.5| -+-----------------------------+-----------------------------+--------+-----+ -``` - -### 12.4 CAPACITY - -#### 12.4.1 功能描述 - -CAPACITY 函数用于按数据点数（行数）分窗，每个窗口最多有 SIZE 行数据。 - -#### 12.4.2 函数定义 - -```sql -CAPACITY(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], size) -``` - -#### 12.4.3 参数说明 - -| 参数名 | 参数类型 | 参数属性 | 描述 | -| -------- | ---------- | -------------------------- | ---------------------------------------- | -| DATA | 表参数 | SET SEMANTICPASS THROUGH | 输入表通过 pkeys、okeys 指定分区和排序 | -| SIZE | 标量参数 | 长整数类型 | 窗口大小 | - -#### 12.4.4 返回结果 - -CAPACITY 函数的返回结果列包含： - -* window\_index: 窗口编号 -* 映射列：DATA 参数的所有输入列 - -#### 12.4.5 使用示例 - -```sql -IoTDB> SELECT * FROM CAPACITY(DATA => bid PARTITION BY stock_id ORDER BY time, SIZE => 2); -+------------+-----------------------------+--------+-----+ -|window_index| time|stock_id|price| -+------------+-----------------------------+--------+-----+ -| 0|2021-01-01T09:06:00.000+08:00| TESL|200.0| -| 0|2021-01-01T09:07:00.000+08:00| TESL|202.0| -| 1|2021-01-01T09:15:00.000+08:00| TESL|195.0| -| 0|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -| 0|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -| 1|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+------------+-----------------------------+--------+-----+ - --- 结合 GROUP BY 语句，等效于树模型的 GROUP BY COUNT -IoTDB> SELECT first(time) as start_time, last(time) as end_time, stock_id, avg(price) as avg FROM CAPACITY(DATA => bid PARTITION BY stock_id ORDER BY time, SIZE => 2) GROUP BY window_index, stock_id; -+-----------------------------+-----------------------------+--------+-----+ -| start_time| end_time|stock_id| avg| -+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:06:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|201.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|101.5| -|2021-01-01T09:09:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+-----------------------------+-----------------------------+--------+-----+ -``` - -### 12.5 TUMBLE - -#### 12.5.1 功能描述 - -TUMBLE 函数用于通过时间属性字段为每行数据分配一个窗口，滚动窗口的大小固定且不重复。 - -#### 12.5.2 函数定义 - -```sql -TUMBLE(data, timecol, size[, origin]) -``` -#### 12.5.3 参数说明 - -| 参数名 | 参数类型 | 参数属性 | 描述 | -| --------- | ---------- | --------------------------------- | -------------------- | -| DATA | 表参数 | ROW SEMANTICPASS THROUGH | 输入表 | -| TIMECOL | 标量参数 | 字符串类型默认值：time | 时间列 | -| SIZE | 标量参数 | 长整数类型 | 窗口大小，需为正数 | -| ORIGIN | 标量参数 | 时间戳类型默认值：Unix 纪元时间 | 第一个窗口起始时间 | - -#### 12.5.4 返回结果 - -TUBMLE 函数的返回结果列包含： - -* window\_start: 窗口开始时间（闭区间） -* window\_end: 窗口结束时间（开区间） -* 映射列：DATA 参数的所有输入列 - -#### 12.5.5 使用示例 - -```SQL -IoTDB> SELECT * FROM TUMBLE( DATA => bid, TIMECOL => 'time', SIZE => 10m); -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -| window_start| window_end| time|stock_id|price| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ - --- 结合 GROUP BY 语句，等效于树模型的 GROUP BY TIME -IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM TUMBLE(DATA => bid, TIMECOL => 'time', SIZE => 10m) GROUP BY window_start, window_end, stock_id; -+-----------------------------+-----------------------------+--------+------------------+ -| window_start| window_end|stock_id| avg| -+-----------------------------+-----------------------------+--------+------------------+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| TESL| 201.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00| TESL| 195.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| AAPL|101.66666666666667| -+-----------------------------+-----------------------------+--------+------------------+ -``` - -### 12.6 CUMULATE - -#### 12.6.1 功能描述 - -Cumulate 函数用于从初始的窗口开始，创建相同窗口开始但窗口结束步长不同的窗口，直到达到最大的窗口大小。每个窗口包含其区间内的元素。例如：1小时步长，24小时大小的累计窗口，每天可以获得如下这些窗口：`[00:00, 01:00)`，`[00:00, 02:00)`，`[00:00, 03:00)`， …， `[00:00, 24:00)` - -#### 12.6.2 函数定义 - -```sql -CUMULATE(data, timecol, size, step[, origin]) -``` - -#### 12.6.3 参数说明 - -| 参数名 | 参数类型 | 参数属性 | 描述 | -| --------- | ---------- | --------------------------------- | -------------------------------------------- | -| DATA | 表参数 | ROW SEMANTICPASS THROUGH | 输入表 | -| TIMECOL | 标量参数 | 字符串类型默认值：time | 时间列 | -| SIZE | 标量参数 | 长整数类型 | 窗口大小，SIZE必须是STEP的整数倍，需为正数 | -| STEP | 标量参数 | 长整数类型 | 窗口步长，需为正数 | -| ORIGIN | 标量参数 | 时间戳类型默认值：Unix 纪元时间 | 第一个窗口起始时间 | - -> 注意：size 如果不是 step 的整数倍，则会报错`Cumulative table function requires size must be an integral multiple of step` - -#### 12.6.4 返回结果 - -CUMULATE函数的返回结果列包含： - -* window\_start: 窗口开始时间（闭区间） -* window\_end: 窗口结束时间（开区间） -* 映射列：DATA 参数的所有输入列 - -#### 12.6.5 使用示例 - -```sql -IoTDB> SELECT * FROM CUMULATE(DATA => bid,TIMECOL => 'time',STEP => 2m,SIZE => 10m); -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -| window_start| window_end| time|stock_id|price| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:16:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:18:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:06:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ - --- 结合 GROUP BY 语句，等效于树模型的 GROUP BY TIME -IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM CUMULATE(DATA => bid,TIMECOL => 'time',STEP => 2m, SIZE => 10m) GROUP BY window_start, window_end, stock_id; -+-----------------------------+-----------------------------+--------+------------------+ -| window_start| window_end|stock_id| avg| -+-----------------------------+-----------------------------+--------+------------------+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00| TESL| 201.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| TESL| 201.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:16:00.000+08:00| TESL| 195.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:18:00.000+08:00| TESL| 195.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00| TESL| 195.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:06:00.000+08:00| AAPL| 100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00| AAPL| 101.5| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| AAPL|101.66666666666667| -+-----------------------------+-----------------------------+--------+------------------+ -``` diff --git a/src/zh/UserGuide/latest-Table/SQL-Manual/Basis-Function_apache.md b/src/zh/UserGuide/latest-Table/SQL-Manual/Basis-Function_apache.md index 8377ba9aa..af0b9f84e 100644 --- a/src/zh/UserGuide/latest-Table/SQL-Manual/Basis-Function_apache.md +++ b/src/zh/UserGuide/latest-Table/SQL-Manual/Basis-Function_apache.md @@ -162,6 +162,7 @@ SELECT LEAST(temperature,humidity) FROM table2; | APPROX_COUNT_DISTINCT | APPROX_COUNT_DISTINCT(x[,maxStandardError]) 函数提供 COUNT(DISTINCT x) 的近似值，返回不同输入值的近似个数。 | `x`：待计算列，支持所有类型；
`maxStandardError`：指定该函数应产生的最大标准误差，取值范围[0.0040625, 0.26]，未指定值时默认0.023。 | INT64 | | APPROX_MOST_FREQUENT | APPROX_MOST_FREQUENT(x, k, capacity) 函数用于近似计算数据集中出现频率最高的前 k 个元素。它返回一个JSON 格式的字符串，其中键是该元素的值，值是该元素对应的近似频率。（V 2.0.5.1 及以后版本支持） | `x`：待计算列，支持 IoTDB 现有所有的数据类型；
`k`：返回出现频率最高的 k 个值；
`capacity`: 用于计算的桶的数量，跟内存占用相关：其值越大误差越小，但占用内存更大，反之capacity值越小误差越大，但占用内存更小。 | STRING | | APPROX_PERCENTILE | APPROX_PERCENTILE 函数用于计算数据集中指定百分位数的值，帮助快速了解数据分布情况（如中位数、四分位数等），支持基于权重的百分位数计算；若百分位数不指向精确位置，返回相邻数值在该位置的线性插值。内存占用与质心数量相关，可通过 compression 参数限定最大质心数量，误差可通过经验公式预估。注意：该函数自 V2.0.10 起支持 | 单权重版本：APPROX_PERCENTILE (x, percentage)
x：待计算列，支持 INT32、INT64、FLOAT、DOUBLE、TIMESTAMP 等所有数字类型；
percentage：目标分位数，DOUBLE 类型。
带权重版本：APPROX_PERCENTILE (x, w, percentage)
x：待计算列，支持 INT32、INT64、FLOAT、DOUBLE、TIMESTAMP 等所有数字类型；
w：权重列，整型（与待计算列长度对齐，Null 或 0 表示该行忽略）；
percentage：目标分位数，DOUBLE 类型。 | 与待计算列 x 的类型相同 | +| PERCENTILE | `PERCENTILE(x, percentage)` 使用线性插值精确计算指定百分位数，可用于快速了解数据分布情况。
`percentage` 的取值范围为 `[0, 1]`。
注意：该函数自 V2.0.12 起支持。 | `x`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`、`TIMESTAMP` 等所有数字类型；
`percentage`：`DOUBLE`。 | 与输入 `x` 的类型相同 | | SUM | 求和。 | INT32 INT64 FLOAT DOUBLE | DOUBLE | | AVG | 求平均值。 | INT32 INT64 FLOAT DOUBLE | DOUBLE | | MAX | 求最大值。 | 所有类型 | 与输入类型一致 | @@ -174,12 +175,30 @@ SELECT LEAST(temperature,humidity) FROM table2; | VARIANCE | VAR_SAMP 的别名，求样本方差。 | INT32 INT64 FLOAT DOUBLE | DOUBLE | | VAR_POP | 求总体方差。 | INT32 INT64 FLOAT DOUBLE | DOUBLE | | VAR_SAMP | 求样本方差。 | INT32 INT64 FLOAT DOUBLE | DOUBLE | +| CORR | `CORR(x, y)` 计算两个变量的皮尔逊相关系数，结果范围为 `[-1, 1]`。
包含 `NULL` 的数据对不参与计算；有效数据对不足 2 个或任一变量的标准差为 0 时返回 `NULL`。
注意：该函数自 V2.0.12 起支持。 | `x`、`y`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`、`TIMESTAMP` 等所有数字类型。 | DOUBLE | +| COVAR_POP | `COVAR_POP(x, y)` 计算两个变量的总体协方差。
包含 `NULL` 的数据对不参与计算；没有有效数据对时返回 `NULL`，仅有一个有效数据对时返回 `0.0`。
注意：该函数自 V2.0.12 起支持。 | `x`、`y`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`、`TIMESTAMP` 等所有数字类型。 | DOUBLE | +| COVAR_SAMP | `COVAR_SAMP(x, y)` 计算两个变量的样本协方差。
包含 `NULL` 的数据对不参与计算；有效数据对不足 2 个时返回 `NULL`。
注意：该函数自 V2.0.12 起支持。 | `x`、`y`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`、`TIMESTAMP` 等所有数字类型。 | DOUBLE | +| REGR_SLOPE | `REGR_SLOPE(y, x)` 计算以 `x` 为自变量、`y` 为因变量的最小二乘回归直线斜率。
包含 `NULL` 的数据对不参与计算；有效数据对不足 2 个或 `x` 的标准差为 0 时返回 `NULL`。
注意：该函数自 V2.0.12 起支持。 | `y`、`x`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`、`TIMESTAMP` 等所有数字类型。 | DOUBLE | +| REGR_INTERCEPT | `REGR_INTERCEPT(y, x)` 计算以 `x` 为自变量、`y` 为因变量的最小二乘回归直线截距。
包含 `NULL` 的数据对不参与计算；有效数据对不足 2 个或 `x` 的标准差为 0 时返回 `NULL`。
注意：该函数自 V2.0.12 起支持。 | `y`、`x`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`、`TIMESTAMP` 等所有数字类型。 | DOUBLE | +| KURTOSIS | `KURTOSIS(x)` 计算数据的样本超额峰度，用于衡量分布的陡峭程度和尾部厚度。忽略 `NULL`；
有效数据不足 4 个或标准差为 0 时返回 `NULL`。
注意：该函数自 V2.0.12 起支持。 | `x`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`、`TIMESTAMP` 等所有数字类型。 | DOUBLE | +| SKEWNESS | `SKEWNESS(x)` 计算数据的样本偏度，用于衡量分布的不对称程度。忽略 `NULL`；
有效数据不足 3 个或标准差为 0 时返回 `NULL`。
注意：该函数自 V2.0.12 起支持。 | `x`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`、`TIMESTAMP` 等所有数字类型。 | DOUBLE | | EXTREME | 求具有最大绝对值的值。如果正值和负值的最大绝对值相等，则返回正值。 | INT32 INT64 FLOAT DOUBLE | 与输入类型一致 | | MODE | 求众数。注意： 1.输入序列的不同值个数过多时会有内存异常风险; 2.如果所有元素出现的频次相同，即没有众数，则随机返回一个元素; 3.如果有多个众数，则随机返回一个众数； 4. NULL 值也会被统计频次，所以即使输入序列的值不全为 NULL，最终结果也可能为 NULL。 | 所有类型 | 与输入类型一致 | | MAX_BY | MAX_BY(x, y) 求二元输入 x 和 y 在 y 最大时对应的 x 的值。MAX_BY(time, x) 返回 x 取最大值时对应的时间戳。 | x 和 y 可以是任意类型 | 与第一个输入 x 的数据类型一致 | | MIN_BY | MIN_BY(x, y) 求二元输入 x 和 y 在 y 最小时对应的 x 的值。MIN_BY(time, x) 返回 x 取最小值时对应的时间戳。 | x 和 y 可以是任意类型 | 与第一个输入 x 的数据类型一致 | | FIRST_BY | FIRST_BY(x, y) 求当 y 为第一个不为 NULL 的值时，同一行里对应的 x 值。 | x 和 y 可以是任意类型 | 与第一个输入 x 的数据类型一致 | | LAST_BY | LAST_BY(x, y) 求当 y 为最后一个不为 NULL 的值时，同一行里对应的 x 值。 | x 和 y 可以是任意类型 | 与第一个输入 x 的数据类型一致 | +| RATE | `RATE(value_col, time_col, window_start, window_end)`。按 `time_col` 排序，基于 `[window_start, window_end)` 内全部有效样本计算每秒平均增长速率。相邻样本值下降时按 Counter Reset 修正，并进行边界外推和左侧 Counter 零点保护。同一聚合分组内的样本应属于同一条逻辑 Counter 时序。
有效非 `NULL` 样本少于两个时返回 `NULL`。
注意：该函数自 V2.0.12 起支持。 | `value_col`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`，非 `NULL` 值必须为有限数值且大于或等于 0；`NULL` 值忽略。
`time_col`、`window_start`、`window_end`：`TIMESTAMP`、`INT64`，`INT64` 按系统当前 `timestamp_precision` 解释。
必须满足 `window_start < window_end` 和 `window_start <= time_col < window_end`；同一分组内窗口边界必须一致，不能存在重复的有效 `time_col`。当 `value_col` 非 `NULL` 时，其余参数不能为 `NULL`。 | `DOUBLE`，单位为输入值单位/秒。 | +| IRATE | `IRATE(value_col, time_col)`。按 `time_col` 排序，仅使用当前聚合分组内最后两个有效样本计算瞬时每秒速率。后一个样本值小于前一个样本值时按 Counter Reset 处理，使用最新样本值作为可确认增量；不进行边界外推。同一聚合分组内的样本应属于同一条逻辑 Counter 时序。
有效非 `NULL` 样本少于两个时返回 `NULL`。
注意：该函数自 V2.0.12 起支持。 | `value_col`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`，非 `NULL` 值必须为有限数值且大于或等于 0；`NULL` 值忽略。
`time_col`：`TIMESTAMP`、`INT64`，`INT64` 按系统当前 `timestamp_precision` 解释。
当 `value_col` 非 `NULL` 时，`time_col` 不能为 `NULL`；同一分组内不能存在重复的有效 `time_col`。 | `DOUBLE`，单位为输入值单位/秒。 | +| INCREASE | `INCREASE(value_col, time_col, window_start, window_end)`。按 `time_col` 排序，基于 `[window_start, window_end)` 内全部有效样本计算窗口总增量。相邻样本值下降时按 Counter Reset 修正，并进行边界外推和左侧 Counter 零点保护。同一聚合分组内的样本应属于同一条逻辑 Counter 时序。
有效非 `NULL` 样本少于两个时返回 `NULL`。
注意：该函数自 V2.0.12 起支持。 | `value_col`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`，非 `NULL` 值必须为有限数值且大于或等于 0；`NULL` 值忽略。
`time_col`、`window_start`、`window_end`：`TIMESTAMP`、`INT64`，`INT64` 按系统当前 `timestamp_precision` 解释。
必须满足 `window_start < window_end` 和 `window_start <= time_col < window_end`；同一分组内窗口边界必须一致，不能存在重复的有效 `time_col`。当 `value_col` 非 `NULL` 时，其余参数不能为 `NULL`。 | `DOUBLE`，单位与 `value_col` 相同。 | +| DELTA | `DELTA(value_col, time_col, window_start, window_end)`。按 `time_col` 排序，基于 `[window_start, window_end)` 内全部有效样本计算窗口变化量。样本值下降时按 Gauge 的正常变化处理，不进行 Counter Reset 修正；支持边界外推，但不启用 Counter 零点保护。
有效非 `NULL` 样本少于两个时返回 `NULL`。
注意：该函数自 V2.0.12 起支持。 | `value_col`：`INT32`、`INT64`、`FLOAT`、`DOUBLE`，非 `NULL` 值必须为有限数值，允许为负数；`NULL` 值忽略。
`time_col`、`window_start`、`window_end`：`TIMESTAMP`、`INT64`，`INT64` 按系统当前 `timestamp_precision` 解释。
必须满足 `window_start < window_end` 和 `window_start <= time_col < window_end`；同一分组内窗口边界必须一致，不能存在重复的有效 `time_col`。当 `value_col` 非 `NULL` 时，其余参数不能为 `NULL`。 | `DOUBLE`，单位与 `value_col` 相同，允许返回负数。 | + + +**说明：** + +1. **Counter Reset 处理**：当单调递增计数器的相邻样本值下降时，将其识别为计数器重置并修正增量，避免产生虚假的负增长。 + +2. **边界外推**：根据窗口内样本的平均采样间隔，将计算结果向窗口起止边界适当延伸，以估算完整窗口内的速率、增量或变化量。 ### 2.3 示例 @@ -414,6 +433,96 @@ It costs 0.244s ``` +#### 2.3.13 Rate + +以下示例使用 2.3.1 中的 `table1` 数据，查询 `device_id = '100'` 在 `2024-11-28 08:00:00` 至 `12:00:00` 的 `temperature`。窗口内有 3 个有效值（`85.0`、`85.0`、`88.0`），`09:00:00` 的 `NULL` 不参与计算。`TUMBLE()` 生成的 `window_start` 和 `window_end` 可直接作为 `rate()`、`increase()` 和 `delta()` 的窗口边界；`irate()` 只需传入数值列和时间列。 + +```SQL +SELECT + device_id, + window_start, + window_end, + rate(temperature, time, window_start, window_end) AS temperature_rate, + increase(temperature, time, window_start, window_end) AS temperature_increase, + irate(temperature, time) AS temperature_irate, + delta(temperature, time, window_start, window_end) AS temperature_delta +FROM TUMBLE( + DATA => ( + SELECT time, device_id, temperature + FROM table1 + WHERE device_id = '100' + AND time >= 2024-11-28T08:00:00.000+08:00 + AND time < 2024-11-28T12:00:00.000+08:00 + ), + TIMECOL => 'time', + SIZE => 4h +) +GROUP BY device_id, window_start, window_end; +``` + +执行结果如下： + +```SQL ++---------+-----------------------------+-----------------------------+--------------------+--------------------+--------------------+-----------------+ +|device_id| window_start| window_end| temperature_rate|temperature_increase| temperature_irate|temperature_delta| ++---------+-----------------------------+-----------------------------+--------------------+--------------------+--------------------+-----------------+ +| 100|2024-11-28T08:00:00.000+08:00|2024-11-28T12:00:00.000+08:00|2.777777777777778E-4| 4.0|8.333333333333334E-4| 4.0| ++---------+-----------------------------+-----------------------------+--------------------+--------------------+--------------------+-----------------+ +Total line number = 1 +It costs 0.132s +``` + +#### 2.3.14 Corr + +以下示例使用 2.3.1 中 `table1` 的示例数据，演示相关性、协方差、线性回归、峰度、偏度和精确百分位数的计算。计算双变量统计量时，只要 `temperature` 或 `humidity` 为 `NULL`，该行就不会参与计算；本例共有 8 组有效数据对。 + +计算 `temperature` 与 `humidity` 的相关系数、总体协方差和样本协方差，并计算 `humidity` 关于 `temperature` 的回归斜率与截距： + +```SQL +SELECT + CORR(temperature, humidity), + COVAR_POP(temperature, humidity), + COVAR_SAMP(temperature, humidity), + REGR_SLOPE(humidity, temperature), + REGR_INTERCEPT(humidity, temperature) +FROM table1; +``` + +执行结果如下： + +```SQL ++--------------------+------------------+-------------------+-------------------+-----------------+ +| _col0| _col1| _col2| _col3| _col4| ++--------------------+------------------+-------------------+-------------------+-----------------+ +|-0.10559449853747326|-0.737500190734855|-0.8428573608398342|-0.1638889312744123|50.90417003631576| ++--------------------+------------------+-------------------+-------------------+-----------------+ +Total line number = 1 +It costs 0.107s +``` + +忽略 `NULL` 后，使用 12 个有效的 `temperature` 值计算样本超额峰度、样本偏度和 50% 精确百分位数： + +```SQL +SELECT + KURTOSIS(temperature), + SKEWNESS(temperature), + PERCENTILE(temperature, 0.5) +FROM table1; +``` + +执行结果如下： + +```SQL ++-------------------+------------------+-----+ +| _col0| _col1|_col2| ++-------------------+------------------+-----+ +|-2.2909322273541326|0.1321189313100222| 86.5| ++-------------------+------------------+-----+ +Total line number = 1 +It costs 0.131s +``` + + ## 3. 逻辑运算符 ### 3.1 概述 @@ -2295,375 +2404,3 @@ SELECT regexp_like('1a 2b 14m', '^\\d+b$'); -- false - `\d+` 表示“一个或多个数字”。 - `b` 表示字母 `b`。 - `'1a 2b 14m'` 并不符合这个模式，因为它不是从数字开始，也不是以 `b` 结束，所以返回 `false`。 - -## 12. 时序分窗函数 - -原始示例数据如下： - -```SQL -IoTDB> SELECT * FROM bid; -+-----------------------------+--------+-----+ -| time|stock_id|price| -+-----------------------------+--------+-----+ -|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -|2021-01-01T09:15:00.000+08:00| TESL|195.0| -+-----------------------------+--------+-----+ - --- 创建语句 -CREATE TABLE bid(time TIMESTAMP TIME, stock_id STRING TAG, price FLOAT FIELD); --- 插入数据 -INSERT INTO bid(time, stock_id, price) VALUES('2021-01-01T09:05:00','AAPL',100.0),('2021-01-01T09:06:00','TESL',200.0),('2021-01-01T09:07:00','AAPL',103.0),('2021-01-01T09:07:00','TESL',202.0),('2021-01-01T09:09:00','AAPL',102.0),('2021-01-01T09:15:00','TESL',195.0); -``` - -### 12.1 HOP - -#### 12.1.1 功能描述 - -HOP 函数用于按时间分段分窗分析，识别每一行数据所属的时间窗口。该函数通过指定固定窗口大小（size）和窗口滑动步长（SLIDE），将数据按时间戳分配到所有与其时间戳重叠的窗口中。若窗口之间存在重叠（步长 < 窗口大小），数据会自动复制到多个窗口。 - -#### 12.1.2 函数定义 - -```SQL -HOP(data, timecol, size, slide[, origin]) -``` - -#### 12.1.3 参数说明 - -| 参数名 | 参数类型 | 参数属性 | 描述 | -| --------- | ---------- | --------------------------------- | -------------------- | -| DATA | 表参数 | ROW SEMANTICPASS THROUGH | 输入表 | -| TIMECOL | 标量参数 | 字符串类型默认值：time | 时间列 | -| SIZE | 标量参数 | 长整数类型 | 窗口大小 | -| SLIDE | 标量参数 | 长整数类型 | 窗口滑动步长 | -| ORIGIN | 标量参数 | 时间戳类型默认值：Unix 纪元时间 | 第一个窗口起始时间 | - -#### 12.1.4 返回结果 - -HOP 函数的返回结果列包含： - -* window\_start: 窗口开始时间（闭区间） -* window\_end: 窗口结束时间（开区间） -* 映射列：DATA 参数的所有输入列 - -#### 12.1.5 使用示例 - -```SQL -IoTDB> SELECT * FROM HOP(DATA => bid,TIMECOL => 'time',SLIDE => 5m,SIZE => 10m); -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -| window_start| window_end| time|stock_id|price| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:25:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ - --- 结合 GROUP BY 语句，等效于树模型的 GROUP BY TIME -IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM HOP(DATA => bid,TIMECOL => 'time',SLIDE => 5m,SIZE => 10m) GROUP BY window_start, window_end, stock_id; -+-----------------------------+-----------------------------+--------+------------------+ -| window_start| window_end|stock_id| avg| -+-----------------------------+-----------------------------+--------+------------------+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| TESL| 201.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL| 201.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00| TESL| 195.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:25:00.000+08:00| TESL| 195.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| AAPL|101.66666666666667| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:15:00.000+08:00| AAPL|101.66666666666667| -+-----------------------------+-----------------------------+--------+------------------+ -``` - -### 12.2 SESSION - -#### 12.2.1 功能描述 - -SESSION 函数用于按会话间隔对数据进行分窗。系统逐行检查与前一行的时间间隔，小于阈值（GAP）则归入当前窗口，超过则归入下一个窗口。 - -#### 12.2.2 函数定义 - -```SQL -SESSION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], timecol, gap) -``` -#### 12.2.3 参数说明 - -| 参数名 | 参数类型 | 参数属性 | 描述 | -| --------- | ---------- | -------------------------- | ---------------------------------------- | -| DATA | 表参数 | SET SEMANTICPASS THROUGH | 输入表通过 pkeys、okeys 指定分区和排序 | -| TIMECOL | 标量参数 | 字符串类型默认值：'time' | 时间列名 | -| GAP | 标量参数 | 长整数类型 | 会话间隔阈值 | - -#### 12.2.4 返回结果 - -SESSION 函数的返回结果列包含： - -* window\_start: 会话窗口内的第一条数据的时间 -* window\_end: 会话窗口内的最后一条数据的时间 -* 映射列：DATA 参数的所有输入列 - -#### 12.2.5 使用示例 - -```SQL -IoTDB> SELECT * FROM SESSION(DATA => bid PARTITION BY stock_id ORDER BY time,TIMECOL => 'time',GAP => 2m); -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -| window_start| window_end| time|stock_id|price| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:06:00.000+08:00|2021-01-01T09:07:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:06:00.000+08:00|2021-01-01T09:07:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:15:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:09:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:09:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:09:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ - --- 结合 GROUP BY 语句，等效于树模型的 GROUP BY SESSION -IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM SESSION(DATA => bid PARTITION BY stock_id ORDER BY time,TIMECOL => 'time',GAP => 2m) GROUP BY window_start, window_end, stock_id; -+-----------------------------+-----------------------------+--------+------------------+ -| window_start| window_end|stock_id| avg| -+-----------------------------+-----------------------------+--------+------------------+ -|2021-01-01T09:06:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL| 201.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL| 195.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|101.66666666666667| -+-----------------------------+-----------------------------+--------+------------------+ -``` - -### 12.3 VARIATION - -#### 12.3.1 功能描述 - -VARIATION 函数用于按数据差值分窗，将第一条数据作为首个窗口的基准值，每个数据点会与基准值进行差值运算，如果差值小于给定的阈值（delta）则加入当前窗口；如果超过阈值，则分为下一个窗口，将该值作为下一个窗口的基准值。 - -#### 12.3.2 函数定义 - -```sql -VARIATION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], col, delta) -``` - -#### 12.3.3 参数说明 - -| 参数名 | 参数类型 | 参数属性 | 描述 | -| -------- | ---------- | -------------------------- | ---------------------------------------- | -| DATA | 表参数 | SET SEMANTICPASS THROUGH | 输入表通过 pkeys、okeys 指定分区和排序 | -| COL | 标量参数 | 字符串类型 | 标识对哪一列计算差值 | -| DELTA | 标量参数 | 浮点数类型 | 差值阈值 | - -#### 12.3.4 返回结果 - -VARIATION 函数的返回结果列包含： - -* window\_index: 窗口编号 -* 映射列：DATA 参数的所有输入列 - -#### 12.3.5 使用示例 - -```sql -IoTDB> SELECT * FROM VARIATION(DATA => bid PARTITION BY stock_id ORDER BY time,COL => 'price',DELTA => 2.0); -+------------+-----------------------------+--------+-----+ -|window_index| time|stock_id|price| -+------------+-----------------------------+--------+-----+ -| 0|2021-01-01T09:06:00.000+08:00| TESL|200.0| -| 0|2021-01-01T09:07:00.000+08:00| TESL|202.0| -| 1|2021-01-01T09:15:00.000+08:00| TESL|195.0| -| 0|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -| 1|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -| 1|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+------------+-----------------------------+--------+-----+ - --- 结合 GROUP BY 语句，等效于树模型的 GROUP BY VARIATION -IoTDB> SELECT first(time) as window_start, last(time) as window_end, stock_id, avg(price) as avg FROM VARIATION(DATA => bid PARTITION BY stock_id ORDER BY time,COL => 'price', DELTA => 2.0) GROUP BY window_index, stock_id; -+-----------------------------+-----------------------------+--------+-----+ -| window_start| window_end|stock_id| avg| -+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:06:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|201.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:07:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.5| -+-----------------------------+-----------------------------+--------+-----+ -``` - -### 12.4 CAPACITY - -#### 12.4.1 功能描述 - -CAPACITY 函数用于按数据点数（行数）分窗，每个窗口最多有 SIZE 行数据。 - -#### 12.4.2 函数定义 - -```sql -CAPACITY(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], size) -``` - -#### 12.4.3 参数说明 - -| 参数名 | 参数类型 | 参数属性 | 描述 | -| -------- | ---------- | -------------------------- | ---------------------------------------- | -| DATA | 表参数 | SET SEMANTICPASS THROUGH | 输入表通过 pkeys、okeys 指定分区和排序 | -| SIZE | 标量参数 | 长整数类型 | 窗口大小 | - -#### 12.4.4 返回结果 - -CAPACITY 函数的返回结果列包含： - -* window\_index: 窗口编号 -* 映射列：DATA 参数的所有输入列 - -#### 12.4.5 使用示例 - -```sql -IoTDB> SELECT * FROM CAPACITY(DATA => bid PARTITION BY stock_id ORDER BY time, SIZE => 2); -+------------+-----------------------------+--------+-----+ -|window_index| time|stock_id|price| -+------------+-----------------------------+--------+-----+ -| 0|2021-01-01T09:06:00.000+08:00| TESL|200.0| -| 0|2021-01-01T09:07:00.000+08:00| TESL|202.0| -| 1|2021-01-01T09:15:00.000+08:00| TESL|195.0| -| 0|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -| 0|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -| 1|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+------------+-----------------------------+--------+-----+ - --- 结合 GROUP BY 语句，等效于树模型的 GROUP BY COUNT -IoTDB> SELECT first(time) as start_time, last(time) as end_time, stock_id, avg(price) as avg FROM CAPACITY(DATA => bid PARTITION BY stock_id ORDER BY time, SIZE => 2) GROUP BY window_index, stock_id; -+-----------------------------+-----------------------------+--------+-----+ -| start_time| end_time|stock_id| avg| -+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:06:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|201.0| -|2021-01-01T09:15:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:05:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|101.5| -|2021-01-01T09:09:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+-----------------------------+-----------------------------+--------+-----+ -``` - -### 12.5 TUMBLE - -#### 12.5.1 功能描述 - -TUMBLE 函数用于通过时间属性字段为每行数据分配一个窗口，滚动窗口的大小固定且不重复。 - -#### 12.5.2 函数定义 - -```sql -TUMBLE(data, timecol, size[, origin]) -``` -#### 12.5.3 参数说明 - -| 参数名 | 参数类型 | 参数属性 | 描述 | -| --------- | ---------- | --------------------------------- | -------------------- | -| DATA | 表参数 | ROW SEMANTICPASS THROUGH | 输入表 | -| TIMECOL | 标量参数 | 字符串类型默认值：time | 时间列 | -| SIZE | 标量参数 | 长整数类型 | 窗口大小，需为正数 | -| ORIGIN | 标量参数 | 时间戳类型默认值：Unix 纪元时间 | 第一个窗口起始时间 | - -#### 12.5.4 返回结果 - -TUBMLE 函数的返回结果列包含： - -* window\_start: 窗口开始时间（闭区间） -* window\_end: 窗口结束时间（开区间） -* 映射列：DATA 参数的所有输入列 - -#### 12.5.5 使用示例 - -```SQL -IoTDB> SELECT * FROM TUMBLE( DATA => bid, TIMECOL => 'time', SIZE => 10m); -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -| window_start| window_end| time|stock_id|price| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ - --- 结合 GROUP BY 语句，等效于树模型的 GROUP BY TIME -IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM TUMBLE(DATA => bid, TIMECOL => 'time', SIZE => 10m) GROUP BY window_start, window_end, stock_id; -+-----------------------------+-----------------------------+--------+------------------+ -| window_start| window_end|stock_id| avg| -+-----------------------------+-----------------------------+--------+------------------+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| TESL| 201.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00| TESL| 195.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| AAPL|101.66666666666667| -+-----------------------------+-----------------------------+--------+------------------+ -``` - -### 12.6 CUMULATE - -#### 12.6.1 功能描述 - -Cumulate 函数用于从初始的窗口开始，创建相同窗口开始但窗口结束步长不同的窗口，直到达到最大的窗口大小。每个窗口包含其区间内的元素。例如：1小时步长，24小时大小的累计窗口，每天可以获得如下这些窗口：`[00:00, 01:00)`，`[00:00, 02:00)`，`[00:00, 03:00)`， …， `[00:00, 24:00)` - -#### 12.6.2 函数定义 - -```sql -CUMULATE(data, timecol, size, step[, origin]) -``` - -#### 12.6.3 参数说明 - -| 参数名 | 参数类型 | 参数属性 | 描述 | -| --------- | ---------- | --------------------------------- | -------------------------------------------- | -| DATA | 表参数 | ROW SEMANTICPASS THROUGH | 输入表 | -| TIMECOL | 标量参数 | 字符串类型默认值：time | 时间列 | -| SIZE | 标量参数 | 长整数类型 | 窗口大小，SIZE必须是STEP的整数倍，需为正数 | -| STEP | 标量参数 | 长整数类型 | 窗口步长，需为正数 | -| ORIGIN | 标量参数 | 时间戳类型默认值：Unix 纪元时间 | 第一个窗口起始时间 | - -> 注意：size 如果不是 step 的整数倍，则会报错`Cumulative table function requires size must be an integral multiple of step` - -#### 12.6.4 返回结果 - -CUMULATE函数的返回结果列包含： - -* window\_start: 窗口开始时间（闭区间） -* window\_end: 窗口结束时间（开区间） -* 映射列：DATA 参数的所有输入列 - -#### 12.6.5 使用示例 - -```sql -IoTDB> SELECT * FROM CUMULATE(DATA => bid,TIMECOL => 'time',STEP => 2m,SIZE => 10m); -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -| window_start| window_end| time|stock_id|price| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:06:00.000+08:00| TESL|200.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| TESL|202.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:16:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:18:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00|2021-01-01T09:15:00.000+08:00| TESL|195.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:06:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:05:00.000+08:00| AAPL|100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:07:00.000+08:00| AAPL|103.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00|2021-01-01T09:09:00.000+08:00| AAPL|102.0| -+-----------------------------+-----------------------------+-----------------------------+--------+-----+ - --- 结合 GROUP BY 语句，等效于树模型的 GROUP BY TIME -IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM CUMULATE(DATA => bid,TIMECOL => 'time',STEP => 2m, SIZE => 10m) GROUP BY window_start, window_end, stock_id; -+-----------------------------+-----------------------------+--------+------------------+ -| window_start| window_end|stock_id| avg| -+-----------------------------+-----------------------------+--------+------------------+ -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00| TESL| 201.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| TESL| 201.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:16:00.000+08:00| TESL| 195.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:18:00.000+08:00| TESL| 195.0| -|2021-01-01T09:10:00.000+08:00|2021-01-01T09:20:00.000+08:00| TESL| 195.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:06:00.000+08:00| AAPL| 100.0| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:08:00.000+08:00| AAPL| 101.5| -|2021-01-01T09:00:00.000+08:00|2021-01-01T09:10:00.000+08:00| AAPL|101.66666666666667| -+-----------------------------+-----------------------------+--------+------------------+ -```