Skip to content

Commit

Permalink
docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@lancelly
lancelly committed Feb 28, 2024
1 parent 9c1a05b commit d5320c5
Show file tree
Hide file tree
Showing 8 changed files with 470 additions and 60 deletions.
3 changes: 3 additions & 0 deletions src/UserGuide/Master/User-Manual/Operator-and-Expression.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,9 @@ The built-in functions can be used in IoTDB without registration, and the functi
| COUNT_IF | Find the number of data points that continuously meet a given condition and the number of data points that meet the condition (represented by keep) meet the specified threshold. | BOOLEAN | `[keep >=/>/=/!=/</<=]threshold`：The specified threshold or threshold condition, it is equivalent to `keep >= threshold` if `threshold` is used alone, type of `threshold` is `INT64` `ignoreNull`：Optional, default value is `true`；If the value is `true`, null values are ignored, it means that if there is a null value in the middle, the value is ignored without interrupting the continuity. If the value is `true`, null values are not ignored, it means that if there are null values in the middle, continuity will be broken | INT64 |
| TIME_DURATION | Find the difference between the timestamp of the largest non-null value and the timestamp of the smallest non-null value in a column | All data Types | / | INT64 |
| MODE | Find the mode. Note: 1.Having too many different values in the input series risks a memory exception; 2.If all the elements have the same number of occurrences, that is no Mode, return the value with earliest time; 3.If there are many Modes, return the Mode with earliest time. | All data Types | / | Consistent with the input data type |
| MAX_BY | MAX_BY(x, y) returns the value of x corresponding to the maximum value of the input y. MAX_BY(time, x) returns the timestamp when x is at its maximum value. | The first input x can be of any type, while the second input y must be of type INT32, INT64, FLOAT, or DOUBLE. | Consistent with the data type of the first input x. |
| MIN_BY | MIN_BY(x, y) returns the value of x corresponding to the minimum value of the input y. MIN_BY(time, x) returns the timestamp when x is at its minimum value. | The first input x can be of any type, while the second input y must be of type INT32, INT64, FLOAT, or DOUBLE. | Consistent with the data type of the first input x. |


For details and examples, see the document [Aggregate Functions](../Operators-Functions/Aggregation.md).

Expand Down
101 changes: 100 additions & 1 deletion src/UserGuide/Master/stage/Operators-Functions/Aggregation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@ The aggregate functions supported by IoTDB are as follows:
| TIME_DURATION | Find the difference between the timestamp of the largest non-null value and the timestamp of the smallest non-null value in a column | All data Types | / | INT64 |
| MODE | Find the mode. Note: 1.Having too many different values in the input series risks a memory exception; 2.If all the elements have the same number of occurrences, that is no Mode, return the value with earliest time; 3.If there are many Modes, return the Mode with earliest time. | All data Types | / | Consistent with the input data type |
| COUNT_TIME | The number of timestamps in the query data set. When used with `align by device`, the result is the number of timestamps in the data set per device. | All data Types, the input parameter can only be `*` | / | INT64 |
| MAX_BY | MAX_BY(x, y) returns the value of x corresponding to the maximum value of the input y. MAX_BY(time, x) returns the timestamp when x is at its maximum value. | The first input x can be of any type, while the second input y must be of type INT32, INT64, FLOAT, or DOUBLE. | / | Consistent with the data type of the first input x. |
| MIN_BY | MIN_BY(x, y) returns the value of x corresponding to the minimum value of the input y. MIN_BY(time, x) returns the timestamp when x is at its minimum value. | The first input x can be of any type, while the second input y must be of type INT32, INT64, FLOAT, or DOUBLE. | / | Consistent with the data type of the first input x. |


## COUNT
Expand Down Expand Up @@ -290,4 +292,101 @@ Result
> 1. The parameter in count_time can only be *.
> 2. Count_time aggregation cannot be used with other aggregation functions.
> 3. Count_time aggregation used with having statement is not supported, and count_time aggregation can not appear in the having statement.
> 4. Count_time does not support use with group by level, group by tag.
> 4. Count_time does not support use with group by level, group by tag.

