## SPECIFY THE DEFAULT DATABASE IN FOLLOWING OPERATIONS
## Specify The Database In Use
```
USE db_name;
...
...
@@ -40,7 +40,7 @@ This way is not applicable when using a REST connection
:::
## DROP DATABASE
## Drop Database
```
DROP DATABASE [IF EXISTS] db_name;
...
...
@@ -51,7 +51,7 @@ All data in the database will be deleted too. This command must be used with cau
:::
## CHANGE DATABASE CONFIGURATION
## Change Database Configuration
Some examples are shown below to demonstrate how to change the configuration of a database. Please be noted that some configuration parameters can be changed after the database is created, but some others can't, for details of the configuration parameters of database please refer to [Configuration Parameters](/reference/config/).
...
...
@@ -96,13 +96,13 @@ The above parameters can be changed using `ALTER DATABASE` command without resta
1. The first column of a table must be in TIMESTAMP type, and it will be set as primary key automatically
2. The maximum length of table name is 192 bytes.
3. The maximum length of each row is 16k bytes, please be notes that the extra 2 bytes used by each BINARY/NCHAR column are also counted in.
4. The name of sub-table can only be consisted of English characters, digits and underscore, and can't be started with digit. Table names are case insensitive.
5. The maximum length in bytes must be specified when using BINARY or NCHAR type.
6. Escape character "\`" can be used to avoid the conflict between table names and reserved keywords, above rules will be bypassed when using escape character on table names, but the upper limit for name length is still valid. The table names specified using escape character are case sensitive. Only ASCII visible characters can be used with escape character.
For example \`aBc\` and \`abc\` are different table names but `abc` and `aBc` are same table names because they are both converted to `abc` internally.
:::
### 以超级表为模板创建数据表
### Create Table Using STable As Template
```
CREATE TABLE [IF NOT EXISTS] tb_name USING stb_name TAGS (tag_value1, ...);
```
以指定的超级表为模板，指定 TAGS 的值来创建数据表。
The above command creates a sub table using the specified super table as template and the specified tab values.
### 以超级表为模板创建数据表，并指定具体的 TAGS 列
### Create Table Using STable As Template With A Part of Tags
```
CREATE TABLE [IF NOT EXISTS] tb_name USING stb_name (tag_name1, ...) TAGS (tag_value1, ...);
This way is useful when migrating the data in one TDengine cluster to another one because it can be used to create exactly same tables in the target database.
## 获取表的结构信息
## Show Table Definition
```
DESCRIBE tb_name;
```
## 修改表定义
## Change Table Definition
### 表增加列
### Add A Column
```
ALTER TABLE tb_name ADD COLUMN field_name data_type;
If a table is created using a super table as template, the table definition can only be changed on the corresponding super table, but the change will be automatically applied to all the sub tables created using this super table as template. For tables created in normal way, the table definition can be changed directly on the table.
:::
### 表修改列宽
### Change Column Length
```
ALTER TABLE tb_name MODIFY COLUMN field_name data_type(length);
The the type of a column is variable length, like BINARY or NCHAR, this way can be used to change (or increase) the length of the column.
### 修改子表标签值
:::note
If a table is created using a super table as template, the table definition can only be changed on the corresponding super table, but the change will be automatically applied to all the sub tables created using this super table as template. For tables created in normal way, the table definition can be changed directly on the table.
:::
### Change Tag Value Of Sub Table
```
ALTER TABLE tb_name SET TAG tag_name=new_tag_value;
```
如果表是通过超级表创建，可以使用此指令修改其标签值
This command can be used to change the tag value if the table is created using a super table as template.
The SQL statement of creating STable is similar to that of creating table, but a special column named as `TAGS` must be specified with the names and types of the tags.
1. The tag types specified in TAGS should NOT be timestamp. Since 2.1.3.0 timestamp type can be used in TAGS column, but its value must be fixed and arithmetic operation can't be applied on it.
2. The tag names specified in TAGS should NOT be same as other columns.
3. The tag names specified in TAGS should NOT be same as any reserved keywords.(Please refer to [keywords](/taos-sql/keywords/)
4. The maximum number of tags specified in TAGS is 128, but there must be at least one tag, and the total length of all tag columns should NOT exceed 16KB.
:::
## 删除超级表
## Drop STable
```
DROP STABLE [IF EXISTS] stb_name;
```
删除 STable 会自动删除通过 STable 创建的子表。
All the sub-tables created using the deleted stable will be deleted automatically.
This command can be used to display the information of all STables in the current database, including name, creation time, number of columns, number of tags, number of tables created using this STable.
This command is useful in migrating data from one TDengine cluster to another one because it can be used to create an exactly same STable in the target database.
## 获取超级表的结构信息
## Get STable Definition
```
DESCRIBE stb_name;
```
## 修改超级表普通列
## Change Columns Of STable
### 超级表增加列
### Add A Column
```
ALTER STABLE stb_name ADD COLUMN field_name data_type;
```
### 超级表删除列
### Remove A Column
```
ALTER STABLE stb_name DROP COLUMN field_name;
```
### 超级表修改列宽
### Change Column Length
```
ALTER STABLE stb_name MODIFY COLUMN field_name data_type(length);
This command is used to add a new tag for a STable and specify the tag type.
### 删除标签
### Remove A Tag
```
ALTER STABLE stb_name DROP TAG tag_name;
```
删除超级表的一个标签，从超级表删除某个标签后，该超级表下的所有子表也会自动删除该标签。
The tag will be removed automatically from all the sub tables crated using the super table as template once a tag is removed from a super table.
### 修改标签名
### Change A Tag
```
ALTER STABLE stb_name CHANGE TAG old_tag_name new_tag_name;
```
修改超级表的标签名，从超级表修改某个标签名后，该超级表下的所有子表也会自动更新该标签名。
The tag name will be changed automatically from all the sub tables crated using the super table as template once a tag name is changed for a super table.
### 修改标签列宽度
### Change Tag Length
```
ALTER STABLE stb_name MODIFY TAG tag_name data_type(length);
Changing tag value can be applied to only sub tables. All other tag operations, like add tag, remove tag, however, can be applied to only STable. If a new tag is added for a STable, the tag will be added with NULL value for all its sub tables.
2. 在使用“插入多条记录”方式写入数据时，不能把第一列的时间戳取值都设为 NOW，否则会导致语句中的多条记录使用相同的时间戳，于是就可能出现相互覆盖以致这些数据行无法全部被正确保存。其原因在于，NOW 函数在执行中会被解析为所在 SQL 语句的实际执行时间，出现在同一语句中的多个 NOW 标记也就会被替换为完全相同的时间戳取值。
3. 允许插入的最老记录的时间戳，是相对于当前服务器时间，减去配置的 keep 值（数据保留的天数）；允许插入的最新记录的时间戳，是相对于当前服务器时间，加上配置的 days 值（数据文件存储数据的时间跨度，单位为天）。keep 和 days 都是可以在创建数据库时指定的，缺省值分别是 3650 天和 10 天。
1. In the second example above, different formats are used in the two rows to be inserted. In the first row, the timestamp format is a date and time string, which is interpreted from the string value only. In the second row, the timestamp format is a long integer, which will be interpreted based on the database time precision.
2. When trying to insert multiple rows in single statement, only the timestamp of one row can be set as NOW, otherwise there will be duplicate timestamps among the rows and the result may be out of expectation because NOW will be interpreted as the time when the statement is executed.
3. The oldest timestamp that is allowed is subtracting the KEEP parameter from current time.
4. The newest timestamp that is allowed is adding the DAYS parameter to current time.
If no columns are explicitly specified, all the columns must be provided with values, this is called "all column mode". The insert performance of all column mode is much better than specifying a part of columns, so it's encouraged to use "all column mode" while providing NULL value explicitly for the columns for which no actual value can be provided.
:::
## 向多个表插入记录
## Insert Into Multiple Tables
可以在一条语句中，分别向多个表插入一条或多条记录，并且也可以在插入过程中指定列。例如：
One or multiple rows can be inserted into multiple tables in single SQL statement, with or without specifying specific columns.
If it's not sure whether the table already exists, the table can be created automatically while inserting using below SQL statement. To use this functionality, a STable must be used as template and tag values must be provided.
Prior to version 2.0.20.5, when using `INSERT` to create table automatically and specify the columns, the column names must follow the table name immediately. From version 2.0.20.5, the column names can follow the table name immediately, also can be put between `TAGS` and `VALUES`. In same SQL statement, however, these two ways of specifying column names can't be mixed.
Besides using `VALUES` to insert one or multiple rows, the data to be inserted can also be prepared in a CSV file with comma as separator and each field value quoted by single quotes. Table definition is not required in the CSV file. For example, if file "/tmp/csvfile.csv" contains below data:
```
'2021-07-13 14:07:34.630', '10.2', '219', '0.32'
'2021-07-13 14:07:35.779', '10.15', '217', '0.33'
```
那么通过如下指令可以把这个文件中的数据写入子表中：
Then data in this file can be inserted by below SQL statement:
```
```sql
INSERTINTOd1001FILE'/tmp/csvfile.csv';
```
## 插入来自文件的数据记录，并自动建表
## CreateTables Automatically and Insert Rows From File
For SQL statement like `insert`, stream parsing strategy is applied. That means before an error is found and the execution is aborted, the part prior to the error point has already been executed. Below is an experiment to help understand the behavior.
The output shows the value to be inserted is invalid. But `SHOW TABLES` proves that the table has been created automatically by the `INSERT` statement.
```
DB error: invalid SQL: 'a' (invalid timestamp) (0.039494s)
taos> SHOW TABLES;
...
...
@@ -147,3 +161,5 @@ taos> SHOW TABLES;
d1001 | 2020-08-06 17:52:02.097 | 4 | meters |
Query OK, 1 row(s) in set (0.001091s)
```
From the above experiment, we can see that even though the value to be inserted is invalid but the table is still created.
In JOIN query, however, with or without table name prefix will return different results. \* without table prefix will return all the columns of both tables, but \* with table name as prefix will return only the columns of that table.
```
taos> SELECT * FROM d1001, d1003 WHERE d1001.ts=d1003.ts;
...
...
@@ -77,8 +77,7 @@ taos> SELECT d1001.* FROM d1001,d1003 WHERE d1001.ts = d1003.ts;
Wilcard \* can be used with some functions, but the result may be different depending on the function being used. For example, `count(*)` returns only one column, i.e. the number of rows; `first`, `last` and `last_row` return all columns of the selected row.
```
taos> SELECT COUNT(*) FROM d1001;
...
...
@@ -96,9 +95,9 @@ taos> SELECT FIRST(*) FROM d1001;
Starting from version 2.0.14, tag columns can be selected together with data columns when querying sub tables. Please be noted that, however, wildcard \* doesn't represent any tag column, that means tag columns must be specified explicitly like below example.
```
taos> SELECT location, groupid, current FROM d1001 LIMIT 2;
...
...
@@ -109,33 +108,26 @@ taos> SELECT location, groupid, current FROM d1001 LIMIT 2;
`DISTINCT` keyword can be used to get all the unique values of tag columns from a super table, it can also be used to get all the unique values of data columns from a table or sub table.
1.Configuration parameter `maxNumOfDistinctRes` in `taos.cfg` is used to control the number of rows to output. The minimum configurable value is 100,000, the maximum configurable value is 100,000,000, the default value is 1000,000. If the actual number of rows exceeds the value of this parameter, only the number of rows specified by this parameter will be output.
2.It can't be guaranteed that the results selected by using `DISTINCT` on columns of `FLOAT` or `DOUBLE` are exactly unique because of the precision nature of floating numbers.
3.`DISTINCT` can't be used in the sub-query of a nested query statement, and can't be used together with aggregate functions, `GROUP BY` or `JOIN` in same SQL statement.
When using `SELECT`, the column names in the result set will be same as that in the select clause if `AS` is not used. `AS` can be used to rename the column names in the result set. For example
```
taos> SELECT ts, ts AS primary_key_ts FROM d1001;
...
...
@@ -147,27 +139,30 @@ taos> SELECT ts, ts AS primary_key_ts FROM d1001;
`AS` can't be used together with `first(*)`, `last(*)`, or `last_row(*)`.
## 隐式结果列
## Implicit Columns
`Select_exprs`可以是表所属列的列名，也可以是基于列的函数表达式或计算式，数量的上限 256 个。当用户使用了`interval`或`group by tags`的子句以后，在最后返回结果中会强制返回时间戳列（第一列）和 group by 子句中的标签列。后续的版本中可以支持关闭 group by 子句中隐式列的输出，列输出完全由 select 子句控制。
`Select_exprs` can be column names of a table, or function expression or arithmetic expression on columns. The maximum number of allowed column names and expressions is 256. Timestamp and the corresponding tag names will be returned in the result set if `interval` or `group by tags` are used, and timestamp will always be the first column in the result set.
`FROM` can be followed by a number of tables or super tables, or can be followed by a sub-query. If no database is specified as current database in use, table names must be preceded with database name, like `power.d1001`.
```
```SQL
SELECT * FROM power.d1001;
------------------------------
```
has same effect as
```SQL
USE power;
SELECT * FROM d1001;
```
## 特殊功能
## Special Query
部分特殊的查询功能可以不使用 FROM 子句执行。获取当前所在的数据库 database()：
Some special query functionalities can be performed without `FORM` sub-clause. For example, below statement can be used to get the current database in use.
```
taos> SELECT DATABASE();
...
...
@@ -177,7 +172,7 @@ taos> SELECT DATABASE();
Query OK, 1 row(s) in set (0.000079s)
```
如果登录的时候没有指定默认数据库，且没有使用`USE`命令切换数据，则返回 NULL。
If no database is specified upon logging in and no database is specified with `USE` after login, NULL will be returned by `select database()`.
```
taos> SELECT DATABASE();
...
...
@@ -187,7 +182,7 @@ taos> SELECT DATABASE();
Query OK, 1 row(s) in set (0.000184s)
```
获取服务器和客户端版本号：
Below statement can be used to get the version of client or server.
Below statement is used to check the server status. One integer, like `1`, is returned if the server status is OK, otherwise an error code is returned. This way is compatible with the status check for TDengine from connection pool or 3rd party tools, and can avoid the problem of losing connection from connection pool when using wrong heartbeat checking SQL statement.
```
taos> SELECT SERVER_STATUS();
...
...
@@ -219,66 +214,59 @@ taos> SELECT SERVER_STATUS() AS status;
Query OK, 1 row(s) in set (0.000081s)
```
## \_block_dist 函数
## \_block_dist
**功能说明**: 用于获得指定的（超级）表的数据块分布信息
**Description**: Get the data block distribution of a table or stable.
```txt title="语法"
```SQL title="Syntax"
SELECT _block_dist() FROM { tb_name | stb_name }
```
**返回结果类型**：字符串。
**适用数据类型**：不能输入任何参数。
**嵌套子查询支持**：不支持子查询或嵌套查询。
**Restrictions**：No argument is allowed, where clause is not allowed
**返回结果**:
**Sub Query**：Sub query or nested query are not supported
- 返回 FROM 子句中输入的表或超级表的数据块分布情况。不支持查询条件。
- 返回的结果是该表或超级表的数据块所包含的行数的数据分布直方图。
**Return value**: A string which includes the data block distribution of the specified table or stable, i.e. the histogram of rows stored in the data blocks of the table or stable.
-Histogram about the rows stored in the data blocks of the table or stable: the value of rows for 5%, 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90%, 95%, and 99%
-Minimum number of rows stored in a data block, i.e. Min=[392(Rows)]
-Maximum number of rows stored in a data block, i.e. Max=[800(Rows)]
-Average number of rows stored in a data block, i.e. Avg=[666(Rows)]
-stddev of number of rows, i.e. Stddev=[2.17]
-Total number of rows, i.e. Rows[2000]
-Total number of data blocks, i.e. Blocks=[3]
-Total disk size consumed, i.e. Size=[5.440(Kb)]
-Compression ratio, which means the compressed size divided by original size, i.e. Comp=[0.23]
-Total number of rows in memory, i.e. RowsInMem=[0], which means no rows in memory
-The time spent on reading head file (to retrieve data block information), i.e. SeekHeaderTime=[1(us)], which means 1 microsecond.
- 暂不支持含列名的四则运算表达式作为 SQL 函数的应用对象（例如，不支持 `select min(2*a) from t;`，但可以写 `select 2*min(a) from t;`）。
-WHERE 语句可以使用各种逻辑判断来过滤数字值，或使用通配符来过滤字符串。
-输出结果缺省按首列时间戳升序排序，但可以指定按降序排序( \_c0 指首列时间戳)。使用 ORDER BY 对其他字段进行排序,排序结果顺序不确定。
-参数 LIMIT 控制输出条数，OFFSET 指定从第几条开始输出。LIMIT/OFFSET 对结果集的执行顺序在 ORDER BY 之后。且 `LIMIT 5 OFFSET 2` 可以简写为 `LIMIT 2, 5`。
- 在有 GROUP BY 子句的情况下，LIMIT 参数控制的是每个分组中至多允许输出的条数。
-参数 SLIMIT 控制由 GROUP BY 指令划分的分组中，至多允许输出几个分组的数据。且 `SLIMIT 5 SOFFSET 2` 可以简写为 `SLIMIT 2, 5`。
-通过 “>>” 输出结果可以导出到指定文件。
-Wildcard \* can be used to get all columns, or specific column names can be specified. Arithmetic operation can be performed on columns of number types, columns can be renamed in the result set.
- Arithmetic operation on columns can't be used in where clause. For example, `where a*2>6;` is not allowed but `where a>6/2;` can be used instead for same purpose.
- Arithmetic operation on columns can't be used as the objectives of select statement. For example, `select min(2*a) from t;` is not allowed but `select 2*min(a) from t;` can be used instead.
-Logical operation can be used in `WHERE` clause to filter numeric values, wildcard can be used to filter string values.
-Result set are arranged in ascending order of the first column, i.e. timestamp, but it can be controlled to output as descending order of timestamp. If `order by` is used on other columns, the result may be not as expected. By the way, \_c0 is used to represent the first column, i.e. timestamp.
-`LIMIT` parameter is used to control the number of rows to output. `OFFSET` parameter is used to specify from which row to output. `LIMIT` and `OFFSET` are executed after `ORDER BY` in the query execution. A simple tip is that `LIMIT 5 OFFSET 2` can be abbreviated as `LIMIT 2, 5`.
- What is controlled by `LIMIT` is the number of rows in each group when `GROUP BY` is used.
-`SLIMIT` parameter is used to control the number of groups when `GROUP BY` is used. Similar to `LIMIT`, `SLIMIT 5 OFFSET 2` can be abbreviated as `SLIMIT 2, 5`.
-">>" can be used to output the result set of `select` statement to the specified file.
## 条件过滤操作
## Where
Logical operations in below table can be used in `where` clause to filter the resulting rows.
| **Operation** | **Note** | **Applicable Data Types** |
- Operator `<\>` is equal to `!=`, please be noted that this operator can't be used on the first column of any table, i.e.timestamp column.
- Operator `like` is used together with wildcards to match strings
- '%' matches 0 or any number of characters, '\_' matches any single ASCII character.
-`\_` is used to match the \_ in the string.
- The maximum length of wildcard string is 100 bytes from version 2.1.6.1 (before that the maximum length is 20 bytes). `maxWildCardsLength` in `taos.cfg` can be used to control this threshold. Too long wildcard string may slowdown the execution performance of `LIKE` operator.
-`AND` keyword can be used to filter multiple columns simultaneously. AND/OR operation can be performed on single or multiple columns from version 2.3.0.0. However, before 2.3.0.0 `OR` can't be used on multiple columns.
- For timestamp column, only one condition can be used; for other columns or tags, `OR` keyword can be used to combine multiple logical operators. For example, `((value > 20 AND value < 30) OR (value < 12))`.
- From version 2.3.0.0, multiple conditions can be used on timestamp column, but the result set can only contain single time range.
- From version 2.0.17.0, operator `BETWEEN AND` can be used in where clause, for example `WHERE col2 BETWEEN 1.5 AND 3.25` means the filter condition is equal to "1.5 ≤ col2 ≤ 3.25".
- From version 2.1.4.0, operator `IN` can be used in where clause. For example, `WHERE city IN ('Beijing', 'Shanghai')`. For bool type, both `{true, false}` and `{0, 1}` are allowed, but integers other than 0 or 1 are not allowed. FLOAT and DOUBLE types are impacted by floating precision, only values that match the condition within the tolerance will be selected. Non-primary key column of timestamp type can be used with `IN`.
- From version 2.3.0.0, regular expression is supported in where clause with keyword `match` or `nmatch`, the regular expression is case insensitive.
## 正则表达式过滤
## Regular Expression
### 语法
### Syntax
```txt
```SQL
WHERE (column|tbname) **match/MATCH/nmatch/NMATCH** _regex_
The regular expression being used must be compliant with POSIX specification, please refer to [Regular Expressions](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html).
The maximum length of regular expression string is 128 bytes. Configuration parameter `maxRegexStringLen` can be used to set the maximum allowed regular expression. It's a configuration parameter on client side, and will take in effect after restarting the client.
From version 2.2.0.0, inner join is fully supported in TDengine. More specifically, the inner join between table and table, that between stable and stable, and that between sub query and sub query are supported.
在普通表与普通表之间的 JOIN 操作中，只能使用主键时间戳之间的相等关系。例如：
Only primary key, i.e. timestamp, can be used in the join operation between table and table. For example:
```sql
SELECT*
...
...
@@ -368,7 +357,7 @@ FROM temp_tb_1 t1, pressure_tb_1 t2
Nested query is also called sub query, that means in a single SQL statement the result of inner query can be used as the data source of the outer query.
From 2.2.0.0, unassociated sub query can be used in the `FROM` clause. unassociated means the sub query doesn't use the parameters in the parent query. More specifically, in the `tb_name_list` of `SELECT` statement, an independent SELECT statement can be used. So a complete nested query looks like:
```
```SQL
SELECT ... FROM (SELECT ... FROM ...) ...;
```
:::info
-目前仅支持一层嵌套，也即不能在子查询中再嵌入子查询。
-内层查询的返回结果将作为“虚拟表”供外层查询使用，此虚拟表可以使用 AS 语法做重命名，以便于外层查询中方便引用。
-Only one layer of nesting is allowed, that means no sub query is allowed in a sub query
-The result set returned by the inner query will be used as a "virtual table" by the outer query, the "virtual table" can be renamed using `AS` keyword for easy reference in the outer query.
-Sub query is not allowed in continuous query.
-JOIN operation is allowed between tables/stables inside both inner and outer queries. Join operation can be performed on the result set of the inner query.
-UNION operation is not allowed in either inner query or outer query.
-The functionalities that can be used in the inner query is same as non-nested query.
-`ORDER BY` inside the inner query doesn't make any sense but will slow down the query performance significantly, so please avoid such usage.
-Compared to the non-nested query, the functionalities that can be used in the outer query have such restrictions as:
- Functions
- If the result set returned by the inner query doesn't contain timestamp column, then functions relying on timestamp can't be used in the outer query, like `TOP`, `BOTTOM`, `FIRST`, `LAST`, `DIFF`.
- Functions that need to scan the data twice can't be used in the outer query, like `STDDEV`, `PERCENTILE`.
-`IN` operator is not allowed in the outer query but can be used in the inner query.
-`GROUP BY` is not supported in the outer query.
:::
## UNION ALL 子句
## UNION ALL
```txt title=语法
```SQL title=Syntax
SELECT ...
UNION ALL SELECT ...
[UNION ALL SELECT ...]
```
TDengine 支持 UNION ALL 操作符。也就是说，如果多个 SELECT 子句返回结果集的结构完全相同（列名、列类型、列数、顺序），那么可以通过 UNION ALL 把这些结果集合并到一起。目前只支持 UNION ALL 模式，也即在结果集的合并过程中是不去重的。在同一个 sql 语句中，UNION ALL 最多支持 100 个。
`UNION ALL` operator can be used to combine the result set from multiple select statements as long as the result set of these select statements have exactly same columns. `UNION ALL` doesn't remove redundant rows from multiple result sets. In single SQL statement, at most 100 `UNION ALL` can be supported.
The rows between 2018-06-01 08:00:00.000 and 2018-06-02 08:00:00.000 and col3 ends with 'nny' can be selected in the descending order of timestamp using below SQL statement:
```
```SQL
SELECT * FROM tb1 WHERE ts > '2018-06-01 08:00:00.000' AND ts <= '2018-06-02 08:00:00.000' AND col3 LIKE '%nny' ORDER BY ts DESC;
The sum of col1 and col2 for rows later than 2018-06-01 08:00:00.000 and whose col2 is bigger than 1.2 can be selected and renamed as "complex", while only 10 rows are output from the 5th row, by below SQL statement:
```
```SQL
SELECT (col1 + col2) AS 'complex' FROM tb1 WHERE ts > '2018-06-01 08:00:00.000' AND col2 > 1.2 LIMIT 10 OFFSET 5;
The rows in the past 10 minutes and whose col2 is bigger than 3.14 are selected and output to the result file `/home/testoutpu.csv` with below SQL statement:
```
```SQL
SELECT COUNT(*) FROM tb1 WHERE ts >= NOW - 10m AND col2 > 3.14 >> /home/testoutpu.csv;
**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.
**返回数据类型**：双精度浮点数 Double。
**Return value type**:Double precision floating number
**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。
**Applicable column types**:Data types except for timestamp, binary, nchar and bool
**适用于**：表、超级表。
**Applicable table types**:table, stable
**使用说明**：
**More explanations**:
-从 2.1.3.0 版本开始此函数可用，IRATE 可以在由 GROUP BY 划分出单独时间线的情况下用于超级表（也即 GROUP BY tbname）。
-From 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
...
...
@@ -115,15 +114,15 @@ SELECT IRATE(field_name) FROM tb_name WHERE clause;
SELECT SUM(field_name) FROM tb_name [WHERE clause];
```
**功能说明**：统计表/超级表中某列的和。
**Description**:The sum of a specific column in a table or stable
**返回数据类型**：双精度浮点数 Double 和长整型 INT64。
**Return value type**:Double precision floating number or long integer
**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。
**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;
...
...
@@ -145,15 +144,15 @@ Query OK, 1 row(s) in set (0.000980s)
SELECT STDDEV(field_name) FROM tb_name [WHERE clause];
```
**功能说明**：统计表中某列的均方差。
**Description**:Standard deviation of a specific column in a table or stable
**返回数据类型**：双精度浮点数 Double。
**Return value type**:Double precision floating number
**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。
**Applicable column types**:Data types except for timestamp, binary, nchar and bool
**适用于**：表、超级表（从 2.0.15.1 版本开始）
**Applicable table types**:table, stable (starting from version 2.0.15.1)
**示例**：
**Examples**:
```
taos> SELECT STDDEV(current) FROM d1001;
...
...
@@ -169,15 +168,15 @@ Query OK, 1 row(s) in set (0.000915s)
SELECT LEASTSQUARES(field_name, start_val, step_val) 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 or tags.
**返回数据类型**：同应用的字段。
**Return value type**:Same as the data type of the column being operated
**应用字段**：适合于除时间主列外的任何类型字段。
**Applicable column types**:Data types except for timestamp
**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.
**支持的版本**：2.6.0.0 及以后的版本。
**Applicable version**:From version 2.6.0.0
**示例**：
**Examples**:
```
taos> select voltage from d002;
...
...
@@ -228,17 +227,17 @@ Query OK, 1 row(s) in set (0.019393s)
SELECT HYPERLOGLOG(field_name) FROM { tb_name | stb_name } [WHERE clause];
- 在数据量较少的时候该算法不是很准确，可以使用 select count(data) from (select unique(col) as data from table) 的方法。
**Description**:The cardinal number of a specific column is returned by using hyperloglog algorithm.
**返回结果类型**：整形。
**Return value type**:Integer
**应用字段**：适合于任何类型字段。
**Applicable column types**:Any data type
**支持的版本**：2.6.0.0 及以后的版本。
**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**:From version 2.6.0.0
**Examples**:
```
taos> select dbig from shll;
...
...
@@ -261,9 +260,9 @@ taos> select hyperloglog(dbig) from shll;
When any selective function is used, timestamp column or tag columns including `tbname` can be specified to show that the selected value are from which rows.
### MIN
...
...
@@ -271,15 +270,15 @@ Query OK, 1 row(s) in set (0.008388s)
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
**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。
**Applicable column types**:Data types except for timestamp, binary, nchar and bool
**适用于**：表、超级表。
**Applicable table types**:table, stable
**示例**：
**Examples**:
```
taos> SELECT MIN(current), MIN(voltage) FROM meters;
...
...
@@ -301,15 +300,15 @@ Query OK, 1 row(s) in set (0.000950s)
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
**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。
**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;
...
...
@@ -331,21 +330,21 @@ Query OK, 1 row(s) in set (0.000987s)
SELECT FIRST(field_name) FROM { tb_name | stb_name } [WHERE clause];
```
**功能说明**：统计表/超级表中某列的值最先写入的非 NULL 值。
**Description**:The first non-null value of a specific column in a table or stable
**返回数据类型**：同应用的字段。
**Return value type**:Same as the column being operated
**应用字段**：所有字段。
**Applicable column types**:Any data type
**适用于**：表、超级表。
**Applicable table types**:table, stable
**使用说明**:
**More explanations**:
-如果要返回各个列的首个（时间戳最小）非 NULL 值，可以使用 FIRST(\*)；
-如果结果集中的某列全部为 NULL 值，则该列的返回结果也是 NULL；
-如果结果集中所有列全部为 NULL 值，则不返回结果。
-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
-No result will NOT be returned if all the columns in the result set are all NULL
**示例**：
**Examples**:
```
taos> SELECT FIRST(*) FROM meters;
...
...
@@ -367,22 +366,21 @@ Query OK, 1 row(s) in set (0.001023s)
SELECT LAST(field_name) FROM { tb_name | stb_name } [WHERE clause];
```
**功能说明**：统计表/超级表中某列的值最后写入的非 NULL 值。
**返回数据类型**：同应用的字段。
**Description**:The last non-NULL value of a specific column in a table or stable
**应用字段**：所有字段。
**Return value type**:Same as the column being operated
- 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;
...
...
@@ -404,21 +402,21 @@ Query OK, 1 row(s) in set (0.000843s)
**功能说明**： 统计表/超级表中某列的值最大 _k_ 个非 NULL 值。如果多条数据取值一样，全部取用又会超出 k 条限制时，系统会从相同值中随机选取符合要求的数量返回。
**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
**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。
**Applicable column types**:Data types except for timestamp, binary, nchar and bool
**适用于**：表、超级表。
**Applicable table types**:table, stable
**使用说明**:
**More explanations**:
-*k*值取值范围 1≤*k*≤100；
-系统同时返回该记录关联的时间戳列；
-限制：TOP 函数不支持 FILL 子句。
-_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;
...
...
@@ -443,21 +441,21 @@ Query OK, 2 row(s) in set (0.000810s)
**功能说明**：统计表/超级表中某列的值最小 _k_ 个非 NULL 值。如果多条数据取值一样，全部取用又会超出 k 条限制时，系统会从相同值中随机选取符合要求的数量返回。
**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
**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。
**Applicable column types**: Data types except for timestamp, binary, nchar and bool
**适用于**：表、超级表。
**Applicable table types**: table, stable
**使用说明**:
**More explanations**:
-*k*值取值范围 1≤*k*≤100；
-系统同时返回该记录关联的时间戳列；
-限制：BOTTOM 函数不支持 FILL 子句。
-_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 BOTTOM(voltage, 2) FROM meters;
...
...
@@ -481,17 +479,17 @@ Query OK, 2 row(s) in set (0.000793s)
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.
**返回数据类型**： 双精度浮点数 Double。
**Return value type**: Double precision floating point
**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。
**Applicable column types**: Data types except for timestamp, binary, nchar and bool
**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.
-**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;
...
...
@@ -551,20 +548,20 @@ Query OK, 1 row(s) in set (0.011639s)
SELECT LAST_ROW(field_name) FROM { tb_name | stb_name };
```
**功能说明**：返回表/超级表的最后一条记录。
**Description**: The last row of a table or stable
**返回数据类型**：同应用的字段。
**Return value type**: Same as the column being operated
-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.
-`INTERP` is used to get the value that matches the specified time slice from a column. If no such value exists an interpolation value will be returned based on `FILL` parameter.
- The input data of `INTERP` is the value of the specified column, `where` can be used to filter the original data. If no `where` condition is specified then all original data is the input.
- The output time range of `INTERP` is specified by `RANGE(timestamp1,timestamp2)` parameter, with timestamp1<=timestamp2. timestamp1 is the starting point of the output time range and must be specified. timestamp2 is the ending point of the output time range and must be specified. If `RANGE` is not specified, then the timestamp of the first row that matches the filter condition is treated as timestamp1, the timestamp of the last row that matches the filter condition is treated as timestamp2.
- The number of rows in the result set of `INTERP` is determined by the parameter `EVERY`. Starting from timestamp1, one interpolation is performed for every time interval specified `EVERY` parameter. If `EVERY` parameter is not used, the time windows will be considered as no ending timestamp, i.e. there is only one time window from timestamp1.
- Interpolation is performed based on `FILL` parameter. No interpolation is performed if `FILL` is not used, that means either the original data that matches is returned or nothing is returned.
-`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..
- INTERP 用于在指定时间断面获取指定列的记录值，如果该时间断面不存在符合条件的行数据，那么会根据 FILL 参数的设定进行插值。
- 单个 INTERP 函数查询只能够针对一个时间点进行查询，如果需要返回等时间间隔的断面数据，可以通过 INTERP 配合 EVERY 的方式来进行查询处理（而不是使用 INTERVAL），其含义是每隔固定长度的时间进行插值
**More explanations**:
**示例**：
- It can be used from version 2.0.15.0
- 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**:
```
taos> SELECT INTERP(*) FROM meters WHERE ts='2017-7-14 18:40:00.004';
...
...
@@ -668,7 +663,7 @@ SELECT INTERP(field_name) FROM { tb_name | stb_name } WHERE ts='timestamp' [FILL
If there is not any data corresponding to the specified timestamp, an interpolation value is returned if interpolation policy is specified by `FILL` parameter; or nothing is returned\
```
taos> SELECT INTERP(*) FROM meters WHERE tbname IN ('d636') AND ts='2017-7-14 18:40:00.005';
...
...
@@ -681,7 +676,7 @@ SELECT INTERP(field_name) FROM { tb_name | stb_name } WHERE ts='timestamp' [FILL
Interpolation is performed every 5 milliseconds between `['2017-7-14 18:40:00', '2017-7-14 18:40:00.014']`
```
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);
...
...
@@ -698,17 +693,17 @@ SELECT INTERP(field_name) FROM { tb_name | stb_name } WHERE ts='timestamp' [FILL
SELECT TAIL(field_name, k, offset_val) FROM {tb_name | stb_name} [WHERE clause];
```
**功能说明**：返回跳过最后 offset_value 个，然后取连续 k 个记录，不忽略 NULL 值。offset_val 可以不输入。此时返回最后的 k 个记录。当有 offset_val 输入的情况下，该函数功能等效于 `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`.
**参数范围**：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
**应用字段**：适合于除时间主列外的任何类型字段。
**Applicable column types**: Any data type except form timestamp, i.e. the primary key
**支持版本**：2.6.0.0 及之后的版本。
**Applicable versions**: From version 2.6.0.0
**示例**：
**Examples**:
```
taos> select ts,dbig from tail2;
...
...
@@ -736,20 +731,20 @@ Query OK, 2 row(s) in set (0.002307s)
SELECT UNIQUE(field_name) FROM {tb_name | stb_name} [WHERE clause];
**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
**应用字段**：适合于除时间类型以外的字段。
**Applicable column types**: Any data types except for timestamp
-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.
**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
**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。
**Applicable column types**: Data types except for timestamp, binary, nchar and bool
**适用于**：表、超级表。
**Applicable table types**: table, stable
**使用说明**:
**More explanations**:
-输出结果行数是范围内总行数减一，第一行没有结果输出。
-从 2.1.3.0 版本开始，DIFF 函数可以在由 GROUP BY 划分出单独时间线的情况下用于超级表（也即 GROUP BY tbname）。
-从 2.6.0 开始，DIFF 函数支持 ignore_negative 参数
-The number of result rows is the number of rows subtracted by one, no output for the first row
-From version 2.1.30, `DIFF` can be used on stable with `GROUP by tbname`
-From version 2.6.0, `ignore_negative` parameter is supported
**示例**：
**Examples**:
```sql
taos>SELECTDIFF(current)FROMd1001;
ts|diff(current)|
=================================================
2018-10-0314:38:15.000|2.30000|
2018-10-0314:38:16.800|-0.30000|
QueryOK,2row(s)inset(0.001162s)
```
```sql
taos>SELECTDIFF(current)FROMd1001;
ts|diff(current)|
=================================================
2018-10-0314:38:15.000|2.30000|
2018-10-0314:38:16.800|-0.30000|
QueryOK,2row(s)inset(0.001162s)
```
### DERIVATIVE
...
...
@@ -815,20 +810,20 @@ Query OK, 5 row(s) in set (0.108458s)
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
**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。
**Applicable column types**: Data types except for timestamp, binary, nchar and bool
**适用于**：表、超级表
**Applicable table types**: table, stable
**使用说明**:
**More explanations**:
-从 2.1.3.0 及以后版本可用；输出结果行数是范围内总行数减一，第一行没有结果输出。
-DERIVATIVE 函数可以在由 GROUP BY 划分出单独时间线的情况下用于超级表（也即 GROUP BY tbname）。
-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;
...
...
@@ -848,17 +843,17 @@ Query OK, 5 row(s) in set (0.004883s)
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
**应用字段**：不能应用在 binary、nchar、bool 类型字段。
**Applicable column types**: Data types except for binary, nchar, and bool
**适用于**：表、超级表。
**Applicable table types**: table, stable
**使用说明**：可用于 TIMESTAMP 字段，此时表示记录的时间覆盖范围。
**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;
...
...
@@ -880,20 +875,21 @@ Query OK, 1 row(s) in set (0.000836s)
SELECT CEIL(field_name) FROM { tb_name | stb_name } [WHERE clause];
```
**功能说明**：获得指定列的向上取整数的结果。
**Description**: The round up value of a specific column
**功能说明**： 计算连续 k 个值的移动平均数（moving average）。如果输入行数小于 k，则无结果输出。参数 k 的合法输入范围是 1≤ k ≤ 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 is _k_ is [1,1000].
**Return value type**: Double precision floating point
**返回结果类型**： 返回双精度浮点数类型。
**Applicable data types**: Data types except for timestamp, binary, nchar, and bool
**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.
**功能说明**：数据类型转换函数，输入参数 expression 支持普通列、常量、标量函数及它们之间的四则运算，不支持 tag 列，只适用于 select 子句中。
**Return value type**: The type specified by parameter `type_name`
**返回结果类型**：CAST 中指定的类型（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
-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]
```
```
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
**返回结果类型**：INT。
**Applicable nested query**: Inner query and Outer query
**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。
**Applicable versions**: From 2.6.0.0
**使用说明**
**More explanations**
- 如果输入值为NULL，输出值为NULL。
- 该函数可以应用在普通表和超级表上。
- 函数适用于内层查询和外层查询。
- 版本2.6.0.x后支持
- 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]
```
```
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
**返回结果类型**：INT。
**Applicable table types**: table, stable
**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。
**Applicable nested query**: Inner query and Outer query
**使用说明**
**Applicable versions**: From 2.6.0.0
- 如果输入值为NULL，输出值为NULL。
- 该函数可以应用在普通表和超级表上。
- 该函数适用于内层查询和外层查询。
- 版本2.6.0.x后支持
**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]
```
```
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
**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。
**Applicable nested query**: Inner query and Outer query
**使用说明**：
**Applicable versions**: From 2.6.0.0
- 如果输入值为NULL，输出值为NULL。
- 该函数可以应用在普通表和超级表上。
- 该函数适用于内层查询和外层查询。
- 版本2.6.0.x后支持
**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]
```
```
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
**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。
**Applicable nested query**: Inner query and Outer query
**使用说明**：
**Applicable versions**: From 2.6.0.0
- 如果输入值为NULL，输出值为NULL。
- 该函数可以应用在普通表和超级表上。
- 该函数适用于内层查询和外层查询。
- 版本2.6.0.x后支持
**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]
```
```
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
**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。
**Applicable table types**: table, stable
**使用说明**：
**Applicable nested query**: Inner query and Outer query
- 如果输入值为NULL，输出值为NULL。
- 该函数可以应用在普通表和超级表上。
- 该函数适用于内层查询和外层查询。
- 版本2.6.0.x后支持
**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]
```
```
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
**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。
**Applicable versions**: From 2.6.0.0
**使用说明**：
**More explanations**
- 如果输入值为NULL，输出值为NULL。
- 该函数可以应用在普通表和超级表上。
- 该函数适用于内层查询和外层查询。
- 版本2.6.0.x后支持
- If the input value is NULL, the output is NULL too
### SUBSTR
```
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`
**功能说明**：从源字符串 str 中的指定位置 pos 开始取一个长度为 len 的子串并返回。
**Return value type**: Same as input
**返回结果类型**：同输入类型。
**Applicable data types**: BINARY or NCHAR, can't be used on tags
**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。
**Applicable table types**: table, stable
**使用说明**：
**Applicable nested query**: Inner query and Outer query
- 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.
**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.
**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
**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.
- 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
- val ： Numeric types
- unit: The unit of time interval, can be [1s, 1m, 1h], default is 1s
Aggregate by time window is supported in TDengine. For example, each temperature sensor reports the temperature every second, the average temperature every 10 minutes can be retrieved by query with time window.
Window related clauses are used to divide the data set to be queried into subsets and then aggregate. There are three kinds of windows, time window, status window, and session window. There are two kinds of time windows, sliding window and flip time window.
`INTERVAL` claused is used to generate time windows of same time interval, `SLIDING` is used to specify the time step for which the time window moves forward. The query is performed on one time window each time, and the time window moves forward with time. When defining continuous query both the size of time window and the step of forward sliding time need to be specified. As shown in the figure blow, [t0s, t0e] ，[t1s , t1e]， [t2s, t2e] are respectively the time range of three time windows on which continuous queries are executed. The time step for which time window moves forward is marked by `sliding time`. Query, filter and aggregate operations are executed on each time window respectively. When the time step specified by `SLIDING` is same as the time interval specified by `INTERVAL`, the sliding time window is actually a flip time window.
`INTERVAL` and `SLIDING` should be used with aggregate functions and selection functions. Below SQL statement is illegal because no aggregate or selection function is used with `INTERVAL`.
```
SELECT * FROM temp_tb_1 INTERVAL(1m);
```
SLIDING 的向前滑动的时间不能超过一个窗口的时间范围。以下语句非法：
The time step specified by `SLIDING` can't exceed the time interval specified by `INTERVAL`. Below SQL statement is illegal because the time length specified by `SLIDING` exceeds that specified by `INTERVAL`.
```
SELECT COUNT(*) FROM temp_tb_1 INTERVAL(1m) SLIDING(2m);
When the time length specified by `SLIDING` is same as that specified by `INTERVAL`, sliding window is actually flip window. The minimum time range specified by `INTERVAL` is 10 milliseconds (10a) prior to version 2.1.5.0. From version 2.1.5.0, the minimum time range by `INTERVAL` can be 1 microsecond (1u). However, if the DB precision is millisecond, the minimum time range is 1 millisecond (1a). Please be noted that the `timezone` parameter should be configured to same value in the `taos.cfg` configuration file on client side and server side.
In case of using integer, bool, or string to represent the device status at a moment, the continuous rows with same status belong to same status window. Once the status changes, the status window closes. As shown in the following figure，there are two status windows according to status, [2019-04-28 14:22:07，2019-04-28 14:22:10] and [2019-04-28 14:22:11，2019-04-28 14:22:12]. Status window is not applicable to stable for now.
使用 STATE_WINDOW 来确定状态窗口划分的列。例如：
`STATE_WINDOW` is used to specify the column based on which to define status window, for example：
```
SELECT COUNT(*), FIRST(ts), status FROM temp_tb_1 STATE_WINDOW(status);
The primary key, i.e. timestamp, is used to determine which session window the row belongs to. If the time interval between two adjacent rows is within the time range specified by `tol_val`, they belong to same session window; otherwise they belong to two different time windows. As shown in the figure below, if the limit of time interval for session window is specified as 12 seconds, then the 6 rows in the figure constitutes 2 time windows, [2019-04-28 14:22:10，2019-04-28 14:22:30] and [2019-04-28 14:23:10，2019-04-28 14:23:30], because the time difference between 2019-04-28 14:22:30 and 2019-04-28 14:23:10 is 40 seconds, which exceeds the time interval limit of 12 seconds.
If the time interval between two continuous rows are withint the time interval specified by `tol_value` they belong to the same session window; otherwise a new session window is started automatically. Session window is not supported on stable for now.
SELECT COUNT(*), FIRST(ts) FROM temp_tb_1 SESSION(ts, tol_val);
```
## More On Window Aggregate
这种类型的查询语法如下：
### Syntax
```
The full syntax of aggregate by window is as following:
```sql
SELECTfunction_listFROMtb_name
[WHEREwhere_condition]
[SESSION(ts_col,tol_val)]
...
...
@@ -71,39 +71,38 @@ SELECT function_list FROM stb_name
2. VALUE 填充：固定值填充，此时需要指定填充的数值。例如：FILL(VALUE, 1.23)。
3. PREV 填充：使用前一个非 NULL 值填充数据。例如：FILL(PREV)。
4. NULL 填充：使用 NULL 填充数据。例如：FILL(NULL)。
5. LINEAR 填充：根据前后距离最近的非 NULL 值做线性插值填充。例如：FILL(LINEAR)。
6. NEXT 填充：使用下一个非 NULL 值填充数据。例如：FILL(NEXT)。
- Aggregate functions and selection functions can be used in `function_list`, with each function having only one output, for example COUNT, AVG, SUM, STDDEV, LEASTSQUARES, PERCENTILE, MIN, MAX, FIRST, LAST. Functions having multiple ouput can't be used, for example DIFF or arithmetic operations.
-`LAST_ROW` can't be used together with window aggregate.
- Scalar functions, like CEIL/FLOOR, can't be used with window aggregate.
-`WHERE` clause can be used to specify the starting and ending time and other filter conditions
-`FILL` clause is used to specify how to fill when there is data missing in any window, including: \
1. NONE: No fill (the default fill mode)
2. VALUE：Fill with a fixed value, which should be specified together, for example `FILL(VALUE, 1.23)`
3. PREV：Fill with the previous non-NULL value, `FILL(PREV)`
4. NULL：Fill with NULL, `FILL(NULL)`
5. LINEAR：Fill with the closest non-NULL value, `FILL(LINEAR)`
6. NEXT：Fill with the next non-NULL value, `FILL(NEXT)`
:::info
1. 使用 FILL 语句的时候可能生成大量的填充输出，务必指定查询的时间区间。针对每次查询，系统可返回不超过 1 千万条具有插值的结果。
2. 在时间维度聚合中，返回的结果中时间序列严格单调递增。
3. 如果查询对象是超级表，则聚合函数会作用于该超级表下满足值过滤条件的所有表的数据。如果查询中没有使用 GROUP BY 语句，则返回的结果按照时间序列严格单调递增；如果查询中使用了 GROUP BY 语句分组，则返回结果中每个 GROUP 内不按照时间序列严格单调递增。
1. Huge volume of interpolation output may be returned using `FILL`, so it's recommended to specify the time range when using `FILL`. The maximum interpolation values that can be returned in single query is 10,000,000.
2. The result set is in the ascending order of timestamp in aggregate by time window aggregate.
3. If aggregate by window is used on stable, the aggregate function is performed on all the rows matching the filter conditions. If `GROUP BY` is not used in the query, the result set will be returned in ascending order of timestamp; otherwise the result set is not exactly in the order of ascending timestamp in each group.
:::
:::
Aggregate by time window is also used in continuous query, please refer to [Continuous Query](/develop/continuous-query).
The average current, maximum current and median of current in every 10 minutes of the past 24 hours can be calculated using below SQL statement, with missing value filled with the previous non-NULL value.
```
SELECT AVG(current), MAX(current), APERCENTILE(current, 50) FROM meters
1. Only English characters, digits and underscore are allowed
2. Can't be started with digits
3. Case Insensitive without escape character "\`"
4. Identifier with escape character "\`"
To support more flexible table or column names, a new escape character "\`" is introduced. For more details please refer to [escape](/taos-sql/escape).
## GROUP BY 的限制
## Password Rule
TAOS SQL 支持对标签、TBNAME 进行 GROUP BY 操作，也支持普通列进行 GROUP BY，前提是：仅限一列且该列的唯一值小于 10 万个。注意：group by 不支持 float,double 类型。
The legal character set is `[a-zA-Z0-9!?$%^&*()_–+={[}]:;@~#|<,>.?/]`.
## IS NOT NULL 的限制
## General Limits
IS NOT NULL 与不为空的表达式适用范围。
- Maximum length of database name is 32 bytes
- Maximum length of table name is 192 bytes, excluding the database name prefix and the separator
- Maximum length of each data row is 48K bytes from version 2.1.7.0 , before which the limit is 16K bytes. Please be noted that the upper limit includes the extra 2 bytes consumed by each column of BINARY/NCHAR type.
- Maximum of column name is 64.
- Maximum number of columns is 4096. There must be at least 2 columns, and the first column must be timestamp.
- Maximum length of tag name is 64.
- Maximum number of tags is 128. There must be at least 1 tag. The total length of tag values should not exceed 16K bytes.
- Maximum length of singe SQL statement is 1048576, i.e. 1 MB bytes. It can be configured in the parameter `maxSQLLength` in the client side, the applicable range is [65480, 1048576].
- At most 4096 columns (or 1024 prior to 2.1.7.0) can be returned by `SELECT`, functions in the query statement may constitute columns. Error will be returned if the limit is exceeded.
- Maximum numbers of databases, stables, tables are only depending on the system resources.
- Maximum of database name is 32 bytes, can't include "." and special characters.
- Maximum replica number of database is 3
- Maximum length of user name is 23 bytes
- Maximum length of password is 15 bytes
- Maximum number of rows depends on the storage space only.
- Maximum number of tables depends on the number of nodes only.
- Maximum number of databases depends on the number of nodes only.
- Maximum number of vnodes for single database is 64.
IS NOT NULL 支持所有类型的列。不为空的表达式为 <\>""，仅对非数值类型的列适用。
## Restrictions of `GROUP BY`
## ORDER BY 的限制
`GROUP BY` can be performed on tags and `TBNAME`. It can be performed on data columns too, with one restriction that only one column and the number of unique values on that column is lower than 100,000. Please be noted that `GROUP BY` can't be performed on float or double type.
- 非超级表只能有一个 order by.
- 超级表最多两个 order by， 并且第二个必须为 ts.
- order by tag，必须和 group by tag 一起，并且是同一个 tag。 tbname 和 tag 一样逻辑。 只适用于超级表
- order by 普通列，必须和 group by 一起或者和 top/bottom 一起，并且是同一个普通列。 适用于超级表和普通表。如果同时存在 group by 和 top/bottom 一起，order by 优先必须和 group by 同一列。
- order by ts. 适用于超级表和普通表。
- order by ts 同时含有 group by 时 针对 group 内部用 ts 排序
## Restrictions of `IS NOT NULL`
## 表(列)名合法性说明
`IS NOT NULL` can be used on any data type of columns. The non-empty string evaluation expression, i.e. `<\>""` can only be used on non-numeric data types.
The name of a table or column can only be composed of ASCII characters, digits and underscore, while digit can't be used as the beginning. The maximum length is 192 bytes. Names are case insensitive. The name mentioned in this rule doesn't include the database name prefix and the separator.
### Name Restrictions After Escaping
To support more flexible table or column names, new escape character "`" is introduced in TDengine to avoid the conflict between table name and keywords and break the above restrictions for table name. The escape character is not counted in the length of table name.
With escaping, the string inside escape characters are case sensitive, i.e. will not be converted to lower case internally.
For example:
\`aBc\` and \`abc\` are different table or column names, but "abc" and "aBc" are same names because internally they are all "abc".
:::note
转义字符中的内容必须是可打印字符。
The characters inside escape characters must be printable characters.
:::
### 支持版本
支持转义符的功能从 2.3.0.1 版本开始。
\ No newline at end of file
### Applicable Versions
Escape character "\`" is available from version 2.3.0.1.
2. 对于%和\_，因为在 like 里这两个字符是通配符，所以在模式匹配 like 里用`\%`%和`\_`表示字符里本身的%和\_，如果在 like 模式匹配上下文之外使用`\%`或`\_`，则它们的计算结果为字符串`\%`和`\_`，而不是%和\_。
1.If there are escape characters in identifiers (database name, table name, column name)
- Identifier without ``: Error will be returned because identifier must be constituted of digits, ASCII characters or underscore and can't be started with digits
- Identifier quoted with ``： Original content is kept, no escaping
2.If there are escape characters in values
- The escape characters will be escaped as the above table. If the escape character doesn't match any supported one, the escape character "\" will be ignored.
- "%" and "\_" are used as wildcards in `like`. `\%` and `\_` should be used to represent literal "%" and "\_" in `like`,. If `\%` and `\_` are used out of `like` context, the evaluation result is "`\%`"and "`\_`", instead of "%" and "\_".
There are about 200 keywords reserved by TDengine, they can't be used as the name of database, stable or table with either upper case, lower case or mixed case.
This document explains the syntax, select, functions and some tips that can be used in TAOS SQL. It would be easier to understand with some fundamental knowledge of SQL.
TAOS SQL is the major interface for users to write data into or query from TDengine. For users to easily use, syntax similar to standard SQL is provided. However, please be noted that TAOS SQL is not standard SQL. Besides, because TDengine doesn't provide the functionality of deleting time series data, corresponding statements are not provided in TAOS SQL.
TAOS SQL 不支持关键字的缩写，例如 DESCRIBE 不能缩写为 DESC。
TAOS SQL doesn't support abbreviation for keywords, for example `DESCRIBE` can't be abbreviated as `DESC`.
本章节 SQL 语法遵循如下约定：
Syntax Specifications used in this chapter:
-<\> 里的内容是用户需要输入的，但不要输入 <\> 本身
-\[\]表示内容为可选项，但不能输入 [] 本身
- | 表示多选一，选择其中一个即可，但不能输入 | 本身
- … 表示前面的项可重复多个
-The content inside <\> needs to be input by the user, excluding <\> itself.
-\[\]means optional input, excluding [] itself.
- | means one of a few options, excluding | itself.
- … means the item prior to it can be repeated multiple times.
To better demonstrate the syntax, usage and rules of TAOS SQL, hereinafter it's assumed that there is a data set of meters. Assuming each meter collects 3 data: current, voltage, phase. The data model is as below:
The data set includes the data collected by 4 meters, the corresponding table name is d1001, d1002, d1003, d1004 respectively based on the data model of TDengine.
