diff --git a/docs-cn/12-taos-sql/07-function.md b/docs-cn/12-taos-sql/07-function.md index d2cd89f152..993a1dac6e 100644 --- a/docs-cn/12-taos-sql/07-function.md +++ b/docs-cn/12-taos-sql/07-function.md @@ -808,6 +808,25 @@ SELECT BOTTOM(field_name, K) FROM { tb_name | stb_name } [WHERE clause]; - 系统同时返回该记录关联的时间戳列; - 限制:BOTTOM 函数不支持 FILL 子句。 +### FIRST + +``` +SELECT FIRST(field_name) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**:统计表/超级表中某列的值最先写入的非 NULL 值。 + +**返回数据类型**:同应用的字段。 + +**适用数据类型**:所有字段。 + +**适用于**:表和超级表。 + +**使用说明**: + +- 如果要返回各个列的首个(时间戳最小)非 NULL 值,可以使用 FIRST(\*); +- 如果结果集中的某列全部为 NULL 值,则该列的返回结果也是 NULL; +- 如果结果集中所有列全部为 NULL 值,则不返回结果。 ### INTERP @@ -919,25 +938,6 @@ SELECT PERCENTILE(field_name, P) FROM { tb_name } [WHERE clause]; **使用说明**:*P*值取值范围 0≤*P*≤100,为 0 的时候等同于 MIN,为 100 的时候等同于 MAX。 -### FIRST - -``` -SELECT FIRST(field_name) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**功能说明**:统计表/超级表中某列的值最先写入的非 NULL 值。 - -**返回数据类型**:同应用的字段。 - -**适用数据类型**:所有字段。 - -**适用于**:表和超级表。 - -**使用说明**: - -- 如果要返回各个列的首个(时间戳最小)非 NULL 值,可以使用 FIRST(\*); -- 如果结果集中的某列全部为 NULL 值,则该列的返回结果也是 NULL; -- 如果结果集中所有列全部为 NULL 值,则不返回结果。 ### TAIL diff --git a/docs-en/12-taos-sql/07-function.md b/docs-en/12-taos-sql/07-function.md index 1a0dc28fa0..6c45474b88 100644 --- a/docs-en/12-taos-sql/07-function.md +++ b/docs-en/12-taos-sql/07-function.md @@ -1,10 +1,658 @@ --- -title: Functions +title: SQL Functions +toc_max_heading_level: 4 --- +## Single-Row Functions + +Single-Row functions return a result row for each row in the query result. + +### Numeric Functions + +#### ABS + +```sql +SELECT ABS(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The absolute of a specific column. + +**Return value type**: UBIGINT if the input value is integer; DOUBLE if the input value is FLOAT/DOUBLE. + +**Applicable data types**: Numeric types. + +**Applicable table types**: table, STable. + +**Applicable nested query**: Inner query and Outer query. + +**More explanations**: + +- Can't be used with tags. +- Can't be used with aggregate functions. + +#### ACOS + +```sql +SELECT ACOS(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The anti-cosine of a specific column + +**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL + +**Applicable data types**: Numeric types. + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**More explanations**: + +- Can't be used with tags +- Can't be used with aggregate functions + +#### ASIN + +```sql +SELECT ASIN(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The anti-sine of a specific column + +**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL + +**Applicable data types**: Numeric types. + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**More explanations**: + +- Can't be used with tags +- Can't be used with aggregate functions + +#### ATAN + +```sql +SELECT ATAN(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: anti-tangent of a specific column + +**Description**: The anti-cosine of a specific column + +**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL + +**Applicable data types**: Numeric types. + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**More explanations**: + +- Can't be used with tags +- Can't be used with aggregate functions + +#### CEIL + +``` +SELECT CEIL(field_name) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**Description**: The rounded up value of a specific column + +**Return value type**: Same as the column being used + +**Applicable data types**: Numeric types. + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and outer query + +**More explanations**: + +- Can't be used on any tags of any type +- Arithmetic operation can be performed on the result of `ceil` function +- Can't be used with aggregate functions + +#### COS + +```sql +SELECT COS(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The cosine of a specific column + +**Description**: The anti-cosine of a specific column + +**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL + +**Applicable data types**: Numeric types. + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**More explanations**: + +- Can't be used with tags +- Can't be used with aggregate functions + +#### FLOOR + +``` +SELECT FLOOR(field_name) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**Description**: The rounded down value of a specific column + +**More explanations**: The restrictions are same as those of the `CEIL` function. + +#### LOG + +```sql +SELECT LOG(field_name, base) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The log of a specific with `base` as the radix + +**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL + +**Applicable data types**: Numeric types. + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**More explanations**: + +- Can't be used with tags +- Can't be used with aggregate functions + +#### POW + +```sql +SELECT POW(field_name, power) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The power of a specific column with `power` as the index + +**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL + +**Applicable data types**: Numeric types. + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**More explanations**: + +- Can't be used with tags +- Can't be used with aggregate functions + +#### ROUND + +``` +SELECT ROUND(field_name) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**Description**: The rounded value of a specific column. + +**More explanations**: The restrictions are same as `CEIL` function. + +#### SIN + +```sql +SELECT SIN(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The sine of a specific column + +**Description**: The anti-cosine of a specific column + +**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL + +**Applicable data types**: Numeric types. + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**More explanations**: + +- Can't be used with tags +- Can't be used with aggregate functions + +#### SQRT + +```sql +SELECT SQRT(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The square root of a specific column + +**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL + +**Applicable data types**: Numeric types. + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**More explanations**: + +- Can't be used with tags +- Can't be used with aggregate functions + +#### TAN + +```sql +SELECT TAN(field_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The tangent of a specific column + +**Description**: The anti-cosine of a specific column + +**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL + +**Applicable data types**: Numeric types. + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**More explanations**: + +- Can't be used with tags +- Can't be used with aggregate functions + +### String Functions + +String functiosn take strings as input and output numbers or strings. + +#### CHAR_LENGTH + +``` +SELECT CHAR_LENGTH(str|column) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The length in number of characters of a string + +**Return value type**: Integer + +**Applicable data types**: BINARY or NCHAR, can't be used on tags + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**More explanations** + +- If the input value is NULL, the output is NULL too + +#### CONCAT + +```sql +SELECT CONCAT(str1|column1, str2|column2, ...) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The concatenation result of two or more strings, the number of strings to be concatenated is at least 2 and at most 8 + +**Return value type**: If all input strings are BINARY type, the result is BINARY type too. If any one of input strings is NCHAR type, then the result is NCHAR. + +**Applicable data types**: BINARY, NCHAR. Can't be used on tag columns. At least 2 input strings are requird, and at most 8 input strings are allowed. + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +#### CONCAT_WS + +``` +SELECT CONCAT_WS(separator, str1|column1, str2|column2, ...) FROM { tb_name | stb_name } [WHERE clause] +``` + +**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 + +**Return value type**: If all input strings are BINARY type, the result is BINARY type too. If any one of input strings is NCHAR type, then the result is NCHAR. + +**Applicable data types**: BINARY, NCHAR. Can't be used on tag columns. At least 3 input strings are requird, and at most 9 input strings are allowed. + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**More explanations**: + +- 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 + +``` +SELECT LENGTH(str|column) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: The length in bytes of a string + +**Return value type**: Integer + +**Applicable data types**: BINARY or NCHAR, can't be used on tags + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**More explanations** + +- If the input value is NULL, the output is NULL too + +#### LOWER + +``` +SELECT LOWER(str|column) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: Convert the input string to lower case + +**Return value type**: Same as input + +**Applicable data types**: BINARY or NCHAR, can't be used on tags + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**More explanations** + +- If the input value is NULL, the output is NULL too + +#### LTRIM + +``` +SELECT LTRIM(str|column) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: Remove the left leading blanks of a string + +**Return value type**: Same as input + +**Applicable data types**: BINARY or NCHAR, can't be used on tags + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**More explanations** + +- If the input value is NULL, the output is NULL too + +#### RTRIM + +``` +SELECT RTRIM(str|column) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: Remove the right tailing blanks of a string + +**Return value type**: Same as input + +**Applicable data types**: BINARY or NCHAR, can't be used on tags + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**More explanations** + +- If the input value is NULL, the output is NULL too + +#### SUBSTR + +``` +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` + +**Return value type**: Same as input + +**Applicable data types**: BINARY or NCHAR, can't be used on tags + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**More explanations**: + +- 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. +- If `len` is not specified, it means from `pos` to the end. + +#### UPPER + +``` +SELECT UPPER(str|column) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: Convert the input string to upper case + +**Return value type**: Same as input + +**Applicable data types**: BINARY or NCHAR, can't be used on tags + +**Applicable table types**: table, STable + +**Applicable nested query**: Inner query and Outer query + +**More explanations** + +- If the input value is NULL, the output is NULL too + +### Conversion Functions + +This kind of functions convert from one data type to another one. + +#### CAST + +```sql +SELECT CAST(expression AS type_name) FROM { tb_name | stb_name } [WHERE clause] +``` + +**Description**: It's used for type casting. The input parameter `expression` can be data columns, constants, scalar functions or arithmetic between them. Can't be used with tags, and can only be used in `select` clause. + +**Return value type**: The type specified by parameter `type_name` + +**Applicable data types**: + +- Parameter `expression` can be any data type except for JSON, more specifically it can be any of BOOL/TINYINT/SMALLINT/INT/BIGINT/FLOAT/DOUBLE/BINARY(M)/TIMESTAMP/NCHAR(M)/TINYINT UNSIGNED/SMALLINT UNSIGNED/INT UNSIGNED/BIGINT UNSIGNED +- The output data type specified by `type_name` can only be one of BIGINT/BINARY(N)/TIMESTAMP/NCHAR(N)/BIGINT UNSIGNED + +**More explanations**: + +- 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: + 1)When casting BINARY/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 + 3)There may be overflow when casting unsigned BIGINT to BIGINT + 4)There may be overflow when casting FLOAT/DOUBLE to BIGINT or UNSIGNED BIGINT + +#### TO_ISO8601 + +```sql +SELECT TO_ISO8601(ts_val | ts_col) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**Description**: The ISO8601 date/time format converted from a UNIX timestamp, plus the timezone of the client side system + +**Return value type**: BINARY + +**Applicable column types**: TIMESTAMP, constant or a column + +**Applicable table types**: table, STable + +**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 a column of TIMESTAMP type, The precision of the returned value is same as the precision set for the current data base in use + +#### TO_JSON + +```sql +SELECT TO_JSON(str_literal) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**Description**: Convert a JSON string to a JSON body。 + +**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 table types**: table, STable + +**Applicable nested query**: Inner query and Outer query. + +#### TO_UNIXTIMESTAMP + +```sql +SELECT TO_UNIXTIMESTAMP(datetime_string | ts_col) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**Description**: UNIX timestamp converted from a string of date/time format + +**Return value type**: Long integer + +**Applicable column types**: Constant or column of BINARY/NCHAR + +**Applicable table types**: table, STable + +**More explanations**: + +- The input string must be compatible with ISO8601/RFC3339 standard, 0 will be returned if the string can't be converted +- The precision of the returned timestamp is same as the precision set for the current data base in use + +### 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. + +#### NOW + +```sql +SELECT NOW() FROM { tb_name | stb_name } [WHERE clause]; +SELECT select_expr FROM { tb_name | stb_name } WHERE ts_col cond_operatior NOW(); +INSERT INTO tb_name VALUES (NOW(), ...); +``` + +**Description**: The current time of the client side system + +**Return value type**: TIMESTAMP + +**Applicable column types**: TIMESTAMP only + +**Applicable table types**: table, STable + +**More explanations**: + +- Add and Subtract operation can be performed, for example NOW() + 1s, the time unit can be: + b(nanosecond), u(microsecond), a(millisecond)), s(second), m(minute), h(hour), d(day), w(week) +- The precision of the returned timestamp is same as the precision set for the current data base in use + +#### TIMEDIFF + +```sql +SELECT TIMEDIFF(ts_val1 | datetime_string1 | ts_col1, ts_val2 | datetime_string2 | ts_col2 [, time_unit]) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**Description**: The difference between two timestamps, and rounded to the time unit specified by `time_unit` + +**Return value type**: Long Integer + +**Applicable column types**: UNIX timestamp constant, string constant of date/time format, or a column of TIMESTAMP type + +**Applicable table types**: table, STable + +**More explanations**: + +- Time unit specified by `time_unit` can be: + 1u(microsecond),1a(millisecond),1s(second),1m(minute),1h(hour),1d(day). +- The precision of the returned timestamp is same as the precision set for the current data base in use + +#### TIMETRUNCATE + +```sql +SELECT TIMETRUNCATE(ts_val | datetime_string | ts_col, time_unit) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**Description**: Truncate the input timestamp with unit specified by `time_unit` + +**Return value type**: TIMESTAMP + +**Applicable column types**: UNIX timestamp constant, string constant of date/time format, or a column of timestamp + +**Applicable table types**: table, STable + +**More explanations**: + +- Time unit specified by `time_unit` can be: + 1u(microsecond),1a(millisecond),1s(second),1m(minute),1h(hour),1d(day). +- The precision of the returned timestamp is same as the precision set for the current data base in use + +#### TIMEZONE + +```sql +SELECT TIMEZONE() FROM { tb_name | stb_name } [WHERE clause]; +``` + +**Description**: The timezone of the client side system + +**Return value type**: BINARY + +**Applicable column types**: None + +**Applicable table types**: table, STable + +#### TODAY + +```sql +SELECT TODAY() FROM { tb_name | stb_name } [WHERE clause]; +SELECT select_expr FROM { tb_name | stb_name } WHERE ts_col cond_operatior TODAY()]; +INSERT INTO tb_name VALUES (TODAY(), ...); +``` + +**Description**: The timestamp of 00:00:00 of the client side system + +**Return value type**: TIMESTAMP + +**Applicable column types**: TIMESTAMP only + +**Applicable table types**: table, STable + +**More explanations**: + +- Add and Subtract operation can be performed, for example NOW() + 1s, the time unit can be: + b(nanosecond), u(microsecond), a(millisecond)), s(second), m(minute), h(hour), d(day), w(week) +- The precision of the returned timestamp is same as the precision set for the current data base in use + ## Aggregate Functions -Aggregate queries are supported in TDengine by the following aggregate functions and selection 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. + +### AVG + +``` +SELECT AVG(field_name) FROM tb_name [WHERE clause]; +``` + +**Description**: Get the average value of a column in a table or STable + +**Return value type**: Double precision floating number + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table, STable ### COUNT @@ -25,141 +673,30 @@ SELECT COUNT([*|field_name]) FROM tb_name [WHERE clause]; - Wildcard (\*) is used to represent all columns. The `COUNT` function is used to 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. -**Examples**: +### ELAPSED -``` -taos> SELECT COUNT(*), COUNT(voltage) FROM meters; - count(*) | count(voltage) | -================================================ - 9 | 9 | -Query OK, 1 row(s) in set (0.004475s) - -taos> SELECT COUNT(*), COUNT(voltage) FROM d1001; - count(*) | count(voltage) | -================================================ - 3 | 3 | -Query OK, 1 row(s) in set (0.001075s) +```mysql +SELECT ELAPSED(field_name[, time_unit]) FROM { tb_name | stb_name } [WHERE clause] [INTERVAL(interval [, offset]) [SLIDING sliding]]; ``` -### AVG +**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. -``` -SELECT AVG(field_name) FROM tb_name [WHERE clause]; -``` +**Return value type**:Double -**Description**: Get the average value of a column in a table or STable +**Applicable Column type**:Timestamp -**Return value type**: Double precision floating number +**Applicable tables**: table, STable, outter in nested query -**Applicable column types**: Data types except for timestamp, binary, nchar and bool +**Explanations**: -**Applicable table types**: table, STable - -**Examples**: - -``` -taos> SELECT AVG(current), AVG(voltage), AVG(phase) FROM meters; - avg(current) | avg(voltage) | avg(phase) | -==================================================================================== - 11.466666751 | 220.444444444 | 0.293333333 | -Query OK, 1 row(s) in set (0.004135s) - -taos> SELECT AVG(current), AVG(voltage), AVG(phase) FROM d1001; - avg(current) | avg(voltage) | avg(phase) | -==================================================================================== - 11.733333588 | 219.333333333 | 0.316666673 | -Query OK, 1 row(s) in set (0.000943s) -``` - -### TWA - -``` -SELECT TWA(field_name) FROM tb_name WHERE clause; -``` - -**Description**: Time weighted average on a specific column within a time range - -**Return value type**: Double precision floating number - -**Applicable column types**: Data types except for timestamp, binary, nchar and bool - -**Applicable table types**: table, STable - -**More explanations**: - -- Since version 2.1.3.0, function TWA can be used on stable with `GROUP BY`, i.e. timelines generated by `GROUP BY tbname` on a STable. - -### IRATE - -``` -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. - -**Return value type**: Double precision floating number - -**Applicable column types**: Data types except for timestamp, binary, nchar and bool - -**Applicable table types**: table, STable - -**More explanations**: - -- Since version 2.1.3.0, function IRATE can be used on stble with `GROUP BY`, i.e. timelines generated by `GROUP BY tbname` on a STable. - -### SUM - -``` -SELECT SUM(field_name) FROM tb_name [WHERE clause]; -``` - -**Description**: The sum of a specific column in a table or STable - -**Return value type**: Double precision floating number or long integer - -**Applicable column types**: Data types except for timestamp, binary, nchar and bool - -**Applicable table types**: table, STable - -**Examples**: - -``` -taos> SELECT SUM(current), SUM(voltage), SUM(phase) FROM meters; - sum(current) | sum(voltage) | sum(phase) | -================================================================================ - 103.200000763 | 1984 | 2.640000001 | -Query OK, 1 row(s) in set (0.001702s) - -taos> SELECT SUM(current), SUM(voltage), SUM(phase) FROM d1001; - sum(current) | sum(voltage) | sum(phase) | -================================================================================ - 35.200000763 | 658 | 0.950000018 | -Query OK, 1 row(s) in set (0.000980s) -``` - -### STDDEV - -``` -SELECT STDDEV(field_name) FROM tb_name [WHERE clause]; -``` - -**Description**: Standard deviation of a specific column in a table or STable - -**Return value type**: Double precision floating number - -**Applicable column types**: Data types except for timestamp, binary, nchar and bool - -**Applicable table types**: table, STable (since version 2.0.15.1) - -**Examples**: - -``` -taos> SELECT STDDEV(current) FROM d1001; - stddev(current) | -============================ - 1.020892909 | -Query OK, 1 row(s) in set (0.000915s) -``` +- `field_name` parameter can only be the first column of a table, i.e. timestamp primary key. +- The minimum value of `time_unit` is the time precision of the database. If `time_unit` is not specified, the time precision of the database is used as the default ime unit. +- It can be used with `INTERVAL` to get the time valid time length of each time window. Please be noted that the return value is same as the time window for all time windows except for the first and the last time window. +- `order by asc/desc` has no effect on the result. +- `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. +- 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`. ### LEASTSQUARES @@ -175,16 +712,6 @@ SELECT LEASTSQUARES(field_name, start_val, step_val) FROM tb_name [WHERE clause] **Applicable table types**: table only -**Examples**: - -``` -taos> SELECT LEASTSQUARES(current, 1, 1) FROM d1001; - leastsquares(current, 1, 1) | -===================================================== -{slop:1.000000, intercept:9.733334} | -Query OK, 1 row(s) in set (0.000921s) -``` - ### MODE ``` @@ -199,27 +726,50 @@ SELECT MODE(field_name) FROM tb_name [WHERE clause]; **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 version**:Since version 2.6.0.0 - -**Examples**: +### SPREAD ``` -taos> select voltage from d002; - voltage | -======================== - 1 | - 1 | - 2 | - 19 | -Query OK, 4 row(s) in set (0.003545s) - -taos> select mode(voltage) from d002; - mode(voltage) | -======================== - 1 | -Query OK, 1 row(s) in set (0.019393s) +SELECT SPREAD(field_name) FROM { tb_name | stb_name } [WHERE clause]; ``` +**Description**: The difference between the max and the min of a specific column + +**Return value type**: Double precision floating point + +**Applicable column types**: Data types except for binary, nchar, and bool + +**Applicable table types**: table, STable + +**More explanations**: Can be used on a column of TIMESTAMP type, the result is the time range size. + +### STDDEV + +``` +SELECT STDDEV(field_name) FROM tb_name [WHERE clause]; +``` + +**Description**: Standard deviation of a specific column in a table or STable + +**Return value type**: Double precision floating number + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table, STable + +### SUM + +``` +SELECT SUM(field_name) FROM tb_name [WHERE clause]; +``` + +**Description**: The sum of a specific column in a table or STable + +**Return value type**: Double precision floating number or long integer + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table, STable + ### HYPERLOGLOG ``` @@ -234,31 +784,6 @@ SELECT HYPERLOGLOG(field_name) FROM { tb_name | stb_name } [WHERE clause]; **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. -**Applicable versions**:Since version 2.6.0.0 - -**Examples**: - -``` -taos> select dbig from shll; - dbig | -======================== - 1 | - 1 | - 1 | - NULL | - 2 | - 19 | - NULL | - 9 | -Query OK, 8 row(s) in set (0.003755s) - -taos> select hyperloglog(dbig) from shll; - hyperloglog(dbig)| -======================== - 4 | -Query OK, 1 row(s) in set (0.008388s) -``` - ### HISTOGRAM ``` @@ -271,262 +796,57 @@ SELECT HISTOGRAM(field_name,bin_type, bin_description, normalized) FROM tb_nam **Applicable column type**:Numerical types. -**Applicable versions**:Since version 2.6.0.0. - **Applicable table types**: table, STable **Explanations**: 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 how 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. - - "linear_bin": "{"start": 0.0, "width": 5.0, "count": 5, "infinity": true}" - "start" - bin starting point. - "width" - bin offset. - "count" - number of bins generated. - "infinity" - whether to add(-inf, inf)as start/end point in generated set of bins. - The above "linear_bin" descriptor generates a set of bins: [-inf, 0.0, 5.0, 10.0, 15.0, 20.0, +inf]. + - "linear_bin": "{"start": 0.0, "width": 5.0, "count": 5, "infinity": true}" + "start" - bin starting point. + "width" - bin offset. + "count" - number of bins generated. + "infinity" - whether to add(-inf, inf)as start/end point in generated set of bins. + The above "linear_bin" descriptor generates a set of bins: [-inf, 0.0, 5.0, 10.0, 15.0, 20.0, +inf]. - - "log_bin": "{"start":1.0, "factor": 2.0, "count": 5, "infinity": true}" - "start" - bin starting point. - "factor" - exponential factor of bin offset. - "count" - number of bins generated. - "infinity" - whether to add(-inf, inf)as start/end point in generated range of bins. - The above "log_bin" descriptor generates a set of bins:[-inf, 1.0, 2.0, 4.0, 8.0, 16.0, +inf]. + - "log_bin": "{"start":1.0, "factor": 2.0, "count": 5, "infinity": true}" + "start" - bin starting point. + "factor" - exponential factor of bin offset. + "count" - number of bins generated. + "infinity" - whether to add(-inf, inf)as start/end point in generated range of bins. + The above "log_bin" descriptor generates a set of bins:[-inf, 1.0, 2.0, 4.0, 8.0, 16.0, +inf]. 3. normalized: setting to 1/0 to turn on/off result normalization. -**Example**: +## Selector Functions -```mysql -taos> SELECT HISTOGRAM(voltage, "user_input", "[1,3,5,7]", 1) FROM meters; - histogram(voltage, "user_input", "[1,3,5,7]", 1) | - ======================================================= - {"lower_bin":1, "upper_bin":3, "count":0.333333} | - {"lower_bin":3, "upper_bin":5, "count":0.333333} | - {"lower_bin":5, "upper_bin":7, "count":0.333333} | - Query OK, 3 row(s) in set (0.004273s) +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. -taos> SELECT HISTOGRAM(voltage, 'linear_bin', '{"start": 1, "width": 3, "count": 3, "infinity": false}', 0) FROM meters; - histogram(voltage, 'linear_bin', '{"start": 1, "width": 3, " | - =================================================================== - {"lower_bin":1, "upper_bin":4, "count":3} | - {"lower_bin":4, "upper_bin":7, "count":3} | - {"lower_bin":7, "upper_bin":10, "count":3} | - Query OK, 3 row(s) in set (0.004887s) - -taos> SELECT HISTOGRAM(voltage, 'log_bin', '{"start": 1, "factor": 3, "count": 3, "infinity": true}', 0) FROM meters; - histogram(voltage, 'log_bin', '{"start": 1, "factor": 3, "count" | - =================================================================== - {"lower_bin":-inf, "upper_bin":1, "count":3} | - {"lower_bin":1, "upper_bin":3, "count":2} | - {"lower_bin":3, "upper_bin":9, "count":6} | - {"lower_bin":9, "upper_bin":27, "count":3} | - {"lower_bin":27, "upper_bin":inf, "count":1} | -``` - -### ELAPSED - -```mysql -SELECT ELAPSED(field_name[, time_unit]) FROM { tb_name | stb_name } [WHERE clause] [INTERVAL(interval [, offset]) [SLIDING sliding]]; -``` - -**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. - -**Return value type**:Double - -**Applicable Column type**:Timestamp - -**Applicable versions**:Sicne version 2.6.0.0 - -**Applicable tables**: table, STable, outter in nested query - -**Explanations**: -- `field_name` parameter can only be the first column of a table, i.e. timestamp primary key. -- The minimum value of `time_unit` is the time precision of the database. If `time_unit` is not specified, the time precision of the database is used as the default ime unit. -- It can be used with `INTERVAL` to get the time valid time length of each time window. Please be noted that the return value is same as the time window for all time windows except for the first and the last time window. -- `order by asc/desc` has no effect on the result. -- `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. -- 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`. - -## Selection Functions - -When any select function is used, timestamp column or tag columns including `tbname` can be specified to show that the selected value are from which rows. - -### MIN +### APERCENTILE ``` -SELECT MIN(field_name) FROM {tb_name | stb_name} [WHERE clause]; +SELECT APERCENTILE(field_name, P[, algo_type]) +FROM { tb_name | stb_name } [WHERE clause] ``` -**Description**: The minimum value of a specific column in a table or STable +**Description**: Similar to `PERCENTILE`, but a simulated result is returned -**Return value type**: Same as the data type of the column being operated upon +**Return value type**: Double precision floating point **Applicable column types**: Data types except for timestamp, binary, nchar and bool **Applicable table types**: table, STable -**Examples**: +**More explanations** -``` -taos> SELECT MIN(current), MIN(voltage) FROM meters; - min(current) | min(voltage) | -====================================== - 10.20000 | 218 | -Query OK, 1 row(s) in set (0.001765s) +- _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")`. +- When `t-digest` is used, `t-digest` sampling is used to calculate. -taos> SELECT MIN(current), MIN(voltage) FROM d1001; - min(current) | min(voltage) | -====================================== - 10.30000 | 218 | -Query OK, 1 row(s) in set (0.000950s) -``` - -### MAX - -``` -SELECT MAX(field_name) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**Description**: The maximum value of a specific column of a table or STable - -**Return value type**: Same as the data type of the column being operated upon - -**Applicable column types**: Data types except for timestamp, binary, nchar and bool - -**Applicable table types**: table, STable - -**Examples**: - -``` -taos> SELECT MAX(current), MAX(voltage) FROM meters; - max(current) | max(voltage) | -====================================== - 13.40000 | 223 | -Query OK, 1 row(s) in set (0.001123s) - -taos> SELECT MAX(current), MAX(voltage) FROM d1001; - max(current) | max(voltage) | -====================================== - 12.60000 | 221 | -Query OK, 1 row(s) in set (0.000987s) -``` - -### FIRST - -``` -SELECT FIRST(field_name) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**Description**: The first non-null value of a specific column in a table or STable - -**Return value type**: Same as the column being operated upon - -**Applicable column types**: Any data type - -**Applicable table types**: table, STable - -**More explanations**: - -- FIRST(\*) can be used to get the first non-null value of all columns -- NULL will be returned if all the values of the specified column are all NULL -- A result will NOT be returned if all the columns in the result set are all NULL - -**Examples**: - -``` -taos> SELECT FIRST(*) FROM meters; - first(ts) | first(current) | first(voltage) | first(phase) | -========================================================================================= -2018-10-03 14:38:04.000 | 10.20000 | 220 | 0.23000 | -Query OK, 1 row(s) in set (0.004767s) - -taos> SELECT FIRST(current) FROM d1002; - first(current) | -======================= - 10.20000 | -Query OK, 1 row(s) in set (0.001023s) -``` - -### LAST - -``` -SELECT LAST(field_name) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**Description**: The last non-NULL value of a specific column in a table or STable - -**Return value type**: Same as the column being operated upon - -**Applicable column types**: Any data type - -**Applicable table types**: table, STable - -**More explanations**: - -- LAST(\*) can be used to get the last non-NULL value of all columns -- If the values of a column in the result set are all NULL, NULL is returned for that column; if all columns in the result are all NULL, no result will be returned. -- When it's used on a STable, if there are multiple values with the timestamp in the result set, one of them will be returned randomly and it's not guaranteed that the same value is returned if the same query is run multiple times. - -**Examples**: - -``` -taos> SELECT LAST(*) FROM meters; - last(ts) | last(current) | last(voltage) | last(phase) | -======================================================================================== -2018-10-03 14:38:16.800 | 12.30000 | 221 | 0.31000 | -Query OK, 1 row(s) in set (0.001452s) - -taos> SELECT LAST(current) FROM d1002; - last(current) | -======================= - 10.30000 | -Query OK, 1 row(s) in set (0.000843s) -``` - -### TOP - -``` -SELECT TOP(field_name, K) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**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 - -**Applicable column types**: Data types except for timestamp, binary, nchar and bool - -**Applicable table types**: table, STable - -**More explanations**: - -- _k_ must be in range [1,100] -- The timestamp associated with the selected values are returned too -- Can't be used with `FILL` - -**Examples**: - -``` -taos> SELECT TOP(current, 3) FROM meters; - ts | top(current, 3) | -================================================= -2018-10-03 14:38:15.000 | 12.60000 | -2018-10-03 14:38:16.600 | 13.40000 | -2018-10-03 14:38:16.800 | 12.30000 | -Query OK, 3 row(s) in set (0.001548s) - -taos> SELECT TOP(current, 2) FROM d1001; - ts | top(current, 2) | -================================================= -2018-10-03 14:38:15.000 | 12.60000 | -2018-10-03 14:38:16.800 | 12.30000 | -Query OK, 2 row(s) in set (0.000810s) -``` +**Nested query**: It can be used in both the outer query and inner query in a nested query. ### BOTTOM @@ -548,100 +868,13 @@ SELECT BOTTOM(field_name, K) FROM { tb_name | stb_name } [WHERE clause]; - The timestamp associated with the selected values are returned too - Can't be used with `FILL` -**Examples**: +### FIRST ``` -taos> SELECT BOTTOM(voltage, 2) FROM meters; - ts | bottom(voltage, 2) | -=============================================== -2018-10-03 14:38:15.000 | 218 | -2018-10-03 14:38:16.650 | 218 | -Query OK, 2 row(s) in set (0.001332s) - -taos> SELECT BOTTOM(current, 2) FROM d1001; - ts | bottom(current, 2) | -================================================= -2018-10-03 14:38:05.000 | 10.30000 | -2018-10-03 14:38:16.800 | 12.30000 | -Query OK, 2 row(s) in set (0.000793s) +SELECT FIRST(field_name) FROM { tb_name | stb_name } [WHERE clause]; ``` -### PERCENTILE - -``` -SELECT PERCENTILE(field_name, P) 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. - -**Return value type**: Double precision floating point - -**Applicable column types**: Data types except for timestamp, binary, nchar and bool - -**Applicable table types**: table - -**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. - -**Examples**: - -``` -taos> SELECT PERCENTILE(current, 20) FROM d1001; -percentile(current, 20) | -============================ - 11.100000191 | -Query OK, 1 row(s) in set (0.000787s) -``` - -### APERCENTILE - -``` -SELECT APERCENTILE(field_name, P[, algo_type]) -FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: Similar to `PERCENTILE`, but a simulated result is returned - -**Return value type**: Double precision floating point - -**Applicable column types**: Data types except for timestamp, binary, nchar and bool - -**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")`. -- When `t-digest` is used, `t-digest` sampling is used to calculate. It can be used from version 2.2.0.0. - -**Nested query**: It can be used in both the outer query and inner query in a nested query. - -``` -taos> SELECT APERCENTILE(current, 20) FROM d1001; -apercentile(current, 20) | -============================ - 10.300000191 | -Query OK, 1 row(s) in set (0.000645s) - -taos> select apercentile (count, 80, 'default') from stb1; - apercentile (c0, 80, 'default') | -================================== - 601920857.210056424 | -Query OK, 1 row(s) in set (0.012363s) - -taos> select apercentile (count, 80, 't-digest') from stb1; - apercentile (c0, 80, 't-digest') | -=================================== - 605869120.966666579 | -Query OK, 1 row(s) in set (0.011639s) -``` - -### LAST_ROW - -``` -SELECT LAST_ROW(field_name) FROM { tb_name | stb_name }; -``` - -**Description**: The last row of a table or STable +**Description**: The first non-null value of a specific column in a table or STable **Return value type**: Same as the column being operated upon @@ -651,26 +884,11 @@ SELECT LAST_ROW(field_name) FROM { tb_name | stb_name }; **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. -- Can't be used with `INTERVAL`. +- FIRST(\*) can be used to get the first non-null value of all columns +- NULL will be returned if all the values of the specified column are all NULL +- A result will NOT be returned if all the columns in the result set are all NULL -**Examples**: - -``` - taos> SELECT LAST_ROW(current) FROM meters; - last_row(current) | - ======================= - 12.30000 | - Query OK, 1 row(s) in set (0.001238s) - - taos> SELECT LAST_ROW(current) FROM d1002; - last_row(current) | - ======================= - 10.30000 | - Query OK, 1 row(s) in set (0.001042s) -``` - -### INTERP [Since version 2.3.1] +### INTERP ``` SELECT INTERP(field_name) FROM { tb_name | stb_name } [WHERE where_condition] [ RANGE(timestamp1,timestamp2) ] [EVERY(interval)] [FILL ({ VALUE | PREV | NULL | LINEAR | NEXT})]; @@ -694,91 +912,89 @@ SELECT INTERP(field_name) FROM { tb_name | stb_name } [WHERE where_condition] [ - `INTERP` can only be used to interpolate in single timeline. So it must be used with `group by tbname` when it's used on a STable. It can't be used with `GROUP BY` when it's used in the inner query of a nested query. - The result of `INTERP` is not influenced by `ORDER BY TIMESTAMP`, which impacts the output order only.. -**Examples**: Based on the `meters` schema used throughout the documents - -- Single point linear interpolation between "2017-07-14 18:40:00" and "2017-07-14 18:40:00: +### LAST ``` - taos> SELECT INTERP(current) FROM t1 RANGE('2017-7-14 18:40:00','2017-7-14 18:40:00') FILL(LINEAR); +SELECT LAST(field_name) FROM { tb_name | stb_name } [WHERE clause]; ``` -- Get original data every 5 seconds, no interpolation, between "2017-07-14 18:00:00" and "2017-07-14 19:00:00: - -``` - taos> SELECT INTERP(current) FROM t1 RANGE('2017-7-14 18:00:00','2017-7-14 19:00:00') EVERY(5s); -``` - -- Linear interpolation every 5 seconds between "2017-07-14 18:00:00" and "2017-07-14 19:00:00: - -``` - taos> SELECT INTERP(current) FROM t1 RANGE('2017-7-14 18:00:00','2017-7-14 19:00:00') EVERY(5s) FILL(LINEAR); -``` - -- Backward interpolation every 5 seconds - -``` - taos> SELECT INTERP(current) FROM t1 EVERY(5s) FILL(NEXT); -``` - -- Linear interpolation every 5 seconds between "2017-07-14 17:00:00" and "2017-07-14 20:00:00" - -``` - taos> SELECT INTERP(current) FROM t1 where ts >= '2017-07-14 17:00:00' and ts <= '2017-07-14 20:00:00' RANGE('2017-7-14 18:00:00','2017-7-14 19:00:00') EVERY(5s) FILL(LINEAR); -``` - -### INTERP [Since version 2.0.15.0] - -``` -SELECT INTERP(field_name) FROM { tb_name | stb_name } WHERE ts='timestamp' [FILL ({ VALUE | PREV | NULL | LINEAR | NEXT})]; -``` - -**Description**: The value of a specific column that matches the specified time slice +**Description**: The last non-NULL value of a specific column in a table or STable **Return value type**: Same as the column being operated upon -**Applicable column types**: Numeric data type +**Applicable column types**: Any data type **Applicable table types**: table, STable **More explanations**: -- Time slice must be specified. If there is no data matching the specified time slice, interpolation is performed based on `FILL` parameter. Conditions such as tags or `tbname` can be used `Where` clause can be used to filter data. -- The timestamp specified must be within the time range of the data rows of the table or STable. If it is beyond the valid time range, nothing is returned even with `FILL` parameter. -- `INTERP` can be used to query only single time point once. `INTERP` can be used with `EVERY` to get the interpolation value every time interval. -- **Examples**: +- LAST(\*) can be used to get the last non-NULL value of all columns +- If the values of a column in the result set are all NULL, NULL is returned for that column; if all columns in the result are all NULL, no result will be returned. +- When it's used on a STable, if there are multiple values with the timestamp in the result set, one of them will be returned randomly and it's not guaranteed that the same value is returned if the same query is run multiple times. + +### LAST_ROW ``` - taos> SELECT INTERP(*) FROM meters WHERE ts='2017-7-14 18:40:00.004'; - interp(ts) | interp(current) | interp(voltage) | interp(phase) | - ========================================================================================== - 2017-07-14 18:40:00.004 | 9.84020 | 216 | 0.32222 | - Query OK, 1 row(s) in set (0.002652s) +SELECT LAST_ROW(field_name) FROM { tb_name | stb_name }; ``` -If there is no data corresponding to the specified timestamp, an interpolation value is returned if interpolation policy is specified by `FILL` parameter; or nothing is returned. +**Description**: The last row of a table or STable + +**Return value type**: Same as the column being operated upon + +**Applicable column types**: Any data type + +**Applicable table types**: table, STable + +**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. +- Can't be used with `INTERVAL`. + +### MAX ``` - taos> SELECT INTERP(*) FROM meters WHERE tbname IN ('d636') AND ts='2017-7-14 18:40:00.005'; - Query OK, 0 row(s) in set (0.004022s) - - taos> SELECT INTERP(*) FROM meters WHERE tbname IN ('d636') AND ts='2017-7-14 18:40:00.005' FILL(PREV); - interp(ts) | interp(current) | interp(voltage) | interp(phase) | - ========================================================================================== - 2017-07-14 18:40:00.005 | 9.88150 | 217 | 0.32500 | - Query OK, 1 row(s) in set (0.003056s) +SELECT MAX(field_name) FROM { tb_name | stb_name } [WHERE clause]; ``` -Interpolation is performed every 5 milliseconds between `['2017-7-14 18:40:00', '2017-7-14 18:40:00.014']` +**Description**: The maximum value of a specific column of a table or STable + +**Return value type**: Same as the data type of the column being operated upon + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table, STable + +### MIN ``` - taos> SELECT INTERP(current) FROM d636 WHERE ts>='2017-7-14 18:40:00' AND ts<='2017-7-14 18:40:00.014' EVERY(5a); - ts | interp(current) | - ================================================= - 2017-07-14 18:40:00.000 | 10.04179 | - 2017-07-14 18:40:00.010 | 10.16123 | - Query OK, 2 row(s) in set (0.003487s) +SELECT MIN(field_name) FROM {tb_name | stb_name} [WHERE clause]; ``` +**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 + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table, STable + +### PERCENTILE + +``` +SELECT PERCENTILE(field_name, P) 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. + +**Return value type**: Double precision floating point + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table + +**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. + ### TAIL ``` @@ -793,30 +1009,26 @@ SELECT TAIL(field_name, k, offset_val) FROM {tb_name | stb_name} [WHERE clause]; **Applicable column types**: Any data type except form timestamp, i.e. the primary key -**Applicable versions**: Since version 2.6.0.0 - -**Examples**: +### TOP ``` -taos> select ts,dbig from tail2; - ts | dbig | -================================================== -2021-10-15 00:31:33.000 | 1 | -2021-10-17 00:31:31.000 | NULL | -2021-12-24 00:31:34.000 | 2 | -2022-01-01 08:00:05.000 | 19 | -2022-01-01 08:00:06.000 | NULL | -2022-01-01 08:00:07.000 | 9 | -Query OK, 6 row(s) in set (0.001952s) - -taos> select tail(dbig,2,2) from tail2; -ts | tail(dbig,2,2) | -================================================== -2021-12-24 00:31:34.000 | 2 | -2022-01-01 08:00:05.000 | 19 | -Query OK, 2 row(s) in set (0.002307s) +SELECT TOP(field_name, K) FROM { tb_name | stb_name } [WHERE clause]; ``` +**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 + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table, STable + +**More explanations**: + +- _k_ must be in range [1,100] +- The timestamp associated with the selected values are returned too +- Can't be used with `FILL` + ### UNIQUE ``` @@ -829,179 +1041,14 @@ SELECT UNIQUE(field_name) FROM {tb_name | stb_name} [WHERE clause]; **Applicable column types**: Any data types except for timestamp -**Applicable versions**: Since version 2.6.0.0 - **More explanations**: - It can be used against table or STable, but can't be used together with time window, like `interval`, `state_window` or `session_window` . - Considering the number of result sets is unpredictable, it's suggested to limit the distinct values under 100,000 to control the memory usage, otherwise error will be returned. -**Examples**: +## Time-Series Specific Functions -``` -taos> select ts,voltage from unique1; - ts | voltage | -================================================== -2021-10-17 00:31:31.000 | 1 | -2022-01-24 00:31:31.000 | 1 | -2021-10-17 00:31:31.000 | 1 | -2021-12-24 00:31:31.000 | 2 | -2022-01-01 08:00:01.000 | 19 | -2021-10-17 00:31:31.000 | NULL | -2022-01-01 08:00:02.000 | NULL | -2022-01-01 08:00:03.000 | 9 | -Query OK, 8 row(s) in set (0.003018s) - -taos> select unique(voltage) from unique1; -ts | unique(voltage) | -================================================== -2021-10-17 00:31:31.000 | 1 | -2021-10-17 00:31:31.000 | NULL | -2021-12-24 00:31:31.000 | 2 | -2022-01-01 08:00:01.000 | 19 | -2022-01-01 08:00:03.000 | 9 | -Query OK, 5 row(s) in set (0.108458s) -``` - -## Scalar functions - -### DIFF - -```sql -SELECT {DIFF(field_name, ignore_negative) | DIFF(field_name)} FROM tb_name [WHERE clause]; -``` - -**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 - -**Applicable column types**: Data types except for timestamp, binary, nchar and bool - -**Applicable table types**: table, STable - -**More explanations**: - -- The number of result rows is the number of rows subtracted by one, no output for the first row -- Since version 2.1.30, `DIFF` can be used on STable with `GROUP by tbname` -- Since version 2.6.0, `ignore_negative` parameter is supported - -**Examples**: - -```sql -taos> SELECT DIFF(current) FROM d1001; - ts | diff(current) | -================================================= -2018-10-03 14:38:15.000 | 2.30000 | -2018-10-03 14:38:16.800 | -0.30000 | -Query OK, 2 row(s) in set (0.001162s) -``` - -### DERIVATIVE - -``` -SELECT DERIVATIVE(field_name, time_interval, ignore_negative) FROM tb_name [WHERE clause]; -``` - -**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 - -**Applicable column types**: Data types except for timestamp, binary, nchar and bool - -**Applicable table types**: table, STable - -**More explanations**: - -- It is available from version 2.1.3.0, 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. - -**Examples**: - -``` -taos> select derivative(current, 10m, 0) from t1; - ts | derivative(current, 10m, 0) | -======================================================== - 2021-08-20 10:11:22.790 | 0.500000000 | - 2021-08-20 11:11:22.791 | 0.166666620 | - 2021-08-20 12:11:22.791 | 0.000000000 | - 2021-08-20 13:11:22.792 | 0.166666620 | - 2021-08-20 14:11:22.792 | -0.666666667 | -Query OK, 5 row(s) in set (0.004883s) -``` - -### SPREAD - -``` -SELECT SPREAD(field_name) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**Description**: The difference between the max and the min of a specific column - -**Return value type**: Double precision floating point - -**Applicable column types**: Data types except for binary, nchar, and bool - -**Applicable table types**: table, STable - -**More explanations**: Can be used on a column of TIMESTAMP type, the result is the time range size. - -**Examples**: - -``` -taos> SELECT SPREAD(voltage) FROM meters; - spread(voltage) | -============================ - 5.000000000 | -Query OK, 1 row(s) in set (0.001792s) - -taos> SELECT SPREAD(voltage) FROM d1001; - spread(voltage) | -============================ - 3.000000000 | -Query OK, 1 row(s) in set (0.000836s) -``` - -### CEIL - -``` -SELECT CEIL(field_name) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**Description**: The rounded up value of a specific column - -**Return value type**: Same as the column being used - -**Applicable data types**: Data types except for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and outer query - -**More explanations**: - -- Can't be used on any tags of any type -- Arithmetic operation can be performed on the result of `ceil` function -- Can't be used with aggregate functions - -### FLOOR - -``` -SELECT FLOOR(field_name) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**Description**: The rounded down value of a specific column - -**More explanations**: The restrictions are same as those of the `CEIL` function. - -### ROUND - -``` -SELECT ROUND(field_name) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**Description**: The rounded value of a specific column. - -**More explanations**: The restrictions are same as `CEIL` function. +TDengine provides a set of time-series specific functions to better meet the requirements in querying time-series data. In general databases, similar functionalities can only be achieved with much more complex syntax and much worse performance. TDengine provides these functionalities in builtin functions so that the burden on user side is minimized. ### CSUM @@ -1026,7 +1073,61 @@ SELECT ROUND(field_name) FROM { tb_name | stb_name } [WHERE clause]; - 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 -**Applicable versions**: Since 2.3.0.x +### DERIVATIVE + +``` +SELECT DERIVATIVE(field_name, time_interval, ignore_negative) FROM tb_name [WHERE clause]; +``` + +**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 + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table, STable + +**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. +- It can be used together with `GROUP BY tbname` against a STable. + +### DIFF + +```sql +SELECT {DIFF(field_name, ignore_negative) | DIFF(field_name)} FROM tb_name [WHERE clause]; +``` + +**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 + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table, STable + +**More explanations**: + +- 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` + +### IRATE + +``` +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. + +**Return value type**: Double precision floating number + +**Applicable column types**: Data types except for timestamp, binary, nchar and bool + +**Applicable table types**: table, STable + +**More explanations**: + +- It can be used on stble with `GROUP BY`, i.e. timelines generated by `GROUP BY tbname` on a STable. ### MAVG @@ -1034,7 +1135,7 @@ SELECT ROUND(field_name) FROM { tb_name | stb_name } [WHERE clause]; SELECT MAVG(field_name, K) FROM { tb_name | stb_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 is _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 @@ -1051,8 +1152,6 @@ SELECT ROUND(field_name) FROM { tb_name | stb_name } [WHERE clause]; - 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. -**Applicable versions**: Since 2.3.0.x - ### SAMPLE ```sql @@ -1074,469 +1173,6 @@ SELECT ROUND(field_name) FROM { tb_name | stb_name } [WHERE clause]; - Arithmetic operation can't be operated on the result of `SAMPLE` function - Must be used with `Group by tbname` when it's used on a STable to force the result on each single timeline -**Applicable versions**: Since 2.3.0.x - -### ASIN - -```sql -SELECT ASIN(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The anti-sine of a specific column - -**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL - -**Applicable data types**: Data types except for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- Can't be used with tags -- Can't be used with aggregate functions - -### ACOS - -```sql -SELECT ACOS(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The anti-cosine of a specific column - -**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL - -**Applicable data types**: Data types except for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- Can't be used with tags -- Can't be used with aggregate functions - -### ATAN - -```sql -SELECT ATAN(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: anti-tangent of a specific column - -**Description**: The anti-cosine of a specific column - -**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL - -**Applicable data types**: Data types except for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- Can't be used with tags -- Can't be used with aggregate functions - -### SIN - -```sql -SELECT SIN(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The sine of a specific column - -**Description**: The anti-cosine of a specific column - -**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL - -**Applicable data types**: Data types except for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- Can't be used with tags -- Can't be used with aggregate functions - -### COS - -```sql -SELECT COS(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The cosine of a specific column - -**Description**: The anti-cosine of a specific column - -**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL - -**Applicable data types**: Data types except for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- Can't be used with tags -- Can't be used with aggregate functions - -### TAN - -```sql -SELECT TAN(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The tangent of a specific column - -**Description**: The anti-cosine of a specific column - -**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL - -**Applicable data types**: Data types except for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- Can't be used with tags -- Can't be used with aggregate functions - -### POW - -```sql -SELECT POW(field_name, power) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The power of a specific column with `power` as the index - -**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL - -**Applicable data types**: Data types except for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- Can't be used with tags -- Can't be used with aggregate functions - -### LOG - -```sql -SELECT LOG(field_name, base) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The log of a specific with `base` as the radix - -**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL - -**Applicable data types**: Data types except for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- Can't be used with tags -- Can't be used with aggregate functions - -### ABS - -```sql -SELECT ABS(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The absolute of a specific column - -**Return value type**: UBIGINT if the input value is integer; DOUBLE if the input value is FLOAT/DOUBLE - -**Applicable data types**: Data types except for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- Can't be used with tags -- Can't be used with aggregate functions - -### SQRT - -```sql -SELECT SQRT(field_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The square root of a specific column - -**Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL - -**Applicable data types**: Data types except for timestamp, binary, nchar, bool - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- Can't be used with tags -- Can't be used with aggregate functions - -### CAST - -```sql -SELECT CAST(expression AS type_name) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: It's used for type casting. The input parameter `expression` can be data columns, constants, scalar functions or arithmetic between them. Can't be used with tags, and can only be used in `select` clause. - -**Return value type**: The type specified by parameter `type_name` - -**Applicable data types**: - -- Parameter `expression` can be any data type except for JSON, more specifically it can be any of BOOL/TINYINT/SMALLINT/INT/BIGINT/FLOAT/DOUBLE/BINARY(M)/TIMESTAMP/NCHAR(M)/TINYINT UNSIGNED/SMALLINT UNSIGNED/INT UNSIGNED/BIGINT UNSIGNED -- The output data type specified by `type_name` can only be one of BIGINT/BINARY(N)/TIMESTAMP/NCHAR(N)/BIGINT UNSIGNED - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- 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: - 1)When casting BINARY/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 - 3)There may be overflow when casting unsigned BIGINT to BIGINT - 4)There may be overflow when casting FLOAT/DOUBLE to BIGINT or UNSIGNED BIGINT - -### CONCAT - -```sql -SELECT CONCAT(str1|column1, str2|column2, ...) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The concatenation result of two or more strings, the number of strings to be concatenated is at least 2 and at most 8 - -**Return value type**: Same as the columns being operated, BINARY or NCHAR; or NULL if all the input are NULL - -**Applicable data types**: The input data must be in either all BINARY or in all NCHAR; can't be used on tag columns - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -### CONCAT_WS - -``` -SELECT CONCAT_WS(separator, str1|column1, str2|column2, ...) FROM { tb_name | stb_name } [WHERE clause] -``` - -**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 - -**Return value type**: Same as the columns being operated, BINARY or NCHAR; or NULL if all the input are NULL - -**Applicable data types**: The input data must be in either all BINARY or in all NCHAR; can't be used on tag columns - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- 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 - -``` -SELECT LENGTH(str|column) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The length in bytes of a string - -**Return value type**: Integer - -**Applicable data types**: BINARY or NCHAR, can't be used on tags - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations** - -- If the input value is NULL, the output is NULL too - -### CHAR_LENGTH - -``` -SELECT CHAR_LENGTH(str|column) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: The length in number of characters of a string - -**Return value type**: Integer - -**Applicable data types**: BINARY or NCHAR, can't be used on tags - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations** - -- If the input value is NULL, the output is NULL too - -### LOWER - -``` -SELECT LOWER(str|column) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: Convert the input string to lower case - -**Return value type**: Same as input - -**Applicable data types**: BINARY or NCHAR, can't be used on tags - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations** - -- If the input value is NULL, the output is NULL too - -### UPPER - -``` -SELECT UPPER(str|column) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: Convert the input string to upper case - -**Return value type**: Same as input - -**Applicable data types**: BINARY or NCHAR, can't be used on tags - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations** - -- If the input value is NULL, the output is NULL too - -### LTRIM - -``` -SELECT LTRIM(str|column) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: Remove the left leading blanks of a string - -**Return value type**: Same as input - -**Applicable data types**: BINARY or NCHAR, can't be used on tags - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations** - -- If the input value is NULL, the output is NULL too - -### RTRIM - -``` -SELECT RTRIM(str|column) FROM { tb_name | stb_name } [WHERE clause] -``` - -**Description**: Remove the right tailing blanks of a string - -**Return value type**: Same as input - -**Applicable data types**: BINARY or NCHAR, can't be used on tags - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations** - -- If the input value is NULL, the output is NULL too - -### SUBSTR - -``` -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` - -**Return value type**: Same as input - -**Applicable data types**: BINARY or NCHAR, can't be used on tags - -**Applicable table types**: table, STable - -**Applicable nested query**: Inner query and Outer query - -**Applicable versions**: From 2.6.0.0 - -**More explanations**: - -- 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. -- If `len` is not specified, it means from `pos` to the end. - ### STATECOUNT ``` @@ -1558,39 +1194,11 @@ SELECT STATECOUNT(field_name, oper, val) FROM { tb_name | stb_name } [WHERE clau **Applicable nested query**: Outer query only -**Applicable versions**: From 2.6.0.0 - **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] - Can't be used with window operation, like interval/state_window/session_window -**Examples**: - -``` -taos> select ts,dbig from statef2; - ts | dbig | -======================================================== -2021-10-15 00:31:33.000000000 | 1 | -2021-10-17 00:31:31.000000000 | NULL | -2021-12-24 00:31:34.000000000 | 2 | -2022-01-01 08:00:05.000000000 | 19 | -2022-01-01 08:00:06.000000000 | NULL | -2022-01-01 08:00:07.000000000 | 9 | -Query OK, 6 row(s) in set (0.002977s) - -taos> select stateCount(dbig,GT,2) from statef2; -ts | dbig | statecount(dbig,gt,2) | -================================================================================ -2021-10-15 00:31:33.000000000 | 1 | -1 | -2021-10-17 00:31:31.000000000 | NULL | NULL | -2021-12-24 00:31:34.000000000 | 2 | -1 | -2022-01-01 08:00:05.000000000 | 19 | 1 | -2022-01-01 08:00:06.000000000 | NULL | NULL | -2022-01-01 08:00:07.000000000 | 9 | 2 | -Query OK, 6 row(s) in set (0.002791s) -``` - ### STATEDURATION ``` @@ -1613,320 +1221,59 @@ SELECT stateDuration(field_name, oper, val, unit) FROM { tb_name | stb_name } [W **Applicable nested query**: Outer query only -**Applicable versions**: From 2.6.0.0 - **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] - Can't be used with window operation, like interval/state_window/session_window -**Examples**: +### TWA ``` -taos> select ts,dbig from statef2; - ts | dbig | -======================================================== -2021-10-15 00:31:33.000000000 | 1 | -2021-10-17 00:31:31.000000000 | NULL | -2021-12-24 00:31:34.000000000 | 2 | -2022-01-01 08:00:05.000000000 | 19 | -2022-01-01 08:00:06.000000000 | NULL | -2022-01-01 08:00:07.000000000 | 9 | -Query OK, 6 row(s) in set (0.002407s) - -taos> select stateDuration(dbig,GT,2) from statef2; -ts | dbig | stateduration(dbig,gt,2) | -=================================================================================== -2021-10-15 00:31:33.000000000 | 1 | -1 | -2021-10-17 00:31:31.000000000 | NULL | NULL | -2021-12-24 00:31:34.000000000 | 2 | -1 | -2022-01-01 08:00:05.000000000 | 19 | 0 | -2022-01-01 08:00:06.000000000 | NULL | NULL | -2022-01-01 08:00:07.000000000 | 9 | 2 | -Query OK, 6 row(s) in set (0.002613s) +SELECT TWA(field_name) FROM tb_name WHERE clause; ``` -## Time Functions +**Description**: Time weighted average on a specific column within a time range -Since version 2.6.0.0, below time related functions can be used in TDengine. +**Return value type**: Double precision floating number -### NOW - -```sql -SELECT NOW() FROM { tb_name | stb_name } [WHERE clause]; -SELECT select_expr FROM { tb_name | stb_name } WHERE ts_col cond_operatior NOW(); -INSERT INTO tb_name VALUES (NOW(), ...); -``` - -**Description**: The current time of the client side system - -**Return value type**: TIMESTAMP - -**Applicable column types**: TIMESTAMP only +**Applicable column types**: Data types except for timestamp, binary, nchar and bool **Applicable table types**: table, STable **More explanations**: -- Add and Subtract operation can be performed, for example NOW() + 1s, the time unit can be: - b(nanosecond), u(microsecond), a(millisecond)), s(second), m(minute), h(hour), d(day), w(week) -- The precision of the returned timestamp is same as the precision set for the current data base in use +- It can be used on stable with `GROUP BY`, i.e. timelines generated by `GROUP BY tbname` on a STable. -**Examples**: +## System Information Functions -```sql -taos> SELECT NOW() FROM meters; - now() | -========================== - 2022-02-02 02:02:02.456 | -Query OK, 1 row(s) in set (0.002093s) +### DATABASE -taos> SELECT NOW() + 1h FROM meters; - now() + 1h | -========================== - 2022-02-02 03:02:02.456 | -Query OK, 1 row(s) in set (0.002093s) - -taos> SELECT COUNT(voltage) FROM d1001 WHERE ts < NOW(); - count(voltage) | -============================= - 5 | -Query OK, 5 row(s) in set (0.004475s) - -taos> INSERT INTO d1001 VALUES (NOW(), 10.2, 219, 0.32); -Query OK, 1 of 1 row(s) in database (0.002210s) +``` +SELECT DATABASE(); ``` -### TODAY +**Description**:Return the current database being used. If the user doesn't specify database when logon and doesn't use `USE` SQL command to switch the datbase, this function returns NULL. -```sql -SELECT TODAY() FROM { tb_name | stb_name } [WHERE clause]; -SELECT select_expr FROM { tb_name | stb_name } WHERE ts_col cond_operatior TODAY()]; -INSERT INTO tb_name VALUES (TODAY(), ...); +### CLIENT_VERSION + +``` +SELECT CLIENT_VERSION(); ``` -**Description**: The timestamp of 00:00:00 of the client side system +**Description**:Return the client version. -**Return value type**: TIMESTAMP +### SERVER_VERSION -**Applicable column types**: TIMESTAMP only - -**Applicable table types**: table, STable - -**More explanations**: - -- Add and Subtract operation can be performed, for example NOW() + 1s, the time unit can be: - b(nanosecond), u(microsecond), a(millisecond)), s(second), m(minute), h(hour), d(day), w(week) -- The precision of the returned timestamp is same as the precision set for the current data base in use - -**Examples**: - -```sql -taos> SELECT TODAY() FROM meters; - today() | -========================== - 2022-02-02 00:00:00.000 | -Query OK, 1 row(s) in set (0.002093s) - -taos> SELECT TODAY() + 1h FROM meters; - today() + 1h | -========================== - 2022-02-02 01:00:00.000 | -Query OK, 1 row(s) in set (0.002093s) - -taos> SELECT COUNT(voltage) FROM d1001 WHERE ts < TODAY(); - count(voltage) | -============================= - 5 | -Query OK, 5 row(s) in set (0.004475s) - -taos> INSERT INTO d1001 VALUES (TODAY(), 10.2, 219, 0.32); -Query OK, 1 of 1 row(s) in database (0.002210s) +``` +SELECT SERVER_VERSION(); ``` -### TIMEZONE +**Description**:Returns the server version. -```sql -SELECT TIMEZONE() FROM { tb_name | stb_name } [WHERE clause]; +### SERVER_STATUS + +``` +SELECT SERVER_VERSION(); ``` -**Description**: The timezone of the client side system - -**Return value type**: BINARY - -**Applicable column types**: None - -**Applicable table types**: table, STable - -**Examples**: - -```sql -taos> SELECT TIMEZONE() FROM meters; - timezone() | -================================= - UTC (UTC, +0000) | -Query OK, 1 row(s) in set (0.002093s) -``` - -### TO_ISO8601 - -```sql -SELECT TO_ISO8601(ts_val | ts_col) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**Description**: The ISO8601 date/time format converted from a UNIX timestamp, plus the timezone of the client side system - -**Return value type**: BINARY - -**Applicable column types**: TIMESTAMP, constant or a column - -**Applicable table types**: table, STable - -**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 a column of TIMESTAMP type, The precision of the returned value is same as the precision set for the current data base in use - -**Examples**: - -```sql -taos> SELECT TO_ISO8601(1643738400) FROM meters; - to_iso8601(1643738400) | -============================== - 2022-02-02T02:00:00+0800 | - -taos> SELECT TO_ISO8601(ts) FROM meters; - to_iso8601(ts) | -============================== - 2022-02-02T02:00:00+0800 | - 2022-02-02T02:00:00+0800 | - 2022-02-02T02:00:00+0800 | -``` - -### TO_UNIXTIMESTAMP - -```sql -SELECT TO_UNIXTIMESTAMP(datetime_string | ts_col) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**Description**: UNIX timestamp converted from a string of date/time format - -**Return value type**: Long integer - -**Applicable column types**: Constant or column of BINARY/NCHAR - -**Applicable table types**: table, STable - -**More explanations**: - -- The input string must be compatible with ISO8601/RFC3339 standard, 0 will be returned if the string can't be converted -- The precision of the returned timestamp is same as the precision set for the current data base in use - -**Examples**: - -```sql -taos> SELECT TO_UNIXTIMESTAMP("2022-02-02T02:00:00.000Z") FROM meters; -to_unixtimestamp("2022-02-02T02:00:00.000Z") | -============================================== - 1643767200000 | - -taos> SELECT TO_UNIXTIMESTAMP(col_binary) FROM meters; - to_unixtimestamp(col_binary) | -======================================== - 1643767200000 | - 1643767200000 | - 1643767200000 | -``` - -### TIMETRUNCATE - -```sql -SELECT TIMETRUNCATE(ts_val | datetime_string | ts_col, time_unit) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**Description**: Truncate the input timestamp with unit specified by `time_unit`\ - -**Return value type**: TIMESTAMP\ - -**Applicable column types**: UNIX timestamp constant, string constant of date/time format, or a column of timestamp - -**Applicable table types**: table, STable - -**More explanations**: - -- Time unit specified by `time_unit` can be: - 1u(microsecond),1a(millisecond),1s(second),1m(minute),1h(hour),1d(day). -- The precision of the returned timestamp is same as the precision set for the current data base in use - -**Examples**: - -```sql -taos> SELECT TIMETRUNCATE(1643738522000, 1h) FROM meters; - timetruncate(1643738522000, 1h) | -=================================== - 2022-02-02 02:00:00.000 | -Query OK, 1 row(s) in set (0.001499s) - -taos> SELECT TIMETRUNCATE("2022-02-02 02:02:02", 1h) FROM meters; - timetruncate("2022-02-02 02:02:02", 1h) | -=========================================== - 2022-02-02 02:00:00.000 | -Query OK, 1 row(s) in set (0.003903s) - -taos> SELECT TIMETRUNCATE(ts, 1h) FROM meters; - timetruncate(ts, 1h) | -========================== - 2022-02-02 02:00:00.000 | - 2022-02-02 02:00:00.000 | - 2022-02-02 02:00:00.000 | -Query OK, 3 row(s) in set (0.003903s) -``` - -### TIMEDIFF - -```sql -SELECT TIMEDIFF(ts_val1 | datetime_string1 | ts_col1, ts_val2 | datetime_string2 | ts_col2 [, time_unit]) FROM { tb_name | stb_name } [WHERE clause]; -``` - -**Description**: The difference between two timestamps, and rounded to the time unit specified by `time_unit` - -**Return value type**: Long Integer - -**Applicable column types**: UNIX timestamp constant, string constant of date/time format, or a column of TIMESTAMP type - -**Applicable table types**: table, STable - -**More explanations**: - -- Time unit specified by `time_unit` can be: - 1u(microsecond),1a(millisecond),1s(second),1m(minute),1h(hour),1d(day). -- The precision of the returned timestamp is same as the precision set for the current data base in use - -**Applicable versions**:Since version 2.6.0.0 - -**Examples**: - -```sql -taos> SELECT TIMEDIFF(1643738400000, 1643742000000) FROM meters; - timediff(1643738400000, 1643742000000) | -========================================= - 3600000 | -Query OK, 1 row(s) in set (0.002553s) -taos> SELECT TIMEDIFF(1643738400000, 1643742000000, 1h) FROM meters; - timediff(1643738400000, 1643742000000, 1h) | -============================================= - 1 | -Query OK, 1 row(s) in set (0.003726s) - -taos> SELECT TIMEDIFF("2022-02-02 03:00:00", "2022-02-02 02:00:00", 1h) FROM meters; - timediff("2022-02-02 03:00:00", "2022-02-02 02:00:00", 1h) | -============================================================= - 1 | -Query OK, 1 row(s) in set (0.001937s) - -taos> SELECT TIMEDIFF(ts_col1, ts_col2, 1h) FROM meters; - timediff(ts_col1, ts_col2, 1h) | -=================================== - 1 | -Query OK, 1 row(s) in set (0.001937s) -``` +**Description**:Returns the server's status.