### MAX_BY
#### Function Definition
max_by(x, y): Returns the value of x at the timestamp when y is at its maximum.
- max_by must have two input parameters x and y.
- Both x and y can use the keyword time, with max_by(time, x) returning the timestamp when x is at its maximum value.
- If x is null at the timestamp corresponding to the maximum value of y, null is returned.
- If y reaches its maximum value at multiple timestamps, the x value corresponding to the smallest timestamp among those maximum values is returned.
- Consistent with IoTDB max_value, only INT32, INT64, FLOAT, DOUBLE are supported as inputs for y, while all six types are supported as inputs for x.
- Direct numerical values are not allowed as inputs for either x or y.

#### Grammar
```sql
select max_by(x, y) from root.sg
select max_by(time, x) from root.sg
```

#### Examples

##### Input Data
```sql
IoTDB> select * from root.test
+-----------------------------+-----------+-----------+
| Time|root.test.a|root.test.b|
+-----------------------------+-----------+-----------+
|1970-01-01T08:00:00.001+08:00| 1.0| 10.0|
|1970-01-01T08:00:00.002+08:00| 2.0| 10.0|
|1970-01-01T08:00:00.003+08:00| 3.0| 10.0|
|1970-01-01T08:00:00.004+08:00| 10.0| 10.0|
|1970-01-01T08:00:00.005+08:00| 10.0| 12.0|
|1970-01-01T08:00:00.006+08:00| 6.0| 6.0|
+-----------------------------+-----------+-----------+
```
##### Query Example
Querying the timestamp corresponding to the maximum value:
```sql
IoTDB> select max_by(time, a), max_value(a) from root.test
+-------------------------+------------------------+
|max_by(Time, root.test.a)| max_value(root.test.a)|
+-------------------------+------------------------+
| 4| 10.0|
+-------------------------+------------------------+
```

Finding the value of b when a is at its maximum:
```sql
IoTDB> select max_by(b, a) from root.test
+--------------------------------+
|max_by(root.test.b, root.test.a)|
+--------------------------------+
| 10.0|
+--------------------------------+
```

Using with expressions:
```sql
IoTDB> select max_by(b + 1, a * 2) from root.test
+----------------------------------------+
|max_by(root.test.b + 1, root.test.a * 2)|
+----------------------------------------+
| 11.0|
+----------------------------------------+
```

Using with group by clause：
```sql
IoTDB> select max_by(b, a) from root.test group by ([0,7),4ms)
+-----------------------------+--------------------------------+
| Time|max_by(root.test.b, root.test.a)|
+-----------------------------+--------------------------------+
|1970-01-01T08:00:00.000+08:00| 3.0|
+-----------------------------+--------------------------------+
|1970-01-01T08:00:00.004+08:00| 10.0|
+-----------------------------+--------------------------------+
```

Using with having clause：
```sql
IoTDB> select max_by(b, a) from root.test group by ([0,7),4ms) having max_by(b, a) > 4.0
+-----------------------------+--------------------------------+
| Time|max_by(root.test.b, root.test.a)|
+-----------------------------+--------------------------------+
|1970-01-01T08:00:00.004+08:00| 10.0|
+-----------------------------+--------------------------------+
```
Using with order by clause：
```sql
IoTDB> select max_by(b, a) from root.test group by ([0,7),4ms) order by time desc
+-----------------------------+--------------------------------+
| Time|max_by(root.test.b, root.test.a)|
+-----------------------------+--------------------------------+
|1970-01-01T08:00:00.004+08:00| 10.0|
+-----------------------------+--------------------------------+
|1970-01-01T08:00:00.000+08:00| 3.0|
+-----------------------------+--------------------------------+
```
Loading

0 comments on commit d5320c5

Please sign in to comment.