**Description**: The log of a specific with `base` as the radix
**Description**: The logarithm of a specific field with `base` as the radix. If `base` parameter is ignored, natural logarithm of the field is returned.
**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL
**Return value type**: DOUBLE.
**Applicable data types**: Numeric types.
**Applicable data types**: Numeric types.
**Applicable table types**: table, STable
**Applicable table types**: table, STable.
**Applicable nested query**: Inner query and Outer query
**Applicable nested query**: Inner query and Outer query.
**Description**: The concatenation result of two or more strings, the number of strings to be concatenated is at least 2 and at most 8
**Description**: The concatenation result of two or more strings.
**Return value type**: If all input strings are VARCHAR type, the result is VARCHAR type too. If any one of input strings is NCHAR type, then the result is NCHAR.
**Return value type**: If all input strings are VARCHAR type, the result is VARCHAR type too. If any one of input strings is NCHAR type, then the result is NCHAR. If input strings contain NULL value, the result is NULL.
**Applicable data types**: VARCHAR, NCHAR. At least 2 input strings are requird, and at most 8 input strings are allowed.
**Applicable data types**: VARCHAR, NCHAR. At least 2 input strings are requird, and at most 8 input strings are allowed.
**Applicable table types**: table, STable
**Applicable table types**: table, STable.
**Applicable nested query**: Inner query and Outer query.
**Applicable nested query**: Inner query and Outer query
**Description**: The concatenation result of two or more strings with separator, the number of strings to be concatenated is at least 3 and at most 9
**Description**: The concatenation result of two or more strings with separator.
**Return value type**: If all input strings are VARCHAR type, the result is VARCHAR type too. If any one of input strings is NCHAR type, then the result is NCHAR.
**Return value type**: If all input strings are VARCHAR type, the result is VARCHAR type too. If any one of input strings is NCHAR type, then the result is NCHAR. If input strings contain NULL value, the result is NULL.
**Applicable data types**: VARCHAR, NCHAR. At least 3 input strings are requird, and at most 9 input strings are allowed.
**Applicable data types**: VARCHAR, NCHAR. At least 3 input strings are requird, and at most 9 input strings are allowed.
**Applicable table types**: table, STable
**Applicable table types**: table, STable.
**Applicable nested query**: Inner query and Outer query
**More explanations**:
**Applicable nested query**: Inner query and Outer query.
- If the value of `separator` is NULL, the output is NULL. If the value of `separator` is not NULL but other input are all NULL, the output is empty string.
#### LENGTH
#### LENGTH
...
@@ -313,18 +303,16 @@ SELECT CONCAT_WS(separator, str1|column1, str2|column2, ...) FROM { tb_name | st
...
@@ -313,18 +303,16 @@ SELECT CONCAT_WS(separator, str1|column1, str2|column2, ...) FROM { tb_name | st
SELECT LENGTH(str|column) FROM { tb_name | stb_name } [WHERE clause]
SELECT LENGTH(str|column) FROM { tb_name | stb_name } [WHERE clause]
```
```
**Description**: The length in bytes of a string
**Description**: The length in bytes of a string.
**Return value type**: Integer
**Return value type**: INTEGER.
**Applicable data types**: VARCHAR or NCHAR
**Applicable data types**: VARCHAR, NCHAR.
**Applicable table types**: table, STable
**Applicable nested query**: Inner query and Outer query
**Applicable table types**: table, STable.
**More explanations**
**Applicable nested query**: Inner query and Outer query.
- If the input value is NULL, the output is NULL too
SELECT SUBSTR(str,pos[,len]) FROM { tb_name | stb_name } [WHERE clause]
SELECT SUBSTR(str,pos[,len]) FROM { tb_name | stb_name } [WHERE clause]
```
```
**Description**: The sub-string starting from `pos` with length of `len` from the original string `str`
**Description**: The sub-string starting from `pos` with length of `len` from the original string `str`.
**Return value type**: Same as input
**Return value type**: Same as input type.
**Applicable data types**: VARCHAR or NCHAR
**Applicable data types**: VARCHAR, NCHAR.
**Applicable table types**: table, STable
**Applicable table types**: table, STable.
**Applicable nested query**: Inner query and Outer query
**Applicable nested query**: Inner query and Outer query.
**More explanations**:
**More explanations**:
- If the input is NULL, the output is NULL
- If the input is NULL, the output is NULL
- Parameter `pos` can be an positive or negative integer; If it's positive, the starting position will be counted from the beginning of the string; if it's negative, the starting position will be counted from the end of the string.
- Parameter `pos` can be an positive or negative integer; If it's positive, the starting position will be counted from the beginning of the string; if it's negative, the starting position will be counted from the end of the string.
- If `len` is not specified, it means from `pos` to the end.
- If `len` is not specified, it means from `pos` to the end of string.
**Description**: It's used for type casting. The input parameter `expression` can be data columns, constants, scalar functions or arithmetic between them.
**Description**: Used for type casting. Convert `expression` to the type specified by `type_name`.
**Return value type**: The type specified by parameter `type_name`
**Return value type**: The type specified by parameter `type_name`.
**Applicable data types**:
**Applicable data types**: `expression` can be any data type except for JSON.
- Parameter `expression` can be any data type except for JSON
- The output data type specified by `type_name` can only be one of BIGINT/VARCHAR(N)/TIMESTAMP/NCHAR(N)/BIGINT UNSIGNED
**More explanations**:
**More explanations**:
- Error will be reported for unsupported type casting
- Error will be reported for unsupported type casting.
- NULL will be returned if the input value is NULL
- Some values of some supported data types may not be casted, below are known issues:
- Some values of some supported data types may not be casted, below are known issues:
1）When casting VARCHAR/NCHAR to BIGINT/BIGINT UNSIGNED, some characters may be treated as illegal, for example "a" may be converted to 0.
1）When casting VARCHAR/NCHAR to BIGINT/BIGINT UNSIGNED, some characters may be treated as illegal, for example "a" may be converted to 0.
2）There may be overflow when casting singed integer or TIMESTAMP to unsigned BIGINT
2）When casting to numeric type, if converted result is out of range the destination data type can hold, overflow may occur and casting behavior is undefined.
3）There may be overflow when casting unsigned BIGINT to BIGINT
3) When casting to VARCHAR/NCHAR type, if converted string length exceeds the length specified in `type_name`, the result will be truncated. (e.g. CAST("abcd" as BINARY(2)) will return string "ab").
4）There may be overflow when casting FLOAT/DOUBLE to BIGINT or UNSIGNED BIGINT
**Description**: The ISO8601 date/time format converted from a UNIX timestamp, plus the timezone of the client side system
**Description**: The ISO8601 date/time format converted from a UNIX timestamp, with timezone attached. `timezone` parameter allows attaching any customized timezone string to the output format. If `timezone` parameter is not specified, the timezone information of client side system will be attached.
**Return value type**: VARCHAR
**Return value type**: VARCHAR.
**Applicable column types**: TIMESTAMP, constant or a column
**Applicable data types**: INTEGER, TIMESTAMP.
**Applicable table types**: table, STable
**Applicable table types**: table, STable.
**More explanations**:
**More explanations**:
- If the input is UNIX timestamp constant, the precision of the returned value is determined by the digits of the input timestamp
- If the input is INTEGER represents UNIX timestamp, the precision of the returned value is determined by the digits of the input integer.
- If the input is a column of TIMESTAMP type, The precision of the returned value is same as the precision set for the current data base in use
- If the input is of TIMESTAMP type, The precision of the returned value is same as the precision set for the current database in use.
**Description**: Convert a JSON string to a JSON body。
**Description**: Convert a JSON string to a JSON body.
**Return value type**: JSON
**Return value type**: JSON.
**Applicable column types**: JSON string, in the format like '{ "literal" : literal }'. '{}' is NULL value. keys in the string must be string constants, values can be constants of numeric types, bool, string or NULL. Escaping characters are not allowed in the JSON string.
**Applicable data types**: JSON string, in the format like '{ "literal" : literal }'. '{}' is NULL value. keys in the string must be string constants, values can be constants of numeric types, bool, string or NULL. Escaping characters are not allowed in the JSON string.
**Applicable table types**: table, STable
**Applicable table types**: table, STable.
**Applicable nested query**: Inner query and Outer query.
**Applicable nested query**: Inner query and Outer query.
**Description**: UNIX timestamp converted from a string of date/time format
**Description**: UNIX timestamp converted from a string of date/time format.
**Return value type**: Long integer
**Return value type**: BIGINT.
**Applicable column types**: Constant or column of VARCHAR/NCHAR
**Applicable data types**: VARCHAR, NCHAR.
**Applicable table types**: table, STable
**Applicable table types**: table, STable.
**More explanations**:
**More explanations**:
- The input string must be compatible with ISO8601/RFC3339 standard, 0 will be returned if the string can't be converted
- The input string must be compatible with ISO8601/RFC3339 standard, NULL will be returned if the string cannot be converted.
- The precision of the returned timestamp is same as the precision set for the current data base in use
- The precision of the returned timestamp is same as the precision set for the current database in use.
### DateTime Functions
### DateTime Functions
This kind of functiosn oeprate on timestamp data. NOW(), TODAY() and TIMEZONE() are executed only once even though they may occurr multiple times in a single SQL statement.
DateTime functions applied to timestamp data. NOW(), TODAY() and TIMEZONE() are executed only once even though they may occur multiple times in a single SQL statement.
#### NOW
#### NOW
...
@@ -523,39 +494,39 @@ SELECT select_expr FROM { tb_name | stb_name } WHERE ts_col cond_operatior NOW()
...
@@ -523,39 +494,39 @@ SELECT select_expr FROM { tb_name | stb_name } WHERE ts_col cond_operatior NOW()
INSERTINTOtb_nameVALUES(NOW(),...);
INSERTINTOtb_nameVALUES(NOW(),...);
```
```
**Description**: The current time of the client side system
**Description**: The current time of the client side system.
**Return value type**: TIMESTAMP
**Return value type**: TIMESTAMP.
**Applicable column types**: TIMESTAMP only
**Applicable data types**: TIMESTAMP only if used in WHERE/INSERT clause.
**Applicable table types**: table, STable
**Applicable table types**: table, STable.
**More explanations**:
**More explanations**:
- Add and Subtract operation can be performed, for example NOW() + 1s, the time unit can be:
- Addition and Subtraction operation with time duration can be performed, for example NOW() + 1s, the time unit can be one of the followings:
- The precision of the returned timestamp is same as the precision set for the current data base in use
- The precision of the returned timestamp is same as the precision set for the current database in use.
## Aggregate Functions
## Aggregate Functions
Aggregate functions return single result row for each group in the query result set. Groups are determined by `GROUP BY` clause or time window clause if they are used; or the whole result is considered a group if neither of them is used.
Aggregate functions return single result row for each group in the query result set. Groups are determined by `GROUP BY` clause or time window clause if they are used; or the whole result is considered a group if neither of them is used.
### APERCENTILE
```
SELECT APERCENTILE(field_name, P[, algo_type])
FROM { tb_name | stb_name } [WHERE clause]
```
**Description**: Similar to `PERCENTILE`, but a approximated result is returned.
**Return value type**: DOUBLE.
**Applicable column types**: Numeric types.
**Applicable table types**: table, STable.
**More explanations**
- _P_ is in range [0,100], when _P_ is 0, the result is same as using function MIN; when _P_ is 100, the result is same as function MAX.
-**algo_type** can only be input as `default` or `t-digest`, if it's not specified `default` will be used, i.e. `apercentile(column_name, 50)` is same as `apercentile(column_name, 50, "default")`.
- If `default` is used, histogram based algorithm is used for calculation. If `t-digest` is used, `t-digest` sampling algorithm is used to calculate the result.
**Nested query**: It can be used in both the outer query and inner query in a nested query.
### AVG
### AVG
```
```
SELECT AVG(field_name) FROM tb_name [WHERE clause];
SELECT AVG(field_name) FROM tb_name [WHERE clause];
```
```
**Description**: Get the average value of a column in a table or STable
**Description**: Get the average value of a column in a table or STable.
**Return value type**: Double precision floating number
**Return value type**: DOUBLE.
**Applicable column types**: Numeric type
**Applicable data types**: Numeric type.
**Applicable table types**: table, STable
**Applicable table types**: table, STable.
### COUNT
### COUNT
...
@@ -637,17 +631,17 @@ SELECT AVG(field_name) FROM tb_name [WHERE clause];
...
@@ -637,17 +631,17 @@ SELECT AVG(field_name) FROM tb_name [WHERE clause];
SELECT COUNT([*|field_name]) FROM tb_name [WHERE clause];
SELECT COUNT([*|field_name]) FROM tb_name [WHERE clause];
```
```
**Description**: Get the number of rows or the number of non-null values in a table or a super table.
**Description**: Get the number of rows in a table or a super table.
**Return value type**: Long integer INT64
**Return value type**: BIGINT.
**Applicable column types**: All
**Applicable data types**: All data types.
**Applicable table types**: table, super table, sub table
**Applicable table types**: table, STable.
**More explanation**:
**More explanation**:
- Wildcard (\*) is used to represent all columns. The `COUNT` function is used to get the total number of all rows.
- Wildcard (\*) is used to represent all columns. If \* used `COUNT` function will get the total number of all rows.
- The number of non-NULL values will be returned if this function is used on a specific column.
- The number of non-NULL values will be returned if this function is used on a specific column.
### ELAPSED
### ELAPSED
...
@@ -656,13 +650,13 @@ SELECT COUNT([*|field_name]) FROM tb_name [WHERE clause];
...
@@ -656,13 +650,13 @@ SELECT COUNT([*|field_name]) FROM tb_name [WHERE clause];
**Description**：`elapsed` function can be used to calculate the continuous time length in which there is valid data. If it's used with `INTERVAL` clause, the returned result is the calcualted time length within each time window. If it's used without `INTERVAL` caluse, the returned result is the calculated time length within the specified time range. Please be noted that the return value of `elapsed` is the number of `time_unit` in the calculated time length.
**Description**：`elapsed` function can be used to calculate the continuous time length in which there is valid data. If it's used with `INTERVAL` clause, the returned result is the calcualted time length within each time window. If it's used without `INTERVAL` caluse, the returned result is the calculated time duration within the specified time range. Please be noted that the calculated time duration is in the specified `time_unit`.
**Return value type**：Double
**Return value type**：DOUBLE.
**Applicable Column type**：Timestamp
**Applicable Column type**：TIMESTAMP.
**Applicable tables**: table, STable, outter in nested query
**Applicable tables**: table, STable, outter in nested query.
-`group by tbname` must be used together when `elapsed` is used against a STable.
-`group by tbname` must be used together when `elapsed` is used against a STable.
-`group by` must NOT be used together when `elapsed` is used against a table or sub table.
-`group by` must NOT be used together when `elapsed` is used against a table or sub table.
- When used in nested query, it's only applicable when the inner query outputs an implicit timestamp column as the primary key. For example, `select elapsed(ts) from (select diff(value) from sub1)` is legal usage while `select elapsed(ts) from (select * from sub1)` is not.
- When used in nested query, it's only applicable when the inner query outputs an implicit timestamp column as the primary key. For example, `select elapsed(ts) from (select diff(value) from sub1)` is legal usage while `select elapsed(ts) from (select * from sub1)` is not.
- It can't be used with `leastsquares`, `diff`, `derivative`, `top`, `bottom`, `last_row`, `interp`.
- It cannot be used with `leastsquares`, `diff`, `derivative`, `top`, `bottom`, `last_row`, `interp`.
**Description**: The linear regression function of the specified column and the timestamp column (primary key), `start_val` is the initial value and `step_val` is the step value.
**Description**: The linear regression function of the specified column and the timestamp column (primary key), `start_val` is the initial value and `step_val` is the step value.
**Return value type**: A string in the format of "(slope, intercept)"
**Return value type**: VARCHAR string in the format of "(slope, intercept)".
**Applicable column types**: Numeric types
**Applicable table types**: table only
### MODE
```
SELECT MODE(field_name) FROM tb_name [WHERE clause];
```
**Description**:The value which has the highest frequency of occurrence. NULL is returned if there are multiple values which have highest frequency of occurrence. It can't be used on timestamp column.
**Return value type**:Same as the data type of the column being operated upon
**Applicable column types**:Data types except for timestamp
**Applicable data types**: Numeric types.
**More explanations**:Considering the number of returned result set is unpredictable, it's suggested to limit the number of unique values to 100,000, otherwise error will be returned.
**Applicable table types**: table only.
### SPREAD
### SPREAD
...
@@ -709,15 +689,15 @@ SELECT MODE(field_name) FROM tb_name [WHERE clause];
...
@@ -709,15 +689,15 @@ SELECT MODE(field_name) FROM tb_name [WHERE clause];
SELECT SPREAD(field_name) FROM { tb_name | stb_name } [WHERE clause];
SELECT SPREAD(field_name) FROM { tb_name | stb_name } [WHERE clause];
```
```
**Description**: The difference between the max and the min of a specific column
**Description**: The difference between the max and the min value of a specific column.
**Return value type**: Double precision floating point
**Return value type**: DOUBLE.
**Applicable column types**: Numeric types
**Applicable column types**: Numeric types.
**Applicable table types**: table, STable
**Applicable table types**: table, STable.
**More explanations**: Can be used on a column of TIMESTAMP type, the result is the time range size.
**More explanations**: Can be used on a column of TIMESTAMP type, the result time unit precision is same as the current database in use.
**Description**:The cardinal number of a specific column is returned by using hyperloglog algorithm.
**Description**:The cardinal number of a specific column is returned by using hyperloglog algorithm.
**Return value type**:Integer
**Return value type**: INTEGER.
**Applicable column types**:Any data type
**Applicable column types**: All data types.
**More explanations**: The benefit of using hyperloglog algorithm is that the memory usage is under control when the data volume is huge. However, when the data volume is very small, the result may be not accurate, it's recommented to use `select count(data) from (select unique(col) as data from table)` in this case.
**More explanations**: The benefit of using hyperloglog algorithm is that the memory usage is under control when the data volume is huge. However, when the data volume is very small, the result may be not accurate, it's recommented to use `select count(data) from (select unique(col) as data from table)` in this case.
...
@@ -769,16 +749,16 @@ SELECT HISTOGRAM(field_name，bin_type, bin_description, normalized) FROM tb_nam
...
@@ -769,16 +749,16 @@ SELECT HISTOGRAM(field_name，bin_type, bin_description, normalized) FROM tb_nam
**Description**：Returns count of data points in user-specified ranges.
**Description**：Returns count of data points in user-specified ranges.
**Return value type**：Double or INT64, depends on normalized parameter settings.
**Return value type**：DOUBLE or BIGINT, depends on normalized parameter settings.
**Applicable column type**：Numerical types.
**Applicable column type**：Numerical types.
**Applicable table types**: table, STable
**Applicable table types**: table, STable.
**Explanations**：
**Explanations**：
1. bin_type: parameter to indicate the bucket type, valid inputs are: "user_input", "linear_bin", "log_bin"。
1. bin_type: parameter to indicate the bucket type, valid inputs are: "user_input", "linear_bin", "log_bin"。
2. bin_description: parameter to describe how to generate buckets，can be in the following JSON formats for each bin_type respectively:
2. bin_description: parameter to describe the rule to generate buckets，can be in the following JSON formats for each bin_type respectively:
- "user_input": "[1, 3, 5, 7]": User specified bin values.
- "user_input": "[1, 3, 5, 7]": User specified bin values.
...
@@ -798,32 +778,25 @@ SELECT HISTOGRAM(field_name，bin_type, bin_description, normalized) FROM tb_nam
...
@@ -798,32 +778,25 @@ SELECT HISTOGRAM(field_name，bin_type, bin_description, normalized) FROM tb_nam
3. normalized: setting to 1/0 to turn on/off result normalization.
3. normalized: setting to 1/0 to turn on/off result normalization.
## Selector Functions
### PERCENTILE
Selector functiosn choose one or more rows in the query result set to retrun according toe the semantics. You can specify to output ts column and other columns including tbname and tags so that you can easily know which rows the selected values belong to.
### APERCENTILE
```
```
SELECT APERCENTILE(field_name, P[, algo_type])
SELECT PERCENTILE(field_name, P) FROM { tb_name } [WHERE clause];
FROM { tb_name | stb_name } [WHERE clause]
```
```
**Description**: Similar to `PERCENTILE`, but a simulated result is returned
**Description**: The value whose rank in a specific column matches the specified percentage. If such a value matching the specified percentage doesn't exist in the column, an interpolation value will be returned.
**Return value type**: Double precision floating point
**Return value type**: DOUBLE.
**Applicable column types**: Numeric types
**Applicable column types**: Numeric types.
**Applicable table types**: table, STable
**Applicable table types**: table.
**More explanations**
**More explanations**: _P_ is in range [0,100], when _P_ is 0, the result is same as using function MIN; when _P_ is 100, the result is same as function MAX.
- _P_ is in range [0,100], when _P_ is 0, the result is same as using function MIN; when _P_ is 100, the result is same as function MAX.
## Selector Functions
-**algo_type** can only be input as `default` or `t-digest`, if it's not specified `default` will be used, i.e. `apercentile(column_name, 50)` is same as `apercentile(column_name, 50, "default")`.
- When `t-digest` is used, `t-digest` sampling is used to calculate.
**Nested query**: It can be used in both the outer query and inner query in a nested query.
Selector functiosn choose one or more rows in the query result according to the semantics. You can specify to output primary timestamp column and other columns including tbname and tags so that you can easily know which rows the selected values belong to.
**Description**: The least _k_ values of a specific column in a table or STable. If a value has multiple occurrences in the column but counting all of them in will exceed the upper limit _k_, then a part of them will be returned randomly.
**Description**: The least _k_ values of a specific column in a table or STable. If a value has multiple occurrences in the column but counting all of them in will exceed the upper limit _k_, then a part of them will be returned randomly.
**Return value type**: Same as the column being operated upon
**Return value type**: Same as the column being operated upon.
**Applicable column types**: Numeric types
**Applicable column types**: Numeric types.
**Applicable table types**: table, STable
**Applicable table types**: table, STable.
**More explanations**:
**More explanations**:
- _k_ must be in range [1,100]
- _k_ must be in range [1,100].
- The timestamp associated with the selected values are returned too
- The timestamp associated with the selected values are returned too.
SELECT LAST_ROW(field_name) FROM { tb_name | stb_name };
SELECT LAST_ROW(field_name) FROM { tb_name | stb_name };
```
```
**Description**: The last row of a table or STable
**Description**: The last row of a table or STable.
**Return value type**: Same as the column being operated upon
**Return value type**: Same as the column being operated upon.
**Applicable column types**: Any data type
**Applicable column types**: All data type.
**Applicable table types**: table, STable
**Applicable table types**: table, STable.
**More explanations**:
**More explanations**:
- When it's used against a STable, multiple rows with the same and largest timestamp may exist, in this case one of them is returned randomly and it's not guaranteed that the result is same if the query is run multiple times.
- When it's used against a STable, multiple rows with the same and largest timestamp may exist, in this case one of them is returned randomly and it's not guaranteed that the result is same if the query is run multiple times.
SELECT MIN(field_name) FROM {tb_name | stb_name} [WHERE clause];
SELECT MIN(field_name) FROM {tb_name | stb_name} [WHERE clause];
```
```
**Description**: The minimum value of a specific column in a table or STable
**Description**: The minimum value of a specific column in a table or STable.
**Return value type**: Same as the data type of the column being operated upon
**Return value type**: Same as the data type of the column being operated upon.
**Applicable column types**: Numeric types
**Applicable column types**: Numeric types.
**Applicable table types**: table, STable
**Applicable table types**: table, STable.
### PERCENTILE
### MODE
```
```
SELECT PERCENTILE(field_name, P) FROM { tb_name } [WHERE clause];
SELECT MODE(field_name) FROM tb_name [WHERE clause];
```
```
**Description**: The value whose rank in a specific column matches the specified percentage. If such a value matching the specified percentage doesn't exist in the column, an interpolation value will be returned.
**Description**:The value which has the highest frequency of occurrence. NULL is returned if there are multiple values which have highest frequency of occurrence.
**Return value type**: Double precision floating point
**Return value type**:Same as the data type of the column being operated upon.
**Applicable column types**: Numeric types
**Applicable column types**: All data types.
**Applicable table types**: table
**More explanations**:Considering the number of returned result set is unpredictable, it's suggested to limit the number of unique values to 100,000, otherwise error will be returned.
**More explanations**: _P_ is in range [0,100], when _P_ is 0, the result is same as using function MIN; when _P_ is 100, the result is same as function MAX.
**Description**: The next _k_ rows are returned after skipping the last `offset_val` rows, NULL values are not ignored. `offset_val` is optional parameter. When it's not specified, the last _k_ rows are returned. When `offset_val` is used, the effect is same as `order by ts desc LIMIT k OFFSET offset_val`.
**Description**: The next _k_ rows are returned after skipping the last `offset_val` rows, NULL values are not ignored. `offset_val` is optional parameter. When it's not specified, the last _k_ rows are returned. When `offset_val` is used, the effect is same as `order by ts desc LIMIT k OFFSET offset_val`.
**Parameter value range**: k: [1,100] offset_val: [0,100]
**Parameter value range**: k: [1,100] offset_val: [0,100].
**Return value type**: Same as the column being operated upon
**Return value type**: Same as the column being operated upon.
**Applicable column types**: Any data type except form timestamp, i.e. the primary key
**Description**: The greatest _k_ values of a specific column in a table or STable. If a value has multiple occurrences in the column but counting all of them in will exceed the upper limit _k_, then a part of them will be returned randomly.
**Description**: The greatest _k_ values of a specific column in a table or STable. If a value has multiple occurrences in the column but counting all of them in will exceed the upper limit _k_, then a part of them will be returned randomly.
**Return value type**: Same as the column being operated upon
**Return value type**: Same as the column being operated upon.
**Applicable column types**: Numeric types
**Applicable column types**: Numeric types.
**Applicable table types**: table, STable
**Applicable table types**: table, STable.
**More explanations**:
**More explanations**:
- _k_ must be in range [1,100]
- _k_ must be in range [1,100].
- The timestamp associated with the selected values are returned too
- The timestamp associated with the selected values are returned too.
**Description**: The values that occur the first time in the specified column. The effect is similar to `distinct` keyword, but it can also be used to match tags or timestamp.
**Description**: The values that occur the first time in the specified column. The effect is similar to `distinct` keyword, but it can also be used to match tags or timestamp.
**Return value type**: Same as the column or tag being operated upon
**Return value type**: Same as the column or tag being operated upon.
**Applicable column types**: Any data types except for timestamp
**Applicable column types**: All data types.
**More explanations**:
**More explanations**:
...
@@ -1035,18 +1027,18 @@ TDengine provides a set of time-series specific functions to better meet the req
...
@@ -1035,18 +1027,18 @@ TDengine provides a set of time-series specific functions to better meet the req
**Description**: The cumulative sum of each row for a specific column. The number of output rows is same as that of the input rows.
**Description**: The cumulative sum of each row for a specific column. The number of output rows is same as that of the input rows.
**Return value type**: Long integer for integers; Double for floating points. Timestamp is returned for each row.
**Return value type**: BIGINT for signed integer input types; UNSIGNED BIGINT for unsigned integer input types; DOUBLE for floating point input types.
**Applicable data types**: Numeric types
**Applicable data types**: Numeric types.
**Applicable table types**: table, STable
**Applicable table types**: table, STable.
**Applicable nested query**: Inner query and Outer query
**Applicable nested query**: Inner query and Outer query.
**More explanations**:
**More explanations**:
- Arithmetic operation can't be performed on the result of `csum` function
- Arithmetic operation cannot be performed on the result of `csum` function.
- Can only be used with aggregate functions
- Can only be used with aggregate functions.
-`Group by tbname` must be used together on a STable to force the result on a single timeline
-`Partition by tbname` must be used together on a STable to force the result on a single timeline.
**Description**: The derivative of a specific column. The time rage can be specified by parameter `time_interval`, the minimum allowed time range is 1 second (1s); the value of `ignore_negative` can be 0 or 1, 1 means negative values are ignored.
**Description**: The derivative of a specific column. The time rage can be specified by parameter `time_interval`, the minimum allowed time range is 1 second (1s); the value of `ignore_negative` can be 0 or 1, 1 means negative values are ignored.
**Return value type**: Double precision floating point
**Return value type**: DOUBLE.
**Applicable column types**: Numeric types
**Applicable column types**: Numeric types.
**Applicable table types**: table, STable
**Applicable table types**: table, STable.
**More explanations**:
**More explanations**:
- The number of result rows is the number of total rows in the time range subtracted by one, no output for the first row.
- The number of result rows is the number of total rows in the time range subtracted by one, no output for the first row.
- It can be used together with `GROUP BY tbname` against a STable.
- It can be used together with `PARTITION BY tbname` against a STable.
- Can be used together with selection of relative columns. E.g. select \_rowts, DERIVATIVE() from.
**Description**: The different of each row with its previous row for a specific column. `ignore_negative` can be specified as 0 or 1, the default value is 1 if it's not specified. `1` means negative values are ignored.
**Description**: The different of each row with its previous row for a specific column. `ignore_negative` can be specified as 0 or 1, the default value is 1 if it's not specified. `1` means negative values are ignored.
**Return value type**: Same as the column being operated upon
**Return value type**: Same as the column being operated upon.
**Applicable column types**: Numeric types
**Applicable column types**: Numeric types.
**Applicable table types**: table, STable
**Applicable table types**: table, STable.
**More explanations**:
**More explanations**:
- The number of result rows is the number of rows subtracted by one, no output for the first row
- The number of result rows is the number of rows subtracted by one, no output for the first row.
- It can be used on STable with `GROUP by tbname`
- It can be used on STable with `PARTITION by tbname`.
- Can be used together with selection of relative columns. E.g. select \_rowts, DIFF() from.
### IRATE
### IRATE
...
@@ -1094,15 +1088,15 @@ SELECT IRATE(field_name) FROM tb_name WHERE clause;
...
@@ -1094,15 +1088,15 @@ SELECT IRATE(field_name) FROM tb_name WHERE clause;
**Description**: instantaneous rate on a specific column. The last two samples in the specified time range are used to calculate instantaneous rate. If the last sample value is smaller, then only the last sample value is used instead of the difference between the last two sample values.
**Description**: instantaneous rate on a specific column. The last two samples in the specified time range are used to calculate instantaneous rate. If the last sample value is smaller, then only the last sample value is used instead of the difference between the last two sample values.
**Return value type**: Double precision floating number
**Return value type**: DOUBLE.
**Applicable column types**: Numeric types
**Applicable column types**: Numeric types.
**Applicable table types**: table, STable
**Applicable table types**: table, STable.
**More explanations**:
**More explanations**:
- It can be used on stble with `GROUP BY`, i.e. timelines generated by `GROUP BY tbname` on a STable.
- It can be used on stble with `PARTITION BY`, i.e. timelines generated by `PARTITION BY tbname` on a STable.
### MAVG
### MAVG
...
@@ -1112,40 +1106,19 @@ SELECT IRATE(field_name) FROM tb_name WHERE clause;
...
@@ -1112,40 +1106,19 @@ SELECT IRATE(field_name) FROM tb_name WHERE clause;
**Description**: The moving average of continuous _k_ values of a specific column. If the number of input rows is less than _k_, nothing is returned. The applicable range of _k_ is [1,1000].
**Description**: The moving average of continuous _k_ values of a specific column. If the number of input rows is less than _k_, nothing is returned. The applicable range of _k_ is [1,1000].
**Return value type**: Double precision floating point
**Return value type**: DOUBLE.
**Applicable data types**: Numeric types
**Applicable data types**: Numeric types.
**Applicable nested query**: Inner query and Outer query
**Applicable table types**: table, STable
**More explanations**:
- Arithmetic operation can't be performed on the result of `MAVG`.
- Can't be used with aggregate functions.
- Must be used with `GROUP BY tbname` when it's used on a STable to force the result on each single timeline.
**Description**: The number of continuous rows satisfying the specified conditions for a specific column. The result is shown as an extra column for each row. If the specified condition is evaluated as true, the number is increased by 1; otherwise the number is reset to -1. If the input value is NULL, then the corresponding row is skipped.
**Description**: The number of continuous rows satisfying the specified conditions for a specific column. If the specified condition is evaluated as true, the number is increased by 1; otherwise the number is reset to -1. If the input value is NULL, then the corresponding row is skipped.
**Applicable parameter values**:
**Applicable parameter values**:
- oper : Can be one of LT (lower than), GT (greater than), LE (lower than or euqal to), GE (greater than or equal to), NE (not equal to), EQ (equal to), the value is case insensitive
- oper : Can be one of "LT" (lower than), "GT" (greater than), "LE" (lower than or euqal to), "GE" (greater than or equal to), "NE" (not equal to), "EQ" (equal to).
- val ： Numeric types
- val ： Numeric types.
**Return value type**: Integer
**Return value type**: INTEGER.
**Applicable data types**: Numeric types
**Applicable data types**: Numeric types.
**Applicable table types**: table, STable
**Applicable table types**: table, STable.
**Applicable nested query**: Outer query only
**Applicable nested query**: Outer query only.
**More explanations**:
**More explanations**:
- Must be used together with `GROUP BY tbname` when it's used on a STable to force the result into each single timeline]
- Must be used together with `PARTITION BY tbname` when it's used on a STable to force the result into each single timeline.
- Can't be used with window operation, like interval/state_window/session_window
- Cannot be used with window operation, like interval/state_window/session_window.
**Description**: The length of time range in which all rows satisfy the specified condition for a specific column. The result is shown as an extra column for each row. The length for the first row that satisfies the condition is 0. Next, if the condition is evaluated as true for a row, the time interval between current row and its previous row is added up to the time range; otherwise the time range length is reset to -1. If the value of the column is NULL, the corresponding row is skipped.
**Description**: The length of time range in which all rows satisfy the specified condition for a specific column. The length for the first row that satisfies the condition is 0. Next, if the condition is evaluated as true for a row, the time interval between current row and its previous row is added up to the time range; otherwise the time range length is reset to -1. If the value of the column is NULL, the corresponding row is skipped.
**Applicable parameter values**:
**Applicable parameter values**:
- oper : Can be one of LT (lower than), GT (greater than), LE (lower than or euqal to), GE (greater than or equal to), NE (not equal to), EQ (equal to), the value is case insensitive
- oper : Can be one of "LT" (lower than), "GT" (greater than), "LE" (lower than or euqal to), "GE" (greater than or equal to), "NE" (not equal to), "EQ" (equal to).
- val ： Numeric types
- val : Numeric types.
- unit: The unit of time interval, can be [1s, 1m, 1h], default is 1s
- unit : The unit of time interval, can be: 1b(nanosecond), 1u(microsecond),1a(millisecond),1s(second),1m(minute),1h(hour),1d(day),1w(week). If not specified, default is same as the current database time precision in use.
**Return value type**: Integer
**Return value type**: INTEGER.
**Applicable data types**: Numeric types
**Applicable data types**: Numeric types.
**Applicable table types**: table, STable
**Applicable table types**: table, STable.
**Applicable nested query**: Outer query only
**Applicable nested query**: Outer query only.
**More explanations**:
**More explanations**:
- Must be used together with `GROUP BY tbname` when it's used on a STable to force the result into each single timeline]
- Must be used together with `PARTITION BY tbname` when it's used on a STable to force the result into each single timeline.
- Can't be used with window operation, like interval/state_window/session_window
- Cannot be used with window operation, like interval/state_window/session_window.
- 对于嵌套查询，仅当内层查询会输出隐式时间戳列时有效。例如select elapsed(ts) from (select diff(value) from sub1)语句，diff函数会让内层查询输出隐式时间戳列，此为主键列，可以用于elapsed函数的第一个参数。相反，例如select elapsed(ts) from (select * from sub1) 语句，ts列输出到外层时已经没有了主键列的含义，无法使用elapsed函数。此外，elapsed函数作为一个与时间线强依赖的函数，形如select elapsed(ts) from (select diff(value) from st group by tbname)尽管会返回一条计算结果，但并无实际意义，这种用法后续也将被限制。
- 对于嵌套查询，仅当内层查询会输出隐式时间戳列时有效。例如select elapsed(ts) from (select diff(value) from sub1)语句，diff函数会让内层查询输出隐式时间戳列，此为主键列，可以用于elapsed函数的第一个参数。相反，例如select elapsed(ts) from (select * from sub1) 语句，ts列输出到外层时已经没有了主键列的含义，无法使用elapsed函数。此外，elapsed函数作为一个与时间线强依赖的函数，形如select elapsed(ts) from (select diff(value) from st group by tbname)尽管会返回一条计算结果，但并无实际意义，这种用法后续也将被限制。
