Skip to content

T
TDengine

taosdata / TDengine
大约 2 年 前同步成功

通知 1192
Star 22018
Fork 4786
T
TDengine
“f94bfbaef02b7767c668192d73411838e87122fe”上不存在“tests/pytest/query/queryGroupbyWithInterval.py”
未验证 提交 6e3b25d2 编写于 作者: W wade zhang 提交者： GitHub
浏览文件
操作

Merge pull request #12194 from taosdata/docs/TD-15336 

docs: English version of SQL reference guide
上级 2ab429ee 1a728725
显示空白变更内容
内联 并排
Showing with 1222 addition and 1067 deletion
docs-en/12-taos-sql/01-data-type.md
浏览文件 @ 6e3b25d2
--- ---
sidebar_label: 支持的数据类型 sidebar_label: Data Types
title: 支持的数据类型 title: Data Types
description: "TDengine 支持的数据类型: 时间戳、浮点型、JSON 类型等" description: "The data types supported by TDengine include timestamp, float, JSON, etc"
--- ---
使用 TDengine，最重要的是时间戳。创建并插入记录、查询历史记录的时候，均需要指定时间戳。时间戳有如下规则： When using TDengine to store and query data, the most important part of the data is timestamp. Timestamp must be specified when creating and inserting data rows or querying data, timestamp must follow below rules:
- 时间格式为 `YYYY-MM-DD HH:mm:ss.MS`，默认时间分辨率为毫秒。比如：`2017-08-12 18:25:58.128` - the format must be `YYYY-MM-DD HH:mm:ss.MS`, the default time precision is millisecond (ms), for example `2017-08-12 18:25:58.128`
- 内部函数 now 是客户端的当前时间 - internal function `now` can be used to get the current timestamp of the client side
- 插入记录时，如果时间戳为 now，插入数据时使用提交这条记录的客户端的当前时间 - the current timestamp of the client side is applied when `now` is used to insert data
- Epoch Time：时间戳也可以是一个长整数，表示从格林威治时间 1970-01-01 00:00:00.000 (UTC/GMT) 开始的毫秒数（相应地，如果所在 Database 的时间精度设置为“微秒”，则长整型格式的时间戳含义也就对应于从格林威治时间 1970-01-01 00:00:00.000 (UTC/GMT) 开始的微秒数；纳秒精度逻辑类似。） - Epoch Time：timestamp can also be a long integer number, which means the number of seconds, milliseconds or nanoseconds, depending on the time precision, from 1970-01-01 00:00:00.000 (UTC/GMT)
- 时间可以加减，比如 now-2h，表明查询时刻向前推 2 个小时（最近 2 小时）。数字后面的时间单位可以是 b(纳秒)、u(微秒)、a(毫秒)、s(秒)、m(分)、h(小时)、d(天)、w(周)。 比如 `select * from t1 where ts > now-2w and ts <= now-1w`，表示查询两周前整整一周的数据。在指定降采样操作（down sampling）的时间窗口（interval）时，时间单位还可以使用 n (自然月) 和 y (自然年)。 - timestamp can be applied with add/substract operation, for example `now-2h` means 2 hours back from the time at which query is executed，the unit can be b(nanosecond), u(microsecond), a(millisecond), s(second), m(minute), h(hour), d(day), w(week.。 So `select * from t1 where ts > now-2w and ts <= now-1w` means the data between two weeks ago and one week ago. The time unit can also be n (calendar month) or y (calendar year) when specifying the time window for down sampling operation.
TDengine 缺省的时间戳精度是毫秒，但通过在 `CREATE DATABASE` 时传递的 PRECISION 参数也可以支持微秒和纳秒。（从 2.1.5.0 版本开始支持纳秒精度） Time precision in TDengine can be set by the `PRECISION` parameter when executing `CREATE DATABASE`, like below, the default time precision is millisecond.
```sql ```sql
CREATE DATABASE db_name PRECISION 'ns'; CREATE DATABASE db_name PRECISION 'ns';
``` ```
在 TDengine 中，普通表的数据模型中可使用以下 10 种数据类型。 In TDengine, below data types can be used when specifying a column or tag.
| # | **类型** | **Bytes** | **说明** | | # | **类型** | **Bytes** | **说明** |
| --- | :-------: | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | --- | :-------: | --------- | ------------------------- |
| 1 | TIMESTAMP | 8 | 时间戳。缺省精度毫秒，可支持微秒和纳秒。从格林威治时间 1970-01-01 00:00:00.000 (UTC/GMT) 开始，计时不能早于该时间。（从 2.0.18.0 版本开始，已经去除了这一时间范围限制）（从 2.1.5.0 版本开始支持纳秒精度） | | 1 | TIMESTAMP | 8 | Default precision is millisecond, microsecond and nanosecond are also supported |
| 2 | INT | 4 | 整型，范围 [-2^31+1, 2^31-1], -2^31 用作 NULL | | 2 | INT | 4 | Integer, the value range is [-2^31+1, 2^31-1], while -2^31 is treated as NULL |
| 3 | BIGINT | 8 | 长整型，范围 [-2^63+1, 2^63-1], -2^63 用作 NULL | | 3 | BIGINT | 8 | Long integer, the value range is [-2^63+1, 2^63-1], while -2^63 is treated as NULL |
| 4 | FLOAT | 4 | 浮点型，有效位数 6-7，范围 [-3.4E38, 3.4E38] | | 4 | FLOAT | 4 | Floating point number, the effective number of digits is 6-7, the value range is [-3.4E38, 3.4E38] |
| 5 | DOUBLE | 8 | 双精度浮点型，有效位数 15-16，范围 [-1.7E308, 1.7E308] | | 5 | DOUBLE | 8 | double precision floating point number, the effective number of digits is 15-16, the value range is [-1.7E308, 1.7E308] |
| 6 | BINARY | 自定义 | 记录单字节字符串，建议只用于处理 ASCII 可见字符，中文等多字节字符需使用 nchar。理论上，最长可以有 16374 字节。binary 仅支持字符串输入，字符串两端需使用单引号引用。使用时须指定大小，如 binary(20) 定义了最长为 20 个单字节字符的字符串，每个字符占 1 byte 的存储空间，总共固定占用 20 bytes 的空间，此时如果用户字符串超出 20 字节将会报错。对于字符串内的单引号，可以用转义字符反斜线加单引号来表示，即 `\’`。 | | 6 | BINARY | User Defined | Single-byte string for ASCII visible characters. Length must be specified when defining a column or tag of binary type. The string length can be up to 16374 bytes. The string value must be quoted with single quotes. The literal single quote inside the string must be preceded with back slash like `\'` |
| 7 | SMALLINT | 2 | 短整型， 范围 [-32767, 32767], -32768 用作 NULL | | 7 | SMALLINT | 2 | Short integer, the value range is [-32767, 32767], while -32768 is treated as NULL |
| 8 | TINYINT | 1 | 单字节整型，范围 [-127, 127], -128 用作 NULL | | 8 | TINYINT | 1 | Single-byte integer, the value range is [-127, 127], while -128 is treated as NLLL |
| 9 | BOOL | 1 | 布尔型，{true, false} | | 9 | BOOL | 1 | Bool, the value range is {true, false} |
| 10 | NCHAR | 自定义 | 记录包含多字节字符在内的字符串，如中文字符。每个 nchar 字符占用 4 bytes 的存储空间。字符串两端使用单引号引用，字符串内的单引号需用转义字符 `\’`。nchar 使用时须指定字符串大小，类型为 nchar(10) 的列表示此列的字符串最多存储 10 个 nchar 字符，会固定占用 40 bytes 的空间。如果用户字符串长度超出声明长度，将会报错。 | | 10 | NCHAR | User Defined| Multiple-Byte string that can include like Chinese characters. Each character of NCHAR type consumes 4 bytes storage. The string value should be quoted with single quotes. Literal single quote inside the string must be preceded with backslash, like `\’`. The length must be specified when defining a column or tag of NCHAR type, for example nchar(10) means it can store at most 10 characters of nchar type and will consume fixed storage of 40 bytes. Error will be reported the string value exceeds the length defined. |
| 11 | JSON | | json 数据类型， 只有 tag 可以是 json 格式 | | 11 | JSON | | json type can only be used on tag, a tag of json type is excluded with any other tags of any other type |
:::tip :::tip
TDengine 对 SQL 语句中的英文字符不区分大小写，自动转化为小写执行。因此用户大小写敏感的字符串及密码，需要使用单引号将字符串引起来。 TDengine is case insensitive and treats any characters in the sql command as lower case by default, case sensitive strings must be quoted with single quotes.
::: :::
:::note :::note
虽然 BINARY 类型在底层存储上支持字节型的二进制字符，但不同编程语言对二进制数据的处理方式并不保证一致，因此建议在 BINARY 类型中只存储 ASCII 可见字符，而避免存储不可见字符。多字节的数据，例如中文字符，则需要使用 NCHAR 类型进行保存。如果强行使用 BINARY 类型保存中文字符，虽然有时也能正常读写，但并不带有字符集信息，很容易出现数据乱码甚至数据损坏等情况。 Only ASCII visible characters are suggested to be used in a column or tag of BINARY type. Multiple-byte characters must be stored in NCHAR type.
::: :::
:::note :::note
SQL 语句中的数值类型将依据是否存在小数点，或使用科学计数法表示，来判断数值类型是否为整型或者浮点型，因此在使用时要注意相应类型越界的情况。例如，9999999999999999999 会认为超过长整型的上边界而溢出，而 9999999999999999999.0 会被认为是有效的浮点数。 Numeric values in SQL statements will be determined as integer or float type according to whether there is decimal point or whether scientific notation is used, so attention must be paid to avoid overflow. For example, 9999999999999999999 will be considered as overflow because it exceeds the upper limit of long integer, but 9999999999999999999.0 will be considered as a legal float number.
::: :::
docs-en/12-taos-sql/02-database.md
浏览文件 @ 6e3b25d2
--- ---
sidebar_label: 数据库管理 sidebar_label: Database
title: 数据库管理 title: Database
description: "创建、删除数据库，查看、修改数据库参数" description: "create and drop database, show or change database parameters"
--- ---
## 创建数据库 ## Create Datable
``` ```
CREATE DATABASE [IF NOT EXISTS] db_name [KEEP keep] [DAYS days] [UPDATE 1]; CREATE DATABASE [IF NOT EXISTS] db_name [KEEP keep] [DAYS days] [UPDATE 1];
``` ```
:::info :::info
1. KEEP 是该数据库的数据保留多长天数，缺省是 3650 天(10 年)，数据库会自动删除超过时限的数据；<!-- REPLACE_OPEN_TO_ENTERPRISE__KEEP_PARAM_DESCRIPTION -->
2. UPDATE 标志数据库支持更新相同时间戳数据；（从 2.1.7.0 版本开始此参数支持设为 2，表示允许部分列更新，也即更新数据行时未被设置的列会保留原值。）（从 2.0.8.0 版本开始支持此参数。注意此参数不能通过 `ALTER DATABASE` 指令进行修改。） 1. KEEP specifies the number of days for which the data in the database to be created will be kept, the default value is 3650 days, i.e. 10 years. The data will be deleted automatically once its age exceeds this threshold.
1. UPDATE 设为 0 时，表示不允许更新数据，后发送的相同时间戳的数据会被直接丢弃； 2. UPDATE specifies whether the data can be updated and how the data can be updated.
2. UPDATE 设为 1 时，表示更新全部列数据，即如果更新一个数据行，其中某些列没有提供取值，那么这些列会被设为 NULL； 1. UPDATE set to 0 means update operation is not allowed, the data with an existing timestamp will be dropped silently.
3. UPDATE 设为 2 时，表示支持更新部分列数据，即如果更新一个数据行，其中某些列没有提供取值，那么这些列会保持原有数据行中的对应值； 2. UPDATE set to 1 means the whole row will be updated, the columns for which no value is specified will be set to NULL
4. 更多关于 UPDATE 参数的用法，请参考[FAQ](/train-faq/faq)。 3. UPDATE set to 2 means updating a part of columns for a row is allowed, the columns for which no value is specified will be kept as no change
3. 数据库名最大长度为 33； 3. The maximum length of database name is 33 bytes.
4. 一条 SQL 语句的最大长度为 65480 个字符； 4. The maximum length of a SQL statement is 65,480 bytes.
5. 数据库还有更多与数据库相关的配置参数，如 cache, blocks, days, keep, minRows, maxRows, wal, fsync, update, cacheLast, replica, quorum, maxVgroupsPerDb, ctime, comp, prec, 具体细节请参见 [配置参数](/reference/config/) 章节。 5. For more parameters that can be used when creating a database, like cache, blocks, days, keep, minRows, maxRows, wal, fsync, update, cacheLast, replica, quorum, maxVgroupsPerDb, ctime, comp, prec, Please refer to [Configuration Parameters](/reference/config/).
::: :::
## 显示系统当前参数 ## Show Current Configuration
``` ```
SHOW VARIABLES; SHOW VARIABLES;
``` ```
## 使用数据库 ## Specify The Database In Use
``` ```
USE db_name; USE db_name;
``` ```
使用/切换数据库（在 REST 连接方式下无效）。 :::note
This way is not applicable when using a REST connection
:::
## 删除数据库 ## Drop Database
``` ```
DROP DATABASE [IF EXISTS] db_name; DROP DATABASE [IF EXISTS] db_name;
``` ```
删除数据库。指定 Database 所包含的全部数据表将被删除，谨慎使用！ :::note
All data in the database will be deleted too. This command must be used with caution.
:::
## 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/).
``` ```
ALTER DATABASE db_name COMP 2; ALTER DATABASE db_name COMP 2;
``` ```
COMP 参数是指修改数据库文件压缩标志位，缺省值为 2，取值范围为 [0, 2]。0 表示不压缩，1 表示一阶段压缩，2 表示两阶段压缩。 COMP parameter specifies whether the data is compressed and how the data is compressed.
``` ```
ALTER DATABASE db_name REPLICA 2; ALTER DATABASE db_name REPLICA 2;
``` ```
REPLICA 参数是指修改数据库副本数，取值范围 [1, 3]。在集群中使用，副本数必须小于或等于 DNODE 的数目。 REPLICA parameter specifies the number of replications of the database.
``` ```
ALTER DATABASE db_name KEEP 365; ALTER DATABASE db_name KEEP 365;
``` ```
KEEP 参数是指修改数据文件保存的天数，缺省值为 3650，取值范围 [days, 365000]，必须大于或等于 days 参数值。 KEEP parameter specifies the number of days for which the data will be kept.
``` ```
ALTER DATABASE db_name QUORUM 2; ALTER DATABASE db_name QUORUM 2;
``` ```
QUORUM 参数是指数据写入成功所需要的确认数，取值范围 [1, 2]。对于异步复制，quorum 设为 1，具有 master 角色的虚拟节点自己确认即可。对于同步复制，quorum 设为 2。原则上，Quorum >= 1 并且 Quorum <= replica(副本数)，这个参数在启动一个同步模块实例时需要提供。 QUORUM parameter specifies the necessary number of confirmations to determine whether the data is written successfully.
``` ```
ALTER DATABASE db_name BLOCKS 100; ALTER DATABASE db_name BLOCKS 100;
``` ```
BLOCKS 参数是每个 VNODE (TSDB) 中有多少 cache 大小的内存块，因此一个 VNODE 的用的内存大小粗略为（cache \* blocks）。取值范围 [3, 1000]。 BLOCKS parameter specifies the number of memory blocks used by each VNODE.
``` ```
ALTER DATABASE db_name CACHELAST 0; ALTER DATABASE db_name CACHELAST 0;
``` ```
CACHELAST 参数控制是否在内存中缓存子表的最近数据。缺省值为 0，取值范围 [0, 1, 2, 3]。其中 0 表示不缓存，1 表示缓存子表最近一行数据，2 表示缓存子表每一列的最近的非 NULL 值，3 表示同时打开缓存最近行和列功能。（从 2.0.11.0 版本开始支持参数值 [0, 1]，从 2.1.2.0 版本开始支持参数值 [0, 1, 2, 3]。） CACHELAST parameter specifies whether and how the latest data of a sub table is cached.
说明：缓存最近行，将显著改善 LAST_ROW 函数的性能表现；缓存每列的最近非 NULL 值，将显著改善无特殊影响（WHERE、ORDER BY、GROUP BY、INTERVAL）下的 LAST 函数的性能表现。
:::tip :::tip
以上所有参数修改后都可以用 show databases 来确认是否修改成功。另外，从 2.1.3.0 版本开始，修改这些参数后无需重启服务器即可生效。 The above parameters can be changed using `ALTER DATABASE` command without restarting. For more details of all configuration parameters please refer to [Configuration Parameters](/reference/config/).
:::tip
## 显示系统所有数据库 :::
## Show All Databases
``` ```
SHOW DATABASES; SHOW DATABASES;
``` ```
## 显示一个数据库的创建语句 ## Show The Create Statement of A Database
``` ```
SHOW CREATE DATABASE db_name; SHOW CREATE DATABASE db_name;
``` ```
常用于数据库迁移。对一个已经存在的数据库，返回其创建语句；在另一个集群中执行该语句，就能得到一个设置完全相同的 Database。 This command is useful when migrating the data from one TDengine cluster to another one. Firstly this command can be used to get the CREATE statement, which in turn can be used in another TDengine to create an exactly same database.
docs-en/12-taos-sql/03-table.md
浏览文件 @ 6e3b25d2
--- ---
title: 表管理 sidebar_label: Table
title: Table
description: create super table, normal table and sub table, drop tables and change tables
--- ---
## 创建数据表 ## Create Table
``` ```
CREATE TABLE [IF NOT EXISTS] tb_name (timestamp_field_name TIMESTAMP, field1_name data_type1 [, field2_name data_type2 ...]); CREATE TABLE [IF NOT EXISTS] tb_name (timestamp_field_name TIMESTAMP, field1_name data_type1 [, field2_name data_type2 ...]);
``` ```
:::info 说明 :::info
1. 表的第一个字段必须是 TIMESTAMP，并且系统自动将其设为主键； 1. The first column of a table must be in TIMESTAMP type, and it will be set as primary key automatically
2. 表名最大长度为 192； 2. The maximum length of table name is 192 bytes.
3. 表的每行长度不能超过 16k 个字符;（注意：每个 BINARY/NCHAR 类型的列还会额外占用 2 个字节的存储位置） 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. 子表名只能由字母、数字和下划线组成，且不能以数字开头，不区分大小写 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. 使用数据类型 binary 或 nchar，需指定其最长的字节数，如 binary(20)，表示 20 字节； 5. The maximum length in bytes must be specified when using BINARY or NCHAR type.
6. 为了兼容支持更多形式的表名，TDengine 引入新的转义符 "\`"，可以让表名与关键词不冲突，同时不受限于上述表名称合法性约束检查。但是同样具有长度限制要求。使用转义字符以后，不再对转义字符中的内容进行大小写统一。 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.
例如：\`aBc\` 和 \`abc\` 是不同的表名，但是 abc 和 aBc 是相同的表名。 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.
需要注意的是转义字符中的内容必须是可打印字符。
上述的操作逻辑和约束要求与 MySQL 数据的操作一致。
从 2.3.0.0 版本开始支持这种方式。
::: :::
### 以超级表为模板创建数据表 ### Create Table Using STable As Template
``` ```
CREATE TABLE [IF NOT EXISTS] tb_name USING stb_name TAGS (tag_value1, ...); 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, ...); CREATE TABLE [IF NOT EXISTS] tb_name USING stb_name (tag_name1, ...) TAGS (tag_value1, ...);
``` ```
以指定的超级表为模板，指定一部分 TAGS 列的值来创建数据表（没被指定的 TAGS 列会设为空值）。 The tags for which no value is specified will be set to NULL.
说明：从 2.0.17.0 版本开始支持这种方式。在之前的版本中，不允许指定 TAGS 列，而必须显式给出所有 TAGS 列的取值。
### 批量创建数据表 ### Create Tables in Batch
``` ```
CREATE TABLE [IF NOT EXISTS] tb_name1 USING stb_name TAGS (tag_value1, ...) [IF NOT EXISTS] tb_name2 USING stb_name TAGS (tag_value2, ...) ...; CREATE TABLE [IF NOT EXISTS] tb_name1 USING stb_name TAGS (tag_value1, ...) [IF NOT EXISTS] tb_name2 USING stb_name TAGS (tag_value2, ...) ...;
``` ```
以更快的速度批量创建大量数据表（服务器端 2.0.14 及以上版本）。 This way can be used to create a lot of tables in a single SQL statement to accelerate the speed of the creating tables.
:::info :::info
1.批量建表方式要求数据表必须以超级表为模板。 2.在不超出 SQL 语句长度限制的前提下，单条语句中的建表数量建议控制在 1000 ～ 3000 之间，将会获得比较理想的建表速度。 - Creating tables in batch must use super table as template.
- The length of single statement is suggested to be between 1,000 and 3,000 bytes for best performance.
::: :::
## 删除数据表 ## Drop Tables
``` ```
DROP TABLE [IF EXISTS] tb_name; DROP TABLE [IF EXISTS] tb_name;
``` ```
## 显示当前数据库下的所有数据表信息 ## Show All Tables In Current Database
``` ```
SHOW TABLES [LIKE tb_name_wildcar]; SHOW TABLES [LIKE tb_name_wildcar];
``` ```
显示当前数据库下的所有数据表信息。 ## Show Create Statement of A Table
## 显示一个数据表的创建语句
``` ```
SHOW CREATE TABLE tb_name; SHOW CREATE TABLE tb_name;
``` ```
常用于数据库迁移。对一个已经存在的数据表，返回其创建语句；在另一个集群中执行该语句，就能得到一个结构完全相同的数据表。 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; DESCRIBE tb_name;
``` ```
## 修改表定义 ## Change Table Definition
### 表增加列 ### Add A Column
``` ```
ALTER TABLE tb_name ADD COLUMN field_name data_type; ALTER TABLE tb_name ADD COLUMN field_name data_type;
...@@ -93,31 +89,39 @@ ALTER TABLE tb_name ADD COLUMN field_name data_type; ...@@ -93,31 +89,39 @@ ALTER TABLE tb_name ADD COLUMN field_name data_type;
:::info :::info
1. 列的最大个数为 1024，最小个数为 2；（从 2.1.7.0 版本开始，改为最多允许 4096 列） 1. The maximum number of columns is 4096, the minimum number of columns is 2.
2. 列名最大长度为 64。 2. The maximum length of column name is 64 bytes.
::: :::
### 表删除列 ### Remove A Column
``` ```
ALTER TABLE tb_name DROP COLUMN field_name; ALTER TABLE tb_name DROP COLUMN field_name;
``` ```
如果表是通过超级表创建，更改表结构的操作只能对超级表进行。同时针对超级表的结构更改对所有通过该结构创建的表生效。对于不是通过超级表创建的表，可以直接修改表结构。 :::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 Column Length
``` ```
ALTER TABLE tb_name MODIFY COLUMN field_name data_type(length); ALTER TABLE tb_name MODIFY COLUMN field_name data_type(length);
``` ```
如果数据列的类型是可变长格式（BINARY 或 NCHAR），那么可以使用此指令修改其宽度（只能改大，不能改小）。（2.1.3.0 版本新增） 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; 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.
docs-en/12-taos-sql/04-stable.md
浏览文件 @ 6e3b25d2
--- ---
sidebar_label: 超级表管理 sidebar_label: STable
title: 超级表 STable 管理 title: Super Table
--- ---
:::note :::note
在 2.0.15.0 及以后的版本中开始支持 STABLE 保留字。也即，在本节后文的指令说明中，CREATE、DROP、ALTER 三个指令在 2.0.15.0 之前的版本中 STABLE 保留字需写作 TABLE。 Keyword `STABLE`, abbreviated for super table, is supported since version 2.0.15.
::: :::
## 创建超级表 ## Crate STable
``` ```
CREATE STABLE [IF NOT EXISTS] stb_name (timestamp_field_name TIMESTAMP, field1_name data_type1 [, field2_name data_type2 ...]) TAGS (tag1_name tag_type1, tag2_name tag_type2 [, tag3_name tag_type3]); CREATE STABLE [IF NOT EXISTS] stb_name (timestamp_field_name TIMESTAMP, field1_name data_type1 [, field2_name data_type2 ...]) TAGS (tag1_name tag_type1, tag2_name tag_type2 [, tag3_name tag_type3]);
``` ```
创建 STable，与创建表的 SQL 语法相似，但需要指定 TAGS 字段的名称和类型。 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.
:::info :::info
1. TAGS 列的数据类型不能是 timestamp 类型；（从 2.1.3.0 版本开始，TAGS 列中支持使用 timestamp 类型，但需注意在 TAGS 中的 timestamp 列写入数据时需要提供给定值，而暂不支持四则运算，例如 `NOW + 10s` 这类表达式） 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. TAGS 列名不能与其他列名相同； 2. The tag names specified in TAGS should NOT be same as other columns.
3. TAGS 列名不能为预留关键字（参见：[参数限制与保留关键字](/taos-sql/keywords/) 章节）； 3. The tag names specified in TAGS should NOT be same as any reserved keywords.(Please refer to [keywords](/taos-sql/keywords/)
4. TAGS 最多允许 128 个，至少 1 个，总长度不超过 16 KB。 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; DROP STABLE [IF EXISTS] stb_name;
``` ```
删除 STable 会自动删除通过 STable 创建的子表。 All the sub-tables created using the deleted stable will be deleted automatically.
## 显示当前数据库下的所有超级表信息 ## Show All STables
``` ```
SHOW STABLES [LIKE tb_name_wildcard]; SHOW STABLES [LIKE tb_name_wildcard];
``` ```
查看数据库内全部 STable，及其相关信息，包括 STable 的名称、创建时间、列数量、标签（TAG）数量、通过该 STable 建表的数量。 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.
## 显示一个超级表的创建语句 ## Show The Create Statement of A STable
``` ```
SHOW CREATE STABLE stb_name; SHOW CREATE STABLE stb_name;
``` ```
常用于数据库迁移。对一个已经存在的超级表，返回其创建语句；在另一个集群中执行该语句，就能得到一个结构完全相同的超级表。 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; DESCRIBE stb_name;
``` ```
## 修改超级表普通列 ## Change Columns Of STable
### 超级表增加列 ### Add A Column
``` ```
ALTER STABLE stb_name ADD COLUMN field_name data_type; ALTER STABLE stb_name ADD COLUMN field_name data_type;
``` ```
### 超级表删除列 ### Remove A Column
``` ```
ALTER STABLE stb_name DROP COLUMN field_name; ALTER STABLE stb_name DROP COLUMN field_name;
``` ```
### 超级表修改列宽 ### Change Column Length
``` ```
ALTER STABLE stb_name MODIFY COLUMN field_name data_type(length); ALTER STABLE stb_name MODIFY COLUMN field_name data_type(length);
``` ```
如果数据列的类型是可变长格式（BINARY 或 NCHAR），那么可以使用此指令修改其宽度（只能改大，不能改小）。（2.1.3.0 版本新增） This command can be used to change (or incerase, more specifically) the length of a column of variable length types, like BINARY or NCHAR.
## 修改超级表标签列 ## Change Tags of A STable
### 添加标签 ### Add A Tag
``` ```
ALTER STABLE stb_name ADD TAG new_tag_name tag_type; ALTER STABLE stb_name ADD TAG new_tag_name tag_type;
``` ```
为 STable 增加一个新的标签，并指定新标签的类型。标签总数不能超过 128 个，总长度不超过 16k 个字符。 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; 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; 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); ALTER STABLE stb_name MODIFY TAG tag_name data_type(length);
``` ```
如果标签的类型是可变长格式（BINARY 或 NCHAR），那么可以使用此指令修改其宽度（只能改大，不能改小）。（2.1.3.0 版本新增） This command can be used to change (or incerase, more specifically) the length of a tag of variable length types, like BINARY or NCHAR.
:::note :::note
除了更新标签的值的操作是针对子表进行，其他所有的标签操作（添加标签、删除标签等）均只能作用于 STable，不能对单个子表操作。对 STable 添加标签以后，依托于该 STable 建立的所有表将自动增加了一个标签，所有新增标签的默认值都是 NULL。 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.
::: :::
docs-en/12-taos-sql/05-insert.md
浏览文件 @ 6e3b25d2
--- ---
sidebar_label: 数据写入 sidebar_label: Insert
title: 数据写入 title: Insert
--- ---
## 写入语法 ## Syntax
``` ```sql
INSERT INTO INSERT INTO
tb_name tb_name
[USING stb_name [(tag1_name, ...)] TAGS (tag1_value, ...)] [USING stb_name [(tag1_name, ...)] TAGS (tag1_value, ...)]
...@@ -18,116 +18,122 @@ INSERT INTO ...@@ -18,116 +18,122 @@ INSERT INTO
...]; ...];
``` ```
## 插入一条或多条记录 ## Insert Single or Multiple Rows
指定已经创建好的数据子表的表名，并通过 VALUES 关键字提供一行或多行数据，即可向数据库写入这些数据。例如，执行如下语句可以写入一行记录： Single row or multiple rows specified with VALUES can be inserted into a specific table. For example
``` Single row is inserted using below statement.
```sq;
INSERT INTO d1001 VALUES (NOW, 10.2, 219, 0.32); INSERT INTO d1001 VALUES (NOW, 10.2, 219, 0.32);
``` ```
或者，可以通过如下语句写入两行记录： Double rows can be inserted using below statement.
``` ```sql
INSERT INTO d1001 VALUES ('2021-07-13 14:06:32.272', 10.2, 219, 0.32) (1626164208000, 10.15, 217, 0.33); INSERT INTO d1001 VALUES ('2021-07-13 14:06:32.272', 10.2, 219, 0.32) (1626164208000, 10.15, 217, 0.33);
``` ```
:::note :::note
1. 在第二个例子中，两行记录的首列时间戳使用了不同格式的写法。其中字符串格式的时间戳写法不受所在 DATABASE 的时间精度设置影响；而长整形格式的时间戳写法会受到所在 DATABASE 的时间精度设置影响——例子中的时间戳在毫秒精度下可以写作 1626164208000，而如果是在微秒精度设置下就需要写为 1626164208000000，纳秒精度设置下需要写为 1626164208000000000。 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. 在使用“插入多条记录”方式写入数据时，不能把第一列的时间戳取值都设为 NOW，否则会导致语句中的多条记录使用相同的时间戳，于是就可能出现相互覆盖以致这些数据行无法全部被正确保存。其原因在于，NOW 函数在执行中会被解析为所在 SQL 语句的实际执行时间，出现在同一语句中的多个 NOW 标记也就会被替换为完全相同的时间戳取值。 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. 允许插入的最老记录的时间戳，是相对于当前服务器时间，减去配置的 keep 值（数据保留的天数）；允许插入的最新记录的时间戳，是相对于当前服务器时间，加上配置的 days 值（数据文件存储数据的时间跨度，单位为天）。keep 和 days 都是可以在创建数据库时指定的，缺省值分别是 3650 天和 10 天。 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.
::: :::
## 插入记录，数据对应到指定的列 ## Insert Into Specific Columns
向数据子表中插入记录时，无论插入一行还是多行，都可以让数据对应到指定的列。对于 SQL 语句中没有出现的列，数据库将自动填充为 NULL。主键（时间戳）不能为 NULL。例如： Data can be inserted into specific columns, either single row or multiple row, while other columns will be inserted as NULL value.
``` ```
INSERT INTO d1001 (ts, current, phase) VALUES ('2021-07-13 14:06:33.196', 10.27, 0.31); INSERT INTO d1001 (ts, current, phase) VALUES ('2021-07-13 14:06:33.196', 10.27, 0.31);
``` ```
:::info :::info
如果不指定列，也即使用全列模式——那么在 VALUES 部分提供的数据，必须为数据表的每个列都显式地提供数据。全列模式写入速度会远快于指定列，因此建议尽可能采用全列写入方式，此时空列可以填入 NULL。 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.
``` ```sql
INSERT INTO d1001 VALUES ('2021-07-13 14:06:34.630', 10.2, 219, 0.32) ('2021-07-13 14:06:35.779', 10.15, 217, 0.33) INSERT INTO d1001 VALUES ('2021-07-13 14:06:34.630', 10.2, 219, 0.32) ('2021-07-13 14:06:35.779', 10.15, 217, 0.33)
d1002 (ts, current, phase) VALUES ('2021-07-13 14:06:34.255', 10.27, 0.31）; d1002 (ts, current, phase) VALUES ('2021-07-13 14:06:34.255', 10.27, 0.31）;
``` ```
## 插入记录时自动建表 ## Automatically Create Table When Inserting
如果用户在写数据时并不确定某个表是否存在，此时可以在写入数据时使用自动建表语法来创建不存在的表，若该表已存在则不会建立新表。自动建表时，要求必须以超级表为模板，并写明数据表的 TAGS 取值。例如： 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.
``` ```sql
INSERT INTO d21001 USING meters TAGS ('Beijing.Chaoyang', 2) VALUES ('2021-07-13 14:06:32.272', 10.2, 219, 0.32); INSERT INTO d21001 USING meters TAGS ('Beijing.Chaoyang', 2) VALUES ('2021-07-13 14:06:32.272', 10.2, 219, 0.32);
``` ```
也可以在自动建表时，只是指定部分 TAGS 列的取值，未被指定的 TAGS 列将置为 NULL。例如： It's not necessary to provide values for all tag when creating tables automatically, the tags without values provided will be set to NULL.
``` ```sql
INSERT INTO d21001 USING meters (groupId) TAGS (2) VALUES ('2021-07-13 14:06:33.196', 10.15, 217, 0.33); INSERT INTO d21001 USING meters (groupId) TAGS (2) VALUES ('2021-07-13 14:06:33.196', 10.15, 217, 0.33);
``` ```
自动建表语法也支持在一条语句中向多个表插入记录。例如： Multiple rows can also be inserted into same table in single SQL statement using this way.自
``` ```sql
INSERT INTO d21001 USING meters TAGS ('Beijing.Chaoyang', 2) VALUES ('2021-07-13 14:06:34.630', 10.2, 219, 0.32) ('2021-07-13 14:06:35.779', 10.15, 217, 0.33) INSERT INTO d21001 USING meters TAGS ('Beijing.Chaoyang', 2) VALUES ('2021-07-13 14:06:34.630', 10.2, 219, 0.32) ('2021-07-13 14:06:35.779', 10.15, 217, 0.33)
d21002 USING meters (groupId) TAGS (2) VALUES ('2021-07-13 14:06:34.255', 10.15, 217, 0.33) d21002 USING meters (groupId) TAGS (2) VALUES ('2021-07-13 14:06:34.255', 10.15, 217, 0.33)
d21003 USING meters (groupId) TAGS (2) (ts, current, phase) VALUES ('2021-07-13 14:06:34.255', 10.27, 0.31); d21003 USING meters (groupId) TAGS (2) (ts, current, phase) VALUES ('2021-07-13 14:06:34.255', 10.27, 0.31);
``` ```
:::info :::info
在 2.0.20.5 版本之前，在使用自动建表语法并指定列时，子表的列名必须紧跟在子表名称后面，而不能如例子里那样放在 TAGS 和 VALUES 之间。从 2.0.20.5 版本开始，两种写法都可以，但不能在一条 SQL 语句中混用，否则会报语法错误。 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.
::: :::
## 插入来自文件的数据记录 ## Insert Rows From A File
除了使用 VALUES 关键字插入一行或多行数据外，也可以把要写入的数据放在 CSV 文件中（英文逗号分隔、英文单引号括住每个值）供 SQL 指令读取。其中 CSV 文件无需表头。例如，如果 /tmp/csvfile.csv 文件的内容为： 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:34.630', '10.2', '219', '0.32'
'2021-07-13 14:07:35.779', '10.15', '217', '0.33' '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
INSERT INTO d1001 FILE '/tmp/csvfile.csv'; INSERT INTO d1001 FILE '/tmp/csvfile.csv';
``` ```
## 插入来自文件的数据记录，并自动建表 ## CreateTables Automatically and Insert Rows From File
从 2.1.5.0 版本开始，支持在插入来自 CSV 文件的数据时，以超级表为模板来自动创建不存在的数据表。例如： From version 2.1.5.0, tables can be automatically created using a super table as template when inserting data from a CSV file, Like below:
``` ```sql
INSERT INTO d21001 USING meters TAGS ('Beijing.Chaoyang', 2) FILE '/tmp/csvfile.csv'; INSERT INTO d21001 USING meters TAGS ('Beijing.Chaoyang', 2) FILE '/tmp/csvfile.csv';
``` ```
也可以在一条语句中向多个表以自动建表的方式插入记录。例如： Multiple tables can be automatically created and inserted in single SQL statement, like below:也
``` ```sql
INSERT INTO d21001 USING meters TAGS ('Beijing.Chaoyang', 2) FILE '/tmp/csvfile_21001.csv' INSERT INTO d21001 USING meters TAGS ('Beijing.Chaoyang', 2) FILE '/tmp/csvfile_21001.csv'
d21002 USING meters (groupId) TAGS (2) FILE '/tmp/csvfile_21002.csv'; d21002 USING meters (groupId) TAGS (2) FILE '/tmp/csvfile_21002.csv';
``` ```
## 历史记录写入 ## More About Insert
可使用 IMPORT 或者 INSERT 命令，IMPORT 的语法，功能与 INSERT 完全一样。 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.
针对 insert 类型的 SQL 语句，我们采用的流式解析策略，在发现后面的错误之前，前面正确的部分 SQL 仍会执行。下面的 SQL 中，INSERT 语句是无效的，但是 d1001 仍会被创建。 Firstly, a super table is created.
```sql
CREATE TABLE meters(ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS(location BINARY(30), groupId INT);
``` ```
taos> CREATE TABLE meters(ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS(location BINARY(30), groupId INT);
Query OK, 0 row(s) affected (0.008245s)
It can be proved that the super table has been created by `SHOW STABLES`, but no table exists by `SHOW TABLES`.
```
taos> SHOW STABLES; taos> SHOW STABLES;
name | created_time | columns | tags | tables | name | created_time | columns | tags | tables |
============================================================================================ ============================================================================================
...@@ -136,9 +142,17 @@ Query OK, 1 row(s) in set (0.001029s) ...@@ -136,9 +142,17 @@ Query OK, 1 row(s) in set (0.001029s)
taos> SHOW TABLES; taos> SHOW TABLES;
Query OK, 0 row(s) in set (0.000946s) Query OK, 0 row(s) in set (0.000946s)
```
taos> INSERT INTO d1001 USING meters TAGS('Beijing.Chaoyang', 2) VALUES('a'); Then, try to create table d1001 automatically when inserting data into it.
```sql
INSERT INTO d1001 USING meters TAGS('Beijing.Chaoyang', 2) VALUES('a');
```
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) DB error: invalid SQL: 'a' (invalid timestamp) (0.039494s)
taos> SHOW TABLES; taos> SHOW TABLES;
...@@ -147,3 +161,5 @@ taos> SHOW TABLES; ...@@ -147,3 +161,5 @@ taos> SHOW TABLES;
d1001 | 2020-08-06 17:52:02.097 | 4 | meters | d1001 | 2020-08-06 17:52:02.097 | 4 | meters |
Query OK, 1 row(s) in set (0.001091s) 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.
docs-en/12-taos-sql/06-select.md
浏览文件 @ 6e3b25d2
--- ---
sidebar_label: 数据查询 sidebar_label: Select
title: 数据查询 title: Select
--- ---
## 查询语法 ## Syntax
``` ```SQL
SELECT select_expr [, select_expr ...] SELECT select_expr [, select_expr ...]
FROM {tb_name_list} FROM {tb_name_list}
[WHERE where_condition] [WHERE where_condition]
...@@ -20,9 +20,9 @@ SELECT select_expr [, select_expr ...] ...@@ -20,9 +20,9 @@ SELECT select_expr [, select_expr ...]
[>> export_file]; [>> export_file];
``` ```
## 通配符 ## Wildcard
通配符 \* 可以用于代指全部列。对于普通表，结果中只有普通列。 Wilcard \* can be used to specify all columns. The result includes only data columns for normal tables.
``` ```
taos> SELECT * FROM d1001; taos> SELECT * FROM d1001;
...@@ -34,7 +34,7 @@ taos> SELECT * FROM d1001; ...@@ -34,7 +34,7 @@ taos> SELECT * FROM d1001;
Query OK, 3 row(s) in set (0.001165s) Query OK, 3 row(s) in set (0.001165s)
``` ```
在针对超级表，通配符包含 _标签列_ 。 The result includes both data columns and tag columns for super table.
``` ```
taos> SELECT * FROM meters; taos> SELECT * FROM meters;
...@@ -52,14 +52,14 @@ taos> SELECT * FROM meters; ...@@ -52,14 +52,14 @@ taos> SELECT * FROM meters;
Query OK, 9 row(s) in set (0.002022s) Query OK, 9 row(s) in set (0.002022s)
``` ```
通配符支持表名前缀，以下两个 SQL 语句均为返回全部的列： Wildcard can be used with table name as prefix, both below SQL statements have same effects and return all columns.
``` ```SQL
SELECT * FROM d1001; SELECT * FROM d1001;
SELECT d1001.* FROM d1001; SELECT d1001.* FROM d1001;
``` ```
在 JOIN 查询中，带前缀的\*和不带前缀\*返回的结果有差别， \*返回全部表的所有列数据（不包含标签），带前缀的通配符，则只返回该表的列数据。 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; 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; ...@@ -77,8 +77,7 @@ taos> SELECT d1001.* FROM d1001,d1003 WHERE d1001.ts = d1003.ts;
Query OK, 1 row(s) in set (0.020443s) Query OK, 1 row(s) in set (0.020443s)
``` ```
在使用 SQL 函数来进行查询的过程中，部分 SQL 函数支持通配符操作。其中的区别在于： 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.
`count(*)`函数只返回一列。`first`、`last`、`last_row`函数则是返回全部列。
``` ```
taos> SELECT COUNT(*) FROM d1001; taos> SELECT COUNT(*) FROM d1001;
...@@ -96,9 +95,9 @@ taos> SELECT FIRST(*) FROM d1001; ...@@ -96,9 +95,9 @@ taos> SELECT FIRST(*) FROM d1001;
Query OK, 1 row(s) in set (0.000849s) Query OK, 1 row(s) in set (0.000849s)
``` ```
## 标签列 ## Tags
从 2.0.14 版本开始，支持在普通表的查询中指定 _标签列_，且标签列的值会与普通列的数据一起返回。 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; taos> SELECT location, groupid, current FROM d1001 LIMIT 2;
...@@ -109,33 +108,26 @@ taos> SELECT location, groupid, current FROM d1001 LIMIT 2; ...@@ -109,33 +108,26 @@ taos> SELECT location, groupid, current FROM d1001 LIMIT 2;
Query OK, 2 row(s) in set (0.003112s) Query OK, 2 row(s) in set (0.003112s)
``` ```
注意：普通表的通配符 \* 中并不包含 _标签列_。 ## Get distinct values
## 获取标签列或普通列的去重取值 `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.
从 2.0.15.0 版本开始，支持在超级表查询标签列时，指定 DISTINCT 关键字，这样将返回指定标签列的所有不重复取值。注意，在 2.1.6.0 版本之前，DISTINCT 只支持处理单个标签列，而从 2.1.6.0 版本开始，DISTINCT 可以对多个标签列进行处理，输出这些标签列取值不重复的组合。
```sql ```sql
SELECT DISTINCT tag_name [, tag_name ...] FROM stb_name; SELECT DISTINCT tag_name [, tag_name ...] FROM stb_name;
```
从 2.1.7.0 版本开始，DISTINCT 也支持对数据子表或普通表进行处理，也即支持获取单个普通列的不重复取值，或多个普通列取值的不重复组合。
```sql
SELECT DISTINCT col_name [, col_name ...] FROM tb_name; SELECT DISTINCT col_name [, col_name ...] FROM tb_name;
``` ```
:::info :::info
1. cfg 文件中的配置参数 maxNumOfDistinctRes 将对 DISTINCT 能够输出的数据行数进行限制。其最小值是 100000，最大值是 100000000，默认值是 10000000。如果实际计算结果超出了这个限制，那么会仅输出这个数量范围内的部分。 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. 由于浮点数天然的精度机制原因，在特定情况下，对 FLOAT 和 DOUBLE 列使用 DISTINCT 并不能保证输出值的完全唯一性。 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 不能在嵌套查询的子查询中使用，也不能与聚合函数、GROUP BY、或 JOIN 在同一条语句中混用。 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.
::: :::
## 结果集列名 ## Columns Names of Result Set
`SELECT`子句中，如果不指定返回结果集合的列名，结果集列名称默认使用`SELECT`子句中的表达式名称作为列名称。此外，用户可使用`AS`来重命名返回结果集合中列的名称。例如： 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; taos> SELECT ts, ts AS primary_key_ts FROM d1001;
...@@ -147,27 +139,30 @@ taos> SELECT ts, ts AS primary_key_ts FROM d1001; ...@@ -147,27 +139,30 @@ taos> SELECT ts, ts AS primary_key_ts FROM d1001;
Query OK, 3 row(s) in set (0.001191s) Query OK, 3 row(s) in set (0.001191s)
``` ```
但是针对`first(*)`、`last(*)`、`last_row(*)`不支持针对单列的重命名。 `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.
## 表（超级表）列表 ## Table List
FROM 关键字后面可以是若干个表（超级表）列表，也可以是子查询的结果。 `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`.
如果没有指定用户的当前数据库，可以在表名称之前使用数据库的名称来指定表所属的数据库。例如：`power.d1001` 方式来跨库使用表。
``` ```SQL
SELECT * FROM power.d1001; SELECT * FROM power.d1001;
------------------------------ ```
has same effect as
```SQL
USE power; USE power;
SELECT * FROM d1001; 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(); taos> SELECT DATABASE();
...@@ -177,7 +172,7 @@ taos> SELECT DATABASE(); ...@@ -177,7 +172,7 @@ taos> SELECT DATABASE();
Query OK, 1 row(s) in set (0.000079s) 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(); taos> SELECT DATABASE();
...@@ -187,7 +182,7 @@ taos> SELECT DATABASE(); ...@@ -187,7 +182,7 @@ taos> SELECT DATABASE();
Query OK, 1 row(s) in set (0.000184s) Query OK, 1 row(s) in set (0.000184s)
``` ```
获取服务器和客户端版本号： Below statement can be used to get the version of client or server.
``` ```
taos> SELECT CLIENT_VERSION(); taos> SELECT CLIENT_VERSION();
...@@ -203,7 +198,7 @@ taos> SELECT SERVER_VERSION(); ...@@ -203,7 +198,7 @@ taos> SELECT SERVER_VERSION();
Query OK, 1 row(s) in set (0.000077s) Query OK, 1 row(s) in set (0.000077s)
``` ```
服务器状态检测语句。如果服务器正常，返回一个数字（例如 1）。如果服务器异常，返回 error code。该 SQL 语法能兼容连接池对于 TDengine 状态的检查及第三方工具对于数据库服务器状态的检查。并可以避免出现使用了错误的心跳检测 SQL 语句导致的连接池连接丢失的问题。 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(); taos> SELECT SERVER_STATUS();
...@@ -219,66 +214,59 @@ taos> SELECT SERVER_STATUS() AS status; ...@@ -219,66 +214,59 @@ taos> SELECT SERVER_STATUS() AS status;
Query OK, 1 row(s) in set (0.000081s) 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 } 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.
- 返回的结果是该表或超级表的数据块所包含的行数的数据分布直方图。
```txt title="返回结果" ```text title="Result"
summary: summary:
5th=[392], 10th=[392], 20th=[392], 30th=[392], 40th=[792], 50th=[792] 60th=[792], 70th=[792], 80th=[792], 90th=[792], 95th=[792], 99th=[792] Min=[392(Rows)] Max=[800(Rows)] Avg=[666(Rows)] Stddev=[2.17] Rows=[2000], Blocks=[3], Size=[5.440(Kb)] Comp=[0.23] RowsInMem=[0] SeekHeaderTime=[1(us)] 5th=[392], 10th=[392], 20th=[392], 30th=[392], 40th=[792], 50th=[792] 60th=[792], 70th=[792], 80th=[792], 90th=[792], 95th=[792], 99th=[792] Min=[392(Rows)] Max=[800(Rows)] Avg=[666(Rows)] Stddev=[2.17] Rows=[2000], Blocks=[3], Size=[5.440(Kb)] Comp=[0.23] RowsInMem=[0] SeekHeaderTime=[1(us)]
``` ```
**上述信息的说明如下**: **More explanation about above example**:
- 查询的（超级）表所包含的存储在文件中的数据块（data block）中所包含的数据行的数量分布直方图信息：5%， 10%， 20%， 30%， 40%， 50%， 60%， 70%， 80%， 90%， 95%， 99% 的数值； - 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%
- 所有数据块中，包含行数最少的数据块所包含的行数量， 其中的 Min 指标 392 行。 - Minimum number of rows stored in a data block, i.e. Min=[392(Rows)]
- 所有数据块中，包含行数最多的数据块所包含的行数量， 其中的 Max 指标 800 行。 - Maximum number of rows stored in a data block, i.e. Max=[800(Rows)]
- 所有数据块行数的算数平均值 666 行（其中的 Avg 项）。 - Average number of rows stored in a data block, i.e. Avg=[666(Rows)]
- 所有数据块中行数分布的均方差为 2.17 ( stddev ）。 - stddev of number of rows, i.e. Stddev=[2.17]
- 数据块包含的行的总数为 2000 行（Rows）。 - Total number of rows, i.e. Rows[2000]
- 数据块总数是 3 个数据块 （Blocks）。 - Total number of data blocks, i.e. Blocks=[3]
- 数据块占用磁盘空间大小 5.44 Kb （size）。 - Total disk size consumed, i.e. Size=[5.440(Kb)]
- 压缩后的数据块的大小除以原始数据的所获得的压缩比例： 23%（Comp），及压缩后的数据规模是原始数据规模的 23%。 - Compression ratio, which means the compressed size divided by original size, i.e. Comp=[0.23]
- 内存中存在的数据行数是 0，表示内存中没有数据缓存。 - Total number of rows in memory, i.e. RowsInMem=[0], which means no rows in memory
- 获取数据块信息的过程中读取头文件的时间开销 1 微秒（SeekHeaderTime）。 - The time spent on reading head file (to retrieve data block information), i.e. SeekHeaderTime=[1(us)], which means 1 microsecond.
**支持版本**：指定计算算法的功能从 2.1.0.x 版本开始，2.1.0.0 之前的版本不支持指定使用算法的功能。 ## Special Keywords in TAOS SQL
## TAOS SQL 中特殊关键词 - `TBNAME`： it is treated as a special tag when selecting on a super table, representing the name of sub-tables in that super table.
- `_c0`: represents the first column of a table or super table.
- `TBNAME`： 在超级表查询中可视为一个特殊的标签，代表查询涉及的子表名 ## Tips
- `_c0`: 表示表（超级表）的第一列
## 小技巧 To get all the sub tables and corresponding tag values from a super table:
获取一个超级表所有的子表名及相关的标签信息： ```SQL
```
SELECT TBNAME, location FROM meters; SELECT TBNAME, location FROM meters;
``` ```
统计超级表下辖子表数量： To get the number of sub tables in a super table：
``` ```SQL
SELECT COUNT(TBNAME) FROM meters; SELECT COUNT(TBNAME) FROM meters;
``` ```
以上两个查询均只支持在 WHERE 条件子句中添加针对标签（TAGS）的过滤条件。例如： Only filter on `TAGS` are allowed in the `where` clause for above two query statements. For example:
``` ```
taos> SELECT TBNAME, location FROM meters; taos> SELECT TBNAME, location FROM meters;
...@@ -297,17 +285,19 @@ taos> SELECT COUNT(tbname) FROM meters WHERE groupId > 2; ...@@ -297,17 +285,19 @@ taos> SELECT COUNT(tbname) FROM meters WHERE groupId > 2;
Query OK, 1 row(s) in set (0.001091s) Query OK, 1 row(s) in set (0.001091s)
``` ```
- 可以使用 \* 返回所有列，或指定列名。可以对数字列进行四则运算，可以给输出的列取列名。 - 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.
- 暂不支持含列名的四则运算表达式用于条件过滤算子（例如，不支持 `where a*2>6;`，但可以写 `where a>6/2;`）。 - 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.
- 暂不支持含列名的四则运算表达式作为 SQL 函数的应用对象（例如，不支持 `select min(2*a) from t;`，但可以写 `select 2*min(a) from t;`）。 - 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.
- WHERE 语句可以使用各种逻辑判断来过滤数字值，或使用通配符来过滤字符串。 - Logical operation can be used in `WHERE` clause to filter numeric values, wildcard can be used to filter string values.
- 输出结果缺省按首列时间戳升序排序，但可以指定按降序排序( \_c0 指首列时间戳)。使用 ORDER BY 对其他字段进行排序,排序结果顺序不确定。 - 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 控制输出条数，OFFSET 指定从第几条开始输出。LIMIT/OFFSET 对结果集的执行顺序在 ORDER BY 之后。且 `LIMIT 5 OFFSET 2` 可以简写为 `LIMIT 2, 5`。 - `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`.
- 在有 GROUP BY 子句的情况下，LIMIT 参数控制的是每个分组中至多允许输出的条数。 - What is controlled by `LIMIT` is the number of rows in each group when `GROUP BY` is used.
- 参数 SLIMIT 控制由 GROUP BY 指令划分的分组中，至多允许输出几个分组的数据。且 `SLIMIT 5 SOFFSET 2` 可以简写为 `SLIMIT 2, 5`。 - `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** | | **Operation** | **Note** | **Applicable Data Types** |
| ------------- | ------------------------ | ----------------------------------------- | | ------------- | ------------------------ | ----------------------------------------- |
...@@ -325,42 +315,41 @@ Query OK, 1 row(s) in set (0.001091s) ...@@ -325,42 +315,41 @@ Query OK, 1 row(s) in set (0.001091s)
**使用说明**: **使用说明**:
- <\> 算子也可以写为 != ，请注意，这个算子不能用于数据表第一列的 timestamp 字段。 - 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.
- like 算子使用通配符字符串进行匹配检查。 - Operator `like` is used together with wildcards to match strings
- 在通配符字符串中：'%'（百分号）匹配 0 到任意个字符；'\_'（下划线）匹配单个任意 ASCII 字符。 - '%' matches 0 or any number of characters, '\_' matches any single ASCII character.
- 如果希望匹配字符串中原本就带有的 \_（下划线）字符，那么可以在通配符字符串中写作 `\_`，也即加一个反斜线来进行转义。（从 2.2.0.0 版本开始支持） - `\_` is used to match the \_ in the string.
- 通配符字符串最长不能超过 20 字节。（从 2.1.6.1 版本开始，通配符字符串的长度放宽到了 100 字节，并可以通过 taos.cfg 中的 maxWildCardsLength 参数来配置这一长度限制。但不建议使用太长的通配符字符串，将有可能严重影响 LIKE 操作的执行性能。） - 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 来连接不同的查询条件，暂不支持 OR 连接的不同列之间的查询过滤条件。 - `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.
- 从 2.3.0.0 版本开始，已支持完整的同一列和/或不同列间的 AND/OR 运算。 - 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))`.
- 针对单一字段的过滤，如果是时间过滤条件，则一条语句中只支持设定一个；但针对其他的（普通）列或标签列，则可以使用 `OR` 关键字进行组合条件的查询过滤。例如： `((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.
- 从 2.3.0.0 版本开始，允许使用多个时间过滤条件，但首列时间戳的过滤运算结果只能包含一个区间。 - 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".
- 从 2.0.17.0 版本开始，条件过滤开始支持 BETWEEN AND 语法，例如 `WHERE col2 BETWEEN 1.5 AND 3.25` 表示查询条件为“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`.
- 从 2.1.4.0 版本开始，条件过滤开始支持 IN 算子，例如 `WHERE city IN ('Beijing', 'Shanghai')`。说明：BOOL 类型写作 `{true, false}` 或 `{0, 1}` 均可，但不能写作 0、1 之外的整数；FLOAT 和 DOUBLE 类型会受到浮点数精度影响，集合内的值在精度范围内认为和数据行的值完全相等才能匹配成功；TIMESTAMP 类型支持非主键的列。 - From version 2.3.0.0, regular expression is supported in where clause with keyword `match` or `nmatch`, the regular expression is case insensitive.
- 从 2.3.0.0 版本开始，条件过滤开始支持正则表达式，关键字 match/nmatch，不区分大小写。
## 正则表达式过滤 ## Regular Expression
### 语法 ### Syntax
```txt ```SQL
WHERE (column|tbname) **match/MATCH/nmatch/NMATCH** _regex_ WHERE (column|tbname) **match/MATCH/nmatch/NMATCH** _regex_
``` ```
### 正则表达式规范 ### Specification
确保使用的正则表达式符合 POSIX 的规范，具体规范内容可参见[Regular Expressions](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html) 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).
### 使用限制 ### Restrictions
只能针对表名（即 tbname 筛选）、binary/nchar 类型标签值进行正则表达式过滤，不支持普通列的过滤。 Regular expression can be used against only table names, i.e. `tbname`, and tags of binary/nchar types, but can't be used against data columns.
正则匹配字符串长度不能超过 128 字节。可以通过参数 _maxRegexStringLen_ 设置和调整最大允许的正则匹配字符串，该参数是客户端配置参数，需要重启才能生效。 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.
## JOIN 子句 ## JOIN
从 2.2.0.0 版本开始，TDengine 对内连接（INNER JOIN）中的自然连接（Natural join）操作实现了完整的支持。也即支持“普通表与普通表之间”、“超级表与超级表之间”、“子查询与子查询之间”进行自然连接。自然连接与内连接的主要区别是，自然连接要求参与连接的字段在不同的表/超级表中必须是同名字段。也即，TDengine 在连接关系的表达中，要求必须使用同名数据列/标签列的相等关系。 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 ```sql
SELECT * SELECT *
...@@ -368,7 +357,7 @@ FROM temp_tb_1 t1, pressure_tb_1 t2 ...@@ -368,7 +357,7 @@ FROM temp_tb_1 t1, pressure_tb_1 t2
WHERE t1.ts = t2.ts WHERE t1.ts = t2.ts
``` ```
在超级表与超级表之间的 JOIN 操作中，除了主键时间戳一致的条件外，还要求引入能实现一一对应的标签列的相等关系。例如： In the join operation between stable and stable, besides the primary key, i.e. timestamp, tags can also be used. For example:
```sql ```sql
SELECT * SELECT *
...@@ -376,88 +365,86 @@ FROM temp_stable t1, temp_stable t2 ...@@ -376,88 +365,86 @@ FROM temp_stable t1, temp_stable t2
WHERE t1.ts = t2.ts AND t1.deviceid = t2.deviceid AND t1.status=0; WHERE t1.ts = t2.ts AND t1.deviceid = t2.deviceid AND t1.status=0;
``` ```
类似地，也可以对多个子查询的查询结果进行 JOIN 操作。 Similary, join operation can be performed on the result set of multiple sub queries.
:::note :::note
Restrictions on join operation:
JOIN语句存在如下限制要求： - The number of tables or stables in single join operation can't exceed 10.
- `FILL` is not allowed in the query statement that includes JOIN operation.
- 参与一条语句中 JOIN 操作的表/超级表最多可以有 10 个。 - Arithmetic operation is not allowed on the result set of join operation.
- 在包含 JOIN 操作的查询语句中不支持 FILL。 - `GROUP BY` is not allowed on a part of tables that participate in join operation.
- 暂不支持参与 JOIN 操作的表之间聚合后的四则运算。 - `OR` can't be used in the conditions for join operation
- 不支持只对其中一部分表做 GROUP BY。 - join operation can't be performed on data columns, i.e. can only be performed on tags or primary key, i.e. timestamp
- JOIN 查询的不同表的过滤条件之间不能为 OR。
- JOIN 查询要求连接条件不能是普通列，只能针对标签和主时间字段列（第一列）。
::: :::
## 嵌套查询 ## Nested Query
“嵌套查询”又称为“子查询”，也即在一条 SQL 语句中，“内层查询”的计算结果可以作为“外层查询”的计算对象来使用。 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.
从 2.2.0.0 版本开始，TDengine 的查询引擎开始支持在 FROM 子句中使用非关联子查询（“非关联”的意思是，子查询不会用到父查询中的参数）。也即在普通 SELECT 语句的 tb_name_list 位置，用一个独立的 SELECT 语句来代替（这一 SELECT 语句被包含在英文圆括号内），于是完整的嵌套查询 SQL 语句形如： 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 ...) ...; SELECT ... FROM (SELECT ... FROM ...) ...;
``` ```
:::info :::info
- 目前仅支持一层嵌套，也即不能在子查询中再嵌入子查询。 - Only one layer of nesting is allowed, that means no sub query is allowed in a sub query
- 内层查询的返回结果将作为“虚拟表”供外层查询使用，此虚拟表可以使用 AS 语法做重命名，以便于外层查询中方便引用。 - 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。内层查询的计算结果也可以再参与数据子表的 JOIN 操作。 - 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 操作。 - 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 子句一般没有意义，建议避免这样的写法以免无谓的资源消耗。 - `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
- 如果内层查询的结果数据未提供时间戳，那么计算过程依赖时间戳的函数在外层会无法正常工作。例如：TOP, BOTTOM, FIRST, LAST, DIFF。 - 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`.
- 计算过程需要两遍扫描的函数，在外层查询中无法正常工作。例如：此类函数包括：STDDEV, PERCENTILE。 - Functions that need to scan the data twice can't be used in the outer query, like `STDDEV`, `PERCENTILE`.
- 外层查询中不支持 IN 算子，但在内层中可以使用。 - `IN` operator is not allowed in the outer query but can be used in the inner query.
- 外层查询不支持 GROUP BY。 - `GROUP BY` is not supported in the outer query.
::: :::
## UNION ALL 子句 ## UNION ALL
```txt title=语法 ```SQL title=Syntax
SELECT ... SELECT ...
UNION ALL SELECT ... UNION ALL 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.
### SQL 示例 ### Examples
对于下面的例子，表 tb1 用以下语句创建： table `tb1` is created using below SQL statement:
``` ```SQL
CREATE TABLE tb1 (ts TIMESTAMP, col1 INT, col2 FLOAT, col3 BINARY(50)); CREATE TABLE tb1 (ts TIMESTAMP, col1 INT, col2 FLOAT, col3 BINARY(50));
``` ```
查询 tb1 刚过去的一个小时的所有记录： The rows in the past one hour in `tb1` can be selected using below SQL statement:
``` ```SQL
SELECT * FROM tb1 WHERE ts >= NOW - 1h; SELECT * FROM tb1 WHERE ts >= NOW - 1h;
``` ```
查询表 tb1 从 2018-06-01 08:00:00.000 到 2018-06-02 08:00:00.000 时间范围，并且 col3 的字符串是'nny'结尾的记录，结果按照时间戳降序： 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; 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;
``` ```
查询 col1 与 col2 的和，并取名 complex, 时间大于 2018-06-01 08:00:00.000, col2 大于 1.2，结果输出仅仅 10 条记录，从第 5 条开始： 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; SELECT (col1 + col2) AS 'complex' FROM tb1 WHERE ts > '2018-06-01 08:00:00.000' AND col2 > 1.2 LIMIT 10 OFFSET 5;
``` ```
查询过去 10 分钟的记录，col2 的值大于 3.14，并且将结果输出到文件 `/home/testoutpu.csv`： 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; SELECT COUNT(*) FROM tb1 WHERE ts >= NOW - 10m AND col2 > 3.14 >> /home/testoutpu.csv;
``` ```
docs-en/12-taos-sql/07-function.md
浏览文件 @ 6e3b25d2
--- ---
sidebar_label: SQL 函数 sidebar_label: Functions
title: SQL 函数 title: Functions
--- ---
## 聚合函数 ## Aggregate Functions
TDengine 支持针对数据的聚合查询。提供支持的聚合和选择函数如下： Aggregate query is supported in TDengine by following aggregate functions and selection functions.
### COUNT ### COUNT
...@@ -13,21 +13,20 @@ TDengine 支持针对数据的聚合查询。提供支持的聚合和选择函 ...@@ -13,21 +13,20 @@ TDengine 支持针对数据的聚合查询。提供支持的聚合和选择函
SELECT COUNT([*|field_name]) FROM tb_name [WHERE clause]; SELECT COUNT([*|field_name]) FROM tb_name [WHERE clause];
``` ```
**功能说明**：统计表/超级表中记录行数或某列的非空值个数。 **Description**:Get the number of rows or the number of non-null values in a table or a super table.
**返回数据类型**：长整型 INT64。 **Return value type**:Long integer INT64
**应用字段**：应用全部字段。 **Applicable column types**:All
**适用于**：表、超级表。 **Applicable table types**: table, super table, sub table
**使用说明**: **More explanation**:
- 可以使用星号(\*)来替代具体的字段，使用星号(\*)返回全部记录数量。 - Wildcard (\*) can be used to represent all columns, it's used to get the number of all rows
- 针对同一表的（不包含 NULL 值）字段查询结果均相同。 - The number of non-NULL values will be returned if this function is used on a specific column
- 如果统计对象是具体的列，则返回该列中非 NULL 值的记录数量。
**示例**： **Examples**:
``` ```
taos> SELECT COUNT(*), COUNT(voltage) FROM meters; taos> SELECT COUNT(*), COUNT(voltage) FROM meters;
...@@ -49,15 +48,15 @@ Query OK, 1 row(s) in set (0.001075s) ...@@ -49,15 +48,15 @@ Query OK, 1 row(s) in set (0.001075s)
SELECT AVG(field_name) FROM tb_name [WHERE clause]; SELECT AVG(field_name) FROM tb_name [WHERE clause];
``` ```
**功能说明**：统计表/超级表中某列的平均值。 **Description**:Get the average value of a column in a table or stable
**返回数据类型**：双精度浮点数 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
**示例**： **Examples**:
``` ```
taos> SELECT AVG(current), AVG(voltage), AVG(phase) FROM meters; taos> SELECT AVG(current), AVG(voltage), AVG(phase) FROM meters;
...@@ -79,17 +78,17 @@ Query OK, 1 row(s) in set (0.000943s) ...@@ -79,17 +78,17 @@ Query OK, 1 row(s) in set (0.000943s)
SELECT TWA(field_name) FROM tb_name WHERE clause; SELECT TWA(field_name) FROM tb_name WHERE clause;
``` ```
**功能说明**：时间加权平均函数。统计表中某列在一段时间内的时间加权平均。 **Description**:Time weighted average on a specific column within a time range
**返回数据类型**：双精度浮点数 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 版本开始，TWA 函数可以在由 GROUP BY 划分出单独时间线的情况下用于超级表（也即 GROUP BY tbname）。 - From version 2.1.3.0, function TWA can be used on stble with `GROUP BY`, i.e. timelines generated by `GROUP BY tbname` on a stable.
### IRATE ### IRATE
...@@ -97,17 +96,17 @@ SELECT TWA(field_name) FROM tb_name WHERE clause; ...@@ -97,17 +96,17 @@ SELECT TWA(field_name) FROM tb_name WHERE clause;
SELECT IRATE(field_name) FROM tb_name WHERE clause; 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.
**返回数据类型**：双精度浮点数 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 ### SUM
...@@ -115,15 +114,15 @@ SELECT IRATE(field_name) FROM tb_name WHERE clause; ...@@ -115,15 +114,15 @@ SELECT IRATE(field_name) FROM tb_name WHERE clause;
SELECT SUM(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; taos> SELECT SUM(current), SUM(voltage), SUM(phase) FROM meters;
...@@ -145,15 +144,15 @@ Query OK, 1 row(s) in set (0.000980s) ...@@ -145,15 +144,15 @@ Query OK, 1 row(s) in set (0.000980s)
SELECT STDDEV(field_name) FROM tb_name [WHERE clause]; 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; taos> SELECT STDDEV(current) FROM d1001;
...@@ -169,15 +168,15 @@ Query OK, 1 row(s) in set (0.000915s) ...@@ -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]; SELECT LEASTSQUARES(field_name, start_val, step_val) FROM tb_name [WHERE clause];
``` ```
**功能说明**：统计表中某列的值是主键（时间戳）的拟合直线方程。start_val 是自变量初始值，step_val 是自变量的步长值。 **Description**:统计表中某列的值是主键（时间戳）的拟合直线方程.start_val 是自变量初始值,step_val 是自变量的步长值.
**返回数据类型**：字符串表达式（斜率, 截距）。 **Return value type**:A string in the format of "(slope, intercept)"
**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。 **Applicable column types**:Data types except for timestamp, binary, nchar and bool
**适用于**：表。 **Applicable table types**:table only
**示例**： **Examples**:
``` ```
taos> SELECT LEASTSQUARES(current, 1, 1) FROM d1001; taos> SELECT LEASTSQUARES(current, 1, 1) FROM d1001;
...@@ -193,17 +192,17 @@ Query OK, 1 row(s) in set (0.000921s) ...@@ -193,17 +192,17 @@ Query OK, 1 row(s) in set (0.000921s)
SELECT MODE(field_name) FROM tb_name [WHERE clause]; SELECT MODE(field_name) FROM tb_name [WHERE clause];
``` ```
**功能说明**：返回出现频率最高的值，若存在多个频率相同的最高值，输出空。不能匹配标签、时间戳输出。 **Description**:The value which has the highest frequency of occurrence. NULL is returned if there are multiple values which have highest frequency of occurrence. It can't be used on timestamp column or tags.
**返回数据类型**：同应用的字段。 **Return value type**:Same as the data type of the column being operated
**应用字段**：适合于除时间主列外的任何类型字段。 **Applicable column types**:Data types except for timestamp
**使用说明**：由于返回数据量未知，考虑到内存因素，为了函数可以正常返回结果，建议不重复的数据量在 10 万级别，否则会报错。 **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; taos> select voltage from d002;
...@@ -228,17 +227,17 @@ Query OK, 1 row(s) in set (0.019393s) ...@@ -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 HYPERLOGLOG(field_name) FROM { tb_name | stb_name } [WHERE clause];
``` ```
**功能说明**： **Description**:The cardinal number of a specific column is returned by using hyperloglog algorithm.
- 采用 hyperloglog 算法，返回某列的基数。该算法在数据量很大的情况下，可以明显降低内存的占用，但是求出来的基数是个估算值，标准误差（标准误差是多次实验，每次的平均数的标准差，不是与真实结果的误差）为 0.81%。
- 在数据量较少的时候该算法不是很准确，可以使用 select count(data) from (select unique(col) as data from table) 的方法。
**返回结果类型**：整形。 **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; taos> select dbig from shll;
...@@ -261,9 +260,9 @@ taos> select hyperloglog(dbig) from shll; ...@@ -261,9 +260,9 @@ taos> select hyperloglog(dbig) from shll;
Query OK, 1 row(s) in set (0.008388s) Query OK, 1 row(s) in set (0.008388s)
``` ```
## 选择函数 ## Selection Functions
在使用所有的选择函数的时候，可以同时指定输出 ts 列或标签列（包括 tbname），这样就可以方便地知道被选出的值是源于哪个数据行的。 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 ### MIN
...@@ -271,15 +270,15 @@ Query OK, 1 row(s) in set (0.008388s) ...@@ -271,15 +270,15 @@ Query OK, 1 row(s) in set (0.008388s)
SELECT MIN(field_name) FROM {tb_name | stb_name} [WHERE clause]; SELECT MIN(field_name) FROM {tb_name | stb_name} [WHERE clause];
``` ```
**功能说明**：统计表/超级表中某列的值最小值。 **Description**:The minimum value of a specific column in a table or stable
**返回数据类型**：同应用的字段。 **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; taos> SELECT MIN(current), MIN(voltage) FROM meters;
...@@ -301,15 +300,15 @@ Query OK, 1 row(s) in set (0.000950s) ...@@ -301,15 +300,15 @@ Query OK, 1 row(s) in set (0.000950s)
SELECT MAX(field_name) FROM { tb_name | stb_name } [WHERE clause]; 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; taos> SELECT MAX(current), MAX(voltage) FROM meters;
...@@ -331,21 +330,21 @@ Query OK, 1 row(s) in set (0.000987s) ...@@ -331,21 +330,21 @@ Query OK, 1 row(s) in set (0.000987s)
SELECT FIRST(field_name) FROM { tb_name | stb_name } [WHERE clause]; 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(\*)； - FIRST(\*) can be used to get the first non-null value of all columns
- 如果结果集中的某列全部为 NULL 值，则该列的返回结果也是 NULL； - NULL will be returned if all the values of the specified column are all NULL
- 如果结果集中所有列全部为 NULL 值，则不返回结果。 - No result will NOT be returned if all the columns in the result set are all NULL
**示例**： **Examples**:
``` ```
taos> SELECT FIRST(*) FROM meters; taos> SELECT FIRST(*) FROM meters;
...@@ -367,22 +366,21 @@ Query OK, 1 row(s) in set (0.001023s) ...@@ -367,22 +366,21 @@ Query OK, 1 row(s) in set (0.001023s)
SELECT LAST(field_name) FROM { tb_name | stb_name } [WHERE clause]; 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
**适用于**：表、超级表。 **Applicable column types**:Any data type
**使用说明**: **Applicable table types**:table, stable
- 如果要返回各个列的最后（时间戳最大）一个非 NULL 值，可以使用 LAST(\*)； **More explanations**:
- 如果结果集中的某列全部为 NULL 值，则该列的返回结果也是 NULL；如果结果集中所有列全部为 NULL 值，则不返回结果。
- 在用于超级表时，时间戳完全一样且同为最大的数据行可能有多个，那么会从中随机返回一条，而并不保证多次运行所挑选的数据行必然一致。
- 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; taos> SELECT LAST(*) FROM meters;
...@@ -404,21 +402,21 @@ Query OK, 1 row(s) in set (0.000843s) ...@@ -404,21 +402,21 @@ Query OK, 1 row(s) in set (0.000843s)
SELECT TOP(field_name, K) FROM { tb_name | stb_name } [WHERE clause]; SELECT TOP(field_name, K) FROM { tb_name | stb_name } [WHERE clause];
``` ```
**功能说明**： 统计表/超级表中某列的值最大 _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； - _k_ must be in range [1,100]
- 系统同时返回该记录关联的时间戳列； - The timestamp associated with the selected values are returned too
- 限制：TOP 函数不支持 FILL 子句。 - Can't be used with `FILL`
**示例**： **Examples**:
``` ```
taos> SELECT TOP(current, 3) FROM meters; taos> SELECT TOP(current, 3) FROM meters;
...@@ -443,21 +441,21 @@ Query OK, 2 row(s) in set (0.000810s) ...@@ -443,21 +441,21 @@ Query OK, 2 row(s) in set (0.000810s)
SELECT BOTTOM(field_name, K) FROM { tb_name | stb_name } [WHERE clause]; SELECT BOTTOM(field_name, K) FROM { tb_name | stb_name } [WHERE clause];
``` ```
**功能说明**：统计表/超级表中某列的值最小 _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； - _k_ must be in range [1,100]
- 系统同时返回该记录关联的时间戳列； - The timestamp associated with the selected values are returned too
- 限制：BOTTOM 函数不支持 FILL 子句。 - Can't be used with `FILL`
**示例**： **Examples**:
``` ```
taos> SELECT BOTTOM(voltage, 2) FROM meters; taos> SELECT BOTTOM(voltage, 2) FROM meters;
...@@ -481,17 +479,17 @@ Query OK, 2 row(s) in set (0.000793s) ...@@ -481,17 +479,17 @@ Query OK, 2 row(s) in set (0.000793s)
SELECT PERCENTILE(field_name, P) FROM { tb_name } [WHERE clause]; 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
**适用于**：表。 **Applicable table types**: table
**使用说明**：*P*值取值范围 0≤*P*≤100，为 0 的时候等同于 MIN，为 100 的时候等同于 MAX。 **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; taos> SELECT PERCENTILE(current, 20) FROM d1001;
...@@ -508,22 +506,21 @@ SELECT APERCENTILE(field_name, P[, algo_type]) ...@@ -508,22 +506,21 @@ SELECT APERCENTILE(field_name, P[, algo_type])
FROM { tb_name | stb_name } [WHERE clause] FROM { tb_name | stb_name } [WHERE clause]
``` ```
**功能说明**：统计表/超级表中指定列的值百分比分位数，与 PERCENTILE 函数相似，但是返回近似结果。 **Description**: Similar to `PERCENTILE`, but a simulated result is 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
**适用于**：表、超级表。 **Applicable table types**: table, stable
**使用说明** **More explanations**
- **P**值有效取值范围 0≤P≤100，为 0 的时候等同于 MIN，为 100 的时候等同于 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**的有效输入：**default** 和 **t-digest** - **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")`.
- 用于指定计算近似分位数的算法。可不提供第三个参数的输入，此时将使用 default 的算法进行计算，即 apercentile(column_name, 50, "default") 与 apercentile(column_name, 50) 等价。 - When `t-digest` is used, `t-digest` sampling is used to calculate. It can be used from version 2.2.0.0.
- 当使用“t-digest”参数的时候，将使用 t-digest 方式采样计算近似分位数。但该参数指定计算算法的功能从 2.2.0.x 版本开始支持，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; taos> SELECT APERCENTILE(current, 20) FROM d1001;
...@@ -551,20 +548,20 @@ Query OK, 1 row(s) in set (0.011639s) ...@@ -551,20 +548,20 @@ Query OK, 1 row(s) in set (0.011639s)
SELECT LAST_ROW(field_name) FROM { tb_name | stb_name }; SELECT LAST_ROW(field_name) FROM { tb_name | stb_name };
``` ```
**功能说明**：返回表/超级表的最后一条记录。 **Description**: The last row of a table or stable
**返回数据类型**：同应用的字段。 **Return value type**: Same as the column being operated
**应用字段**：所有字段。 **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.
- 不能与 INTERVAL 一起使用。 - Can't be used with `INTERVAL`.
**示例**： **Examples**:
``` ```
taos> SELECT LAST_ROW(current) FROM meters; taos> SELECT LAST_ROW(current) FROM meters;
...@@ -580,85 +577,83 @@ SELECT LAST_ROW(field_name) FROM { tb_name | stb_name }; ...@@ -580,85 +577,83 @@ SELECT LAST_ROW(field_name) FROM { tb_name | stb_name };
Query OK, 1 row(s) in set (0.001042s) Query OK, 1 row(s) in set (0.001042s)
``` ```
### INTERP [2.3.1 及之后的版本] ### INTERP [From version 2.3.1]
``` ```
SELECT INTERP(field_name) FROM { tb_name | stb_name } [WHERE where_condition] [ RANGE(timestamp1,timestamp2) ] [EVERY(interval)] [FILL ({ VALUE | PREV | NULL | LINEAR | NEXT})]; SELECT INTERP(field_name) FROM { tb_name | stb_name } [WHERE where_condition] [ RANGE(timestamp1,timestamp2) ] [EVERY(interval)] [FILL ({ VALUE | PREV | NULL | LINEAR | NEXT})];
``` ```
**功能说明**：返回表/超级表的指定时间截面指定列的记录值（插值）。 **Description**: The value that matches the specified timestamp range is returned, if existing; or an interpolation value is returned.
**返回数据类型**：同字段类型。
**应用字段**：数值型字段。 **Return value type**: same as the column being operated
**适用于**：表、超级表、嵌套查询。 **Applicable column types**: Numeric data types
**Applicable table types**: table, stable, nested query
**使用说明** **More explanations**
- INTERP 用于在指定时间断面获取指定列的记录值，如果该时间断面不存在符合条件的行数据，那么会根据 FILL 参数的设定进行插值。 - `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.
- INTERP 的输入数据为指定列的数据，可以通过条件语句（where 子句）来对原始列数据进行过滤，如果没有指定过滤条件则输入为全部数据。 - 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.
- INTERP 的输出时间范围根据 RANGE(timestamp1,timestamp2)字段来指定，需满足 timestamp1<=timestamp2。其中 timestamp1（必选值）为输出时间范围的起始值，即如果 timestamp1 时刻符合插值条件则 timestamp1 为输出的第一条记录，timestamp2（必选值）为输出时间范围的结束值，即输出的最后一条记录的 timestamp 不能大于 timestamp2。如果没有指定 RANGE，那么满足过滤条件的输入数据中第一条记录的 timestamp 即为 timestamp1，最后一条记录的 timestamp 即为 timestamp2，同样也满足 timestamp1 <= timestamp2。 - 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.
- INTERP 根据 EVERY 字段来确定输出时间范围内的结果条数，即从 timestamp1 开始每隔固定长度的时间（EVERY 值）进行插值。如果没有指定 EVERY，则默认窗口大小为无穷大，即从 timestamp1 开始只有一个窗口。 - 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.
- INTERP 根据 FILL 字段来决定在每个符合输出条件的时刻如何进行插值，如果没有 FILL 字段则默认不插值，即输出为原始记录值或不输出（原始记录不存在）。 - 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 只能在一个时间序列内进行插值，因此当作用于超级表时必须跟 group by tbname 一起使用，当作用嵌套查询外层时内层子查询不能含 GROUP BY 信息。 - `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.
- INTERP 的插值结果不受 ORDER BY timestamp 的影响，ORDER BY timestamp 只影响输出结果的排序。 - The result of `INTERP` is not influenced by `ORDER BY TIMESTAMP`, which impacts the output order only..
**SQL示例（基于文档中广泛使用的电表 schema )**： **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:
``` ```
taos> SELECT INTERP(current) FROM t1 RANGE('2017-7-14 18:40:00','2017-7-14 18:40:00') FILL(LINEAR); taos> SELECT INTERP(current) FROM t1 RANGE('2017-7-14 18:40:00','2017-7-14 18:40:00') FILL(LINEAR);
``` ```
- 在2017-07-14 18:00:00到2017-07-14 19:00:00间每隔5秒钟进行取值(不插值) - Get an 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); taos> SELECT INTERP(current) FROM t1 RANGE('2017-7-14 18:00:00','2017-7-14 19:00:00') EVERY(5s);
``` ```
- 在2017-07-14 18:00:00到2017-07-14 19:00:00间每隔5秒钟进行线性插值 - 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); taos> SELECT INTERP(current) FROM t1 RANGE('2017-7-14 18:00:00','2017-7-14 19:00:00') EVERY(5s) FILL(LINEAR);
``` ```
- 在所有时间范围内每隔 5 秒钟进行向后插值 - Backward interpolation every 5 seconds
``` ```
taos> SELECT INTERP(current) FROM t1 EVERY(5s) FILL(NEXT); taos> SELECT INTERP(current) FROM t1 EVERY(5s) FILL(NEXT);
``` ```
- 根据 2017-07-14 17:00:00 到 2017-07-14 20:00:00 间的数据进行从 2017-07-14 18:00:00 到 2017-07-14 19:00:00 间每隔 5 秒钟进行线性插值 - 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); 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 [2.3.1 之前的版本] ### INTERP [Prior to version 2.3.1]
``` ```
SELECT INTERP(field_name) FROM { tb_name | stb_name } WHERE ts='timestamp' [FILL ({ VALUE | PREV | NULL | LINEAR | NEXT})]; 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
**返回数据类型**：同字段类型。 **Return value type**: Same as the column being operated
**应用字段**：数值型字段。 **Applicable column types**: Numeric data type
**适用于**：表、超级表。 **Applicable table types**: table, stable
**使用说明**: **More explanations**:
- 从 2.0.15.0 及以后版本可用 - It can be used from version 2.0.15.0
- INTERP 必须指定时间断面，如果该时间断面不存在直接对应的数据，那么会根据 FILL 参数的设定进行插值。此外，条件语句里面可附带筛选条件，例如标签、tbname。 - 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.
- INTERP 查询要求查询的时间区间必须位于数据集合（表）的所有记录的时间范围之内。如果给定的时间戳位于时间范围之外，即使有插值指令，仍然不返回结果。 - 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 函数查询只能够针对一个时间点进行查询，如果需要返回等时间间隔的断面数据，可以通过 INTERP 配合 EVERY 的方式来进行查询处理（而不是使用 INTERVAL），其含义是每隔固定长度的时间进行插值 - `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'; 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 ...@@ -668,7 +663,7 @@ SELECT INTERP(field_name) FROM { tb_name | stb_name } WHERE ts='timestamp' [FILL
Query OK, 1 row(s) in set (0.002652s) Query OK, 1 row(s) in set (0.002652s)
``` ```
如果给定的时间戳无对应的数据，在不指定插值生成策略的情况下，不会返回结果，如果指定了插值策略，会根据插值策略返回结果。 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'; 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 ...@@ -681,7 +676,7 @@ SELECT INTERP(field_name) FROM { tb_name | stb_name } WHERE ts='timestamp' [FILL
Query OK, 1 row(s) in set (0.003056s) Query OK, 1 row(s) in set (0.003056s)
``` ```
如下所示代码表示在时间区间 `['2017-7-14 18:40:00', '2017-7-14 18:40:00.014']` 中每隔 5 毫秒 进行一次断面计算。 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); 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 ...@@ -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]; 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; taos> select ts,dbig from tail2;
...@@ -736,20 +731,20 @@ Query OK, 2 row(s) in set (0.002307s) ...@@ -736,20 +731,20 @@ Query OK, 2 row(s) in set (0.002307s)
SELECT UNIQUE(field_name) FROM {tb_name | stb_name} [WHERE clause]; SELECT UNIQUE(field_name) FROM {tb_name | stb_name} [WHERE clause];
``` ```
**功能说明**：返回该列的数值首次出现的值。该函数功能与 distinct 相似，但是可以匹配标签和时间戳信息。可以针对除时间列以外的字段进行查询，可以匹配标签和时间戳，其中的标签和时间戳是第一次出现时刻的标签和时间戳。 **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
**支持版本**：2.6.0.0 及之后的版本。 **支持版本**: From version 2.6.0.0
**使用说明**: **More explanations**:
- 该函数可以应用在普通表和超级表上。不能和窗口操作一起使用，例如 interval/state_window/session_window 。 - It can be used against table or stable, but can't be used together with time window, like `interval`, `state_window` or `session_window` .
- 由于返回数据量未知，考虑到内存因素，为了函数可以正常返回结果，建议不重复的数据量在 10 万级别，否则会报错。 - 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**:
``` ```
taos> select ts,voltage from unique1; taos> select ts,voltage from unique1;
...@@ -776,38 +771,38 @@ ts | unique(voltage) | ...@@ -776,38 +771,38 @@ ts | unique(voltage) |
Query OK, 5 row(s) in set (0.108458s) Query OK, 5 row(s) in set (0.108458s)
``` ```
## 计算函数 ## Scalar functions
### DIFF ### DIFF
```sql ```sql
SELECT {DIFF(field_name, ignore_negative) | DIFF(field_name)} FROM tb_name [WHERE clause]; SELECT {DIFF(field_name, ignore_negative) | DIFF(field_name)} FROM tb_name [WHERE clause];
``` ```
**功能说明**：统计表中某列的值与前一行对应值的差。 ignore_negative 取值为 0|1 , 可以不填，默认值为 0. 不忽略负值。ignore_negative 为 1 时表示忽略负数。 **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**:
- 输出结果行数是范围内总行数减一，第一行没有结果输出。 - The number of result rows is the number of rows subtracted by one, no output for the first row
- 从 2.1.3.0 版本开始，DIFF 函数可以在由 GROUP BY 划分出单独时间线的情况下用于超级表（也即 GROUP BY tbname）。 - From version 2.1.30, `DIFF` can be used on stable with `GROUP by tbname`
- 从 2.6.0 开始，DIFF 函数支持 ignore_negative 参数 - From version 2.6.0, `ignore_negative` parameter is supported
**示例**： **Examples**:
```sql ```sql
taos> SELECT DIFF(current) FROM d1001; taos> SELECT DIFF(current) FROM d1001;
ts | diff(current) | ts | diff(current) |
================================================= =================================================
2018-10-03 14:38:15.000 | 2.30000 | 2018-10-03 14:38:15.000 | 2.30000 |
2018-10-03 14:38:16.800 | -0.30000 | 2018-10-03 14:38:16.800 | -0.30000 |
Query OK, 2 row(s) in set (0.001162s) Query OK, 2 row(s) in set (0.001162s)
``` ```
### DERIVATIVE ### DERIVATIVE
...@@ -815,20 +810,20 @@ Query OK, 5 row(s) in set (0.108458s) ...@@ -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]; SELECT DERIVATIVE(field_name, time_interval, ignore_negative) FROM tb_name [WHERE clause];
``` ```
**功能说明**：统计表中某列数值的单位变化率。其中单位时间区间的长度可以通过 time_interval 参数指定，最小可以是 1 秒（1s）；ignore_negative 参数的值可以是 0 或 1，为 1 时表示忽略负值。 **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 及以后版本可用；输出结果行数是范围内总行数减一，第一行没有结果输出。 - 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.\
- DERIVATIVE 函数可以在由 GROUP BY 划分出单独时间线的情况下用于超级表（也即 GROUP BY tbname）。 - It can be used together with `GROUP BY tbname` against a stable.
**示例**： **Examples**:
``` ```
taos> select derivative(current, 10m, 0) from t1; taos> select derivative(current, 10m, 0) from t1;
...@@ -848,17 +843,17 @@ Query OK, 5 row(s) in set (0.004883s) ...@@ -848,17 +843,17 @@ Query OK, 5 row(s) in set (0.004883s)
SELECT SPREAD(field_name) FROM { tb_name | stb_name } [WHERE clause]; SELECT SPREAD(field_name) FROM { tb_name | stb_name } [WHERE clause];
``` ```
**功能说明**：统计表/超级表中某列的最大值和最小值之差。 **Description**: The difference between the max and the min of a specific column
**返回数据类型**：双精度浮点数。 **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; taos> SELECT SPREAD(voltage) FROM meters;
...@@ -880,20 +875,21 @@ Query OK, 1 row(s) in set (0.000836s) ...@@ -880,20 +875,21 @@ Query OK, 1 row(s) in set (0.000836s)
SELECT CEIL(field_name) FROM { tb_name | stb_name } [WHERE clause]; SELECT CEIL(field_name) FROM { tb_name | stb_name } [WHERE clause];
``` ```
**功能说明**：获得指定列的向上取整数的结果。 **Description**: The round up value of a specific column
**返回结果类型**：与指定列的原始数据类型一致。例如，如果指定列的原始数据类型为 Float，那么返回的数据类型也为 Float；如果指定列的原始数据类型为 Double，那么返回的数据类型也为 Double。 **Return value type**: Same as the column being used
**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列，无论 tag 列的类型是什么类型。 **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**:
- 支持 +、-、\*、/ 运算，如 ceil(col1) + ceil(col2)。 - Can't be used on any tags of any type
- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 - Arithmetic operation can be performed on the result of `ceil` function
- Can't be used with aggregate functions
### FLOOR ### FLOOR
...@@ -901,8 +897,9 @@ SELECT CEIL(field_name) FROM { tb_name | stb_name } [WHERE clause]; ...@@ -901,8 +897,9 @@ SELECT CEIL(field_name) FROM { tb_name | stb_name } [WHERE clause];
SELECT FLOOR(field_name) FROM { tb_name | stb_name } [WHERE clause]; SELECT FLOOR(field_name) FROM { tb_name | stb_name } [WHERE clause];
``` ```
**功能说明**：获得指定列的向下取整数的结果。 **Description**: The round down value of a specific column
其他使用说明参见 CEIL 函数描述。
**More explanations**: The restrictions are same as `CEIL` function.
### ROUND ### ROUND
...@@ -910,8 +907,9 @@ SELECT FLOOR(field_name) FROM { tb_name | stb_name } [WHERE clause]; ...@@ -910,8 +907,9 @@ SELECT FLOOR(field_name) FROM { tb_name | stb_name } [WHERE clause];
SELECT ROUND(field_name) FROM { tb_name | stb_name } [WHERE clause]; SELECT ROUND(field_name) FROM { tb_name | stb_name } [WHERE clause];
``` ```
**功能说明**：获得指定列的四舍五入的结果。 **Description**: The round value of a specific column.
其他使用说明参见 CEIL 函数描述。
**More explanations**: The restrictions are same as `CEIL` function.
### CSUM ### CSUM
...@@ -919,21 +917,24 @@ SELECT ROUND(field_name) FROM { tb_name | stb_name } [WHERE clause]; ...@@ -919,21 +917,24 @@ SELECT ROUND(field_name) FROM { tb_name | stb_name } [WHERE clause];
SELECT CSUM(field_name) FROM { tb_name | stb_name } [WHERE clause] SELECT CSUM(field_name) FROM { tb_name | stb_name } [WHERE clause]
``` ```
**功能说明**：累加和（Cumulative sum），输出行与输入行数相同。 **Description**: The cumulative sum of each row for a specific column. The number of output rows is same as that of the input rows.
**Return value type**: Long integer for integers; Double for floating points. Timestamp is returned for each row.
**返回结果类型**： 输入列如果是整数类型返回值为长整型 （int64_t），浮点数返回值为双精度浮点数（Double）。无符号整数类型返回值为无符号长整型（uint64_t）。 返回结果中同时带有每行记录对应的时间戳。 **Applicable data types**: Data types except for timestamp, binary, nchar, and bool
**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在标签之上。 **Applicable table types**: table, stable
**嵌套子查询支持**： 适用于内层查询和外层查询。 **Applicable nested query**: Inner query and Outer query
**使用说明**： **More explanations**:
- 不支持 +、-、*、/ 运算，如 csum(col1) + csum(col2)。 - Can't be used on tags when it's used on stable
- 只能与聚合（Aggregation）函数一起使用。 该函数可以应用在普通表和超级表上。 - Arithmetic operation can't be performed on the result of `csum` function
- 使用在超级表上的时候，需要搭配 Group by tbname使用，将结果强制规约到单个时间线。 - 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
**支持版本**： 从2.3.0.x开始支持 **Applicable versions**: From 2.3.0.x
### MAVG ### MAVG
...@@ -941,21 +942,24 @@ SELECT ROUND(field_name) FROM { tb_name | stb_name } [WHERE clause]; ...@@ -941,21 +942,24 @@ SELECT ROUND(field_name) FROM { tb_name | stb_name } [WHERE clause];
SELECT MAVG(field_name, K) FROM { tb_name | stb_name } [WHERE clause] SELECT MAVG(field_name, K) FROM { tb_name | stb_name } [WHERE clause]
``` ```
**功能说明**： 计算连续 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
**适用数据类型**： 不能应用在 timestamp、binary、nchar、bool 类型上；在超级表查询中使用时，不能应用在标签之上。 **Applicable nested query**: Inner query and Outer query
**嵌套子查询支持**： 适用于内层查询和外层查询。 **Applicable table types**: table, stable
**使用说明**： **More explanations**:
- 不支持 +、-、*、/ 运算，如 mavg(col1, k1) + mavg(col2, k1); - Arithmetic operation can't be performed on the result of `MAVG`.
- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用； - Can only be used with data columns, can't be used with tags.
- 该函数可以应用在普通表和超级表上；使用在超级表上的时候，需要搭配 Group by tbname使用，将结果强制规约到单个时间线。 - Can't be used with aggregate functions.\（Aggregation）函数一起使用；
- Must be used with `GROUP BY tbname` when it's used on a stable to force the result on each single timeline.该
**支持版本**： 从2.3.0.x开始支持 **Applicable versions**: From 2.3.0.x
### SAMPLE ### SAMPLE
...@@ -963,439 +967,504 @@ SELECT ROUND(field_name) FROM { tb_name | stb_name } [WHERE clause]; ...@@ -963,439 +967,504 @@ SELECT ROUND(field_name) FROM { tb_name | stb_name } [WHERE clause];
SELECT SAMPLE(field_name, K) FROM { tb_name | stb_name } [WHERE clause] SELECT SAMPLE(field_name, K) FROM { tb_name | stb_name } [WHERE clause]
``` ```
**功能说明**： 获取数据的 k 个采样值。参数 k 的合法输入范围是 1≤ k ≤ 1000。 **Description**: _k_ sampling values of a specific column. The applicable range of _k_ is [1,10000]
**返回结果类型**： 同原始数据类型， 返回结果中带有该行记录的时间戳。 **Return value type**: Same as the column being operated plus the associated timestamp
**适用数据类型**： 在超级表查询中使用时，不能应用在标签之上。 **Applicable data types**: Any data type except for tags of stable
**嵌套子查询支持**： 适用于内层查询和外层查询。 **Applicable table types**: table, stable
**使用说明**： **Applicable nested query**: Inner query and Outer query
- 不能参与表达式计算；该函数可以应用在普通表和超级表上； **More explanations**:
- 使用在超级表上的时候，需要搭配 Group by tbname 使用，将结果强制规约到单个时间线。
**支持版本**： 从2.3.0.x开始支持 - 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**: From 2.3.0.x
### ASIN ### ASIN
```sql ```sql
SELECT ASIN(field_name) FROM { tb_name | stb_name } [WHERE clause] 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
**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL **Applicable table types**: table, stable
**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 **Applicable nested query**: Inner query and Outer query
**嵌套子查询支持**：适用于内层查询和外层查询。 **Applicable versions**: From 2.6.0.0
**使用说明**： **More explanations**:
- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 - Can't be used with tags
- 该函数可以应用在普通表和超级表上。 - Can't be used with aggregate functions
- 版本2.6.0.x后支持
### ACOS ### ACOS
```sql ```sql
SELECT ACOS(field_name) FROM { tb_name | stb_name } [WHERE clause] SELECT ACOS(field_name) FROM { tb_name | stb_name } [WHERE clause]
``` ```
**Description**: The anti-cosine of a specific column 获
**功能说明**：获得指定列的反余弦结果 **Return value type**: ouble if the input value is not NULL; or NULL if the input value is NULL
**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL **Applicable data types**: Data types except for timestamp, binary, nchar, bool
**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 **Applicable table types**: table, stable
**嵌套子查询支持**：适用于内层查询和外层查询。 **Applicable nested query**: Inner query and Outer query
**使用说明**： **Applicable versions**: From 2.6.0.0
- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 **More explanations**:
- 该函数可以应用在普通表和超级表上。
- 版本2.6.0.x后支持 - Can't be used with tags
- Can't be used with aggregate functions
### ATAN ### ATAN
```sql ```sql
SELECT ATAN(field_name) FROM { tb_name | stb_name } [WHERE clause] SELECT ATAN(field_name) FROM { tb_name | stb_name } [WHERE clause]
``` ```
**功能说明**：获得指定列的反正切结果 **Description**: anti-tangent of a specific column
**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL **Description**: The anti-cosine of a specific column 获
**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 **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
- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 **Applicable nested query**: Inner query and Outer query
- 该函数可以应用在普通表和超级表上。
- 版本2.6.0.x后支持 **Applicable versions**: From 2.6.0.0
**More explanations**:
- Can't be used with tags
- Can't be used with aggregate functions
### SIN ### SIN
```sql ```sql
SELECT SIN(field_name) FROM { tb_name | stb_name } [WHERE clause] 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
**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL **Applicable data types**: Data types except for timestamp, binary, nchar, bool
**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 **Applicable table types**: table, stable
**嵌套子查询支持**：适用于内层查询和外层查询。 **Applicable nested query**: Inner query and Outer query
**使用说明**： **Applicable versions**: From 2.6.0.0
- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 **More explanations**:
- 该函数可以应用在普通表和超级表上。
- 版本2.6.0.x后支持 - Can't be used with tags
- Can't be used with aggregate functions
### COS ### COS
```sql ```sql
SELECT COS(field_name) FROM { tb_name | stb_name } [WHERE clause] SELECT COS(field_name) FROM { tb_name | stb_name } [WHERE clause]
``` ```
**功能说明**：获得指定列的余弦结果 **Description**: The cosine of a specific column
**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL **Description**: The anti-cosine of a specific column 获
**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 **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
- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 **Applicable nested query**: Inner query and Outer query
- 该函数可以应用在普通表和超级表上。
- 版本2.6.0.x后支持 **Applicable versions**: From 2.6.0.0
**More explanations**:
- Can't be used with tags
- Can't be used with aggregate functions
### TAN ### TAN
```sql ```sql
SELECT TAN(field_name) FROM { tb_name | stb_name } [WHERE clause] 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
**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL **Applicable data types**: Data types except for timestamp, binary, nchar, bool
**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 **Applicable table types**: table, stable
**嵌套子查询支持**：适用于内层查询和外层查询。 **Applicable nested query**: Inner query and Outer query
**使用说明**： **Applicable versions**: From 2.6.0.0
- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 **More explanations**:
- 该函数可以应用在普通表和超级表上。
- 版本2.6.0.x后支持 - Can't be used with tags
- Can't be used with aggregate functions
### POW ### POW
```sql ```sql
SELECT POW(field_name, power) FROM { tb_name | stb_name } [WHERE clause] SELECT POW(field_name, power) FROM { tb_name | stb_name } [WHERE clause]
``` ```
**功能说明**：获得指定列的指数为 power 的幂 **Description**: The power of a specific column with `power` as the index
**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL **Return value type**: Double if the input value is not NULL; or NULL if the input value is NULL
**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 **Applicable data types**: Data types except for timestamp, binary, nchar, bool
**嵌套子查询支持**：适用于内层查询和外层查询。 **Applicable table types**: table, stable
**使用说明**： **Applicable nested query**: Inner query and Outer query
- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 **Applicable versions**: From 2.6.0.0
- 该函数可以应用在普通表和超级表上。
- 版本2.6.0.x后支持 **More explanations**:
- Can't be used with tags
- Can't be used with aggregate functions
### LOG ### LOG
```sql ```sql
SELECT LOG(field_name, base) FROM { tb_name | stb_name } [WHERE clause] 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
**功能说明**：获得指定列对于底数 base 的对数 **Applicable data types**: Data types except for timestamp, binary, nchar, bool
**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL **Applicable table types**: table, stable
**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 **Applicable nested query**: Inner query and Outer query
**嵌套子查询支持**：适用于内层查询和外层查询。 **Applicable versions**: From 2.6.0.0
**使用说明**： **More explanations**:
- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 - Can't be used with tags
- 该函数可以应用在普通表和超级表上。 - Can't be used with aggregate functions
- 版本2.6.0.x后支持
### ABS ### ABS
```sql ```sql
SELECT ABS(field_name) FROM { tb_name | stb_name } [WHERE clause] 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
**返回结果类型**：如果输入值为整数，输出值是 UBIGINT 类型。如果输入值是 FLOAT/DOUBLE 数据类型，输出值是 DOUBLE 数据类型。 **Applicable table types**: table, stable
**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 **Applicable nested query**: Inner query and Outer query
**嵌套子查询支持**：适用于内层查询和外层查询。 **Applicable versions**: From 2.6.0.0
**使用说明**： **More explanations**:
- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 - Can't be used with tags
- 该函数可以应用在普通表和超级表上。 - Can't be used with aggregate functions
- 版本2.6.0.x后支持
### SQRT ### SQRT
```sql ```sql
SELECT SQRT(field_name) FROM { tb_name | stb_name } [WHERE clause] 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
**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL **Applicable data types**: Data types except for timestamp, binary, nchar, bool
**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 **Applicable table types**: table, stable
**嵌套子查询支持**：适用于内层查询和外层查询。 **Applicable nested query**: Inner query and Outer query
**使用说明**： **Applicable versions**: From 2.6.0.0
- 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 **More explanations**:
- 该函数可以应用在普通表和超级表上。
- 版本2.6.0.x后支持 - Can't be used with tags
- Can't be used with aggregate functions
### CAST ### CAST
```sql ```sql
SELECT CAST(expression AS type_name) FROM { tb_name | stb_name } [WHERE clause] SELECT CAST(expression AS type_name) FROM { tb_name | stb_name } [WHERE clause]
``` ```
**功能说明**：数据类型转换函数，输入参数 expression 支持普通列、常量、标量函数及它们之间的四则运算，不支持 tag 列，只适用于 select 子句中。 **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.
**返回结果类型**：CAST 中指定的类型（type_name）。 **Return value type**: The type specified by parameter `type_name`
**适用数据类型**： **Applicable data types**:
- 输入参数 expression 的类型可以是除 JSON 外目前所有类型字段（BOOL/TINYINT/SMALLINT/INT/BIGINT/FLOAT/DOUBLE/BINARY(M)/TIMESTAMP/NCHAR(M)/TINYINT UNSIGNED/SMALLINT UNSIGNED/INT UNSIGNED/BIGINT UNSIGNED）; - 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
- 输出目标类型只支持 BIGINT/BINARY(N)/TIMESTAMP/NCHAR(N)/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**:
- 如果输入值为NULL则输出值也为NULL。
- 对于类型支持但某些值无法正确转换的情况对应的转换后的值以转换函数输出为准。目前可能遇到的几种情况： - Error will be reported for unsupported type casting
1）BINARY/NCHAR转BIGINT/BIGINT UNSIGNED时可能出现的无效字符情况，例如"a"可能转为0。 - NULL will be returned if the input value is NULL
2）有符号数或TIMESTAMP转BIGINT UNSIGNED可能遇到的溢出问题。 - Some values of some supported data types may not be casted, below are known issues:
3）BIGINT UNSIGNED转BIGINT可能遇到的溢出问题。 1）When casting BINARY/NCHAR to BIGINT/BIGINT UNSIGNED, some characters may be treated as illegal, for example "a" may be converted to 0.
4）FLOAT/DOUBLE转BIGINT/BIGINT UNSIGNED可能遇到的溢出问题。 2）There may be overflow when casting singed integer or TIMESTAMP to unsigned BIGINT
- 版本2.6.0.x后支持 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 ### CONCAT
```sql ```sql
SELECT CONCAT(str1|column1, str2|column2, ...) FROM { tb_name | stb_name } [WHERE clause] 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
**返回结果类型**：同输入参数类型，BINARY 或者 NCHAR。 **Return value type**: Same as the columns being operated, BINARY or NCHAR; or NULL if all the input are NULL
**适用数据类型**：输入参数或者全部是 BINARY 格式的字符串或者列，或者全部是 NCHAR 格式的字符串或者列。不能应用在 TAG 列。 **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
- 如果输入值为NULL，输出值为NULL。 **Applicable nested query**: Inner query and Outer query
- 该函数最小参数个数为2个，最大参数个数为8个。
- 该函数可以应用在普通表和超级表上。 **Applicable versions**: From 2.6.0.0
- 该函数适用于内层查询和外层查询。
- 版本2.6.0.x后支持
### CONCAT_WS ### CONCAT_WS
``` ```
SELECT CONCAT_WS(separator, str1|column1, str2|column2, ...) FROM { tb_name | stb_name } [WHERE clause] 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
**返回结果类型**：同输入参数类型，BINARY 或者 NCHAR。 **Return value type**: Same as the columns being operated, BINARY or NCHAR; or NULL if all the input are NULL
**适用数据类型**：输入参数或者全部是 BINARY 格式的字符串或者列，或者全部是 NCHAR 格式的字符串或者列。不能应用在 TAG 列。 **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
- 如果separator值为NULL，输出值为NULL。如果separator值不为NULL，其他输入为NULL，输出为空串 **Applicable nested query**: Inner query and Outer query
- 该函数最小参数个数为3个，最大参数个数为9个。
- 该函数可以应用在普通表和超级表上。 **Applicable versions**: From 2.6.0.0
- 该函数适用于内层查询和外层查询。
- 版本2.6.0.x后支持 **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 ### 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。 - If the input value is NULL, the output is NULL too
- 该函数可以应用在普通表和超级表上。
- 函数适用于内层查询和外层查询。
- 版本2.6.0.x后支持
### CHAR_LENGTH ### 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
**返回结果类型**：INT。 **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。 **Applicable versions**: From 2.6.0.0
- 该函数可以应用在普通表和超级表上。
- 该函数适用于内层查询和外层查询。 **More explanations**
- 版本2.6.0.x后支持
- If the input value is NULL, the output is NULL too
### LOWER ### 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
**返回结果类型**：同输入类型。 **Applicable nested query**: Inner query and Outer query
**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 **Applicable versions**: From 2.6.0.0
**使用说明**： **More explanations**
- 如果输入值为NULL，输出值为NULL。 - If the input value is NULL, the output is NULL too
- 该函数可以应用在普通表和超级表上。
- 该函数适用于内层查询和外层查询。
- 版本2.6.0.x后支持
### UPPER ### 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
**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 **Applicable table types**: table, stable
**使用说明**： **Applicable nested query**: Inner query and Outer query
- 如果输入值为NULL，输出值为NULL。 **Applicable versions**: From 2.6.0.0
- 该函数可以应用在普通表和超级表上。
- 该函数适用于内层查询和外层查询。 **More explanations**
- 版本2.6.0.x后支持
- If the input value is NULL, the output is NULL too
### LTRIM ### 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
**功能说明**：返回清除左边空格后的字符串。 **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。 - If the input value is NULL, the output is NULL too
- 该函数可以应用在普通表和超级表上。
- 该函数适用于内层查询和外层查询。
- 版本2.6.0.x后支持
### RTRIM ### 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
**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 **Applicable table types**: table, stable
**使用说明**： **Applicable nested query**: Inner query and Outer query
- 如果输入值为NULL，输出值为NULL。 **Applicable versions**: From 2.6.0.0
- 该函数可以应用在普通表和超级表上。
- 该函数适用于内层查询和外层查询。 **More explanations**
- 版本2.6.0.x后支持
- If the input value is NULL, the output is NULL too
### SUBSTR ### 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`
**Return value type**: Same as input
**功能说明**：从源字符串 str 中的指定位置 pos 开始取一个长度为 len 的子串并返回。 **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。 **More explanations**:
- 输入参数pos可以为正数，也可以为负数。如果pos是正数，表示开始位置从字符串开头正数计算。如果pos为负数，表示开始位置从字符串结尾倒数计算。如果输入参数len被忽略，返回的子串包含从pos开始的整个字串。
- 该函数可以应用在普通表和超级表上。
- 该函数适用于内层查询和外层查询。
- 版本2.6.0.x后支持
### 四则运算 - 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.
### Arithmetic Operations
``` ```
SELECT field_name [+|-|*|/|%][Value|field_name] FROM { tb_name | stb_name } [WHERE clause]; SELECT field_name [+|-|*|/|%][Value|field_name] FROM { tb_name | stb_name } [WHERE clause];
``` ```
**功能说明**：统计表/超级表中某列或多列间的值加、减、乘、除、取余计算结果。 **Description**: The sum, difference, product, quotient, or remainder between one or more columns
**Return value type**: Double precision floating point
**返回数据类型**：双精度浮点数。 **Applicable column types**: Data types except for timestamp, binary, nchar, bool
**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。 **Applicable table types**: table, stable
**适用于**：表、超级表。 **More explanations**:
**使用说明**： - Arithmetic operations can be performed on two or more columns, `()` can be used to control the precedence
- NULL doesn't participate the operation, if one of the operands is NULL then result is NULL
- 支持两列或多列之间进行计算，可使用括号控制计算优先级； **Examples**:
- NULL 字段不参与计算，如果参与计算的某行中包含 NULL，该行的计算结果为 NULL。
``` ```
taos> SELECT current + voltage * phase FROM d1001; taos> SELECT current + voltage * phase FROM d1001;
...@@ -1413,27 +1482,29 @@ Query OK, 3 row(s) in set (0.001046s) ...@@ -1413,27 +1482,29 @@ Query OK, 3 row(s) in set (0.001046s)
SELECT STATECOUNT(field_name, oper, val) FROM { tb_name | stb_name } [WHERE clause]; SELECT STATECOUNT(field_name, oper, val) FROM { tb_name | stb_name } [WHERE clause];
``` ```
**功能说明**：返回满足某个条件的连续记录的个数，结果作为新的一列追加在每行后面。条件根据参数计算，如果条件为 true 则加 1，条件为 false 则重置为-1，如果数据为 NULL，跳过该条数据。 **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 : LT (小于)、GT（大于）、LE（小于等于）、GE（大于等于）、NE（不等于）、EQ（等于），不区分大小写。 - 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 : 数值型 - val ： Numeric types
**返回结果类型**：整形。 **Return value type**: Integer
**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上。 **Applicable data types**: Data types excpet for timestamp, binary, nchar, bool
**嵌套子查询支持**：不支持应用在子查询上。 **Applicable table types**: table, stable
**支持的版本**：2.6 开始的版本。 **Applicable nested query**: Outer query only
**使用说明**： **Applicable versions**: From 2.6.0.0
- 该函数可以应用在普通表上，在由 GROUP BY 划分出单独时间线的情况下用于超级表（也即 GROUP BY tbname） **More explanations**:
- 不能和窗口操作一起使用，例如 interval/state_window/session_window。
**示例**： - 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; taos> select ts,dbig from statef2;
...@@ -1465,28 +1536,30 @@ Query OK, 6 row(s) in set (0.002791s) ...@@ -1465,28 +1536,30 @@ Query OK, 6 row(s) in set (0.002791s)
SELECT stateDuration(field_name, oper, val, unit) FROM { tb_name | stb_name } [WHERE clause]; SELECT stateDuration(field_name, oper, val, unit) FROM { tb_name | stb_name } [WHERE clause];
``` ```
**功能说明**：返回满足某个条件的连续记录的时间长度，结果作为新的一列追加在每行后面。条件根据参数计算，如果条件为 true 则加上两个记录之间的时间长度（第一个满足条件的记录时间长度记为 0），条件为 false 则重置为-1，如果数据为 NULL，跳过该条数据。 **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.
**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
- val ： Numeric types
- unit: The unit of time interval, can be [1s, 1m, 1h], default is 1s
- oper : LT (小于)、GT（大于）、LE（小于等于）、GE（大于等于）、NE（不等于）、EQ（等于），不区分大小写。 **Return value type**: Integer
- val : 数值型
- unit : 时间长度的单位，范围[1s、1m、1h ]，不足一个单位舍去。默认为 1s。
**返回结果类型**：整形。 **Applicable data types**: Data types excpet for timestamp, binary, nchar, bool
**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上。 **Applicable table types**: table, stable
**嵌套子查询支持**：不支持应用在子查询上。 **Applicable nested query**: Outer query only
**支持的版本**：2.6 开始的版本。 **Applicable versions**: From 2.6.0.0
**使用说明**： **More explanations**:
- 该函数可以应用在普通表上，在由 GROUP BY 划分出单独时间线的情况下用于超级表（也即 GROUP BY tbname） - Must be used together with `GROUP BY tbname` when it's used on a stable to force the result into each single timeline]
- 不能和窗口操作一起使用，例如 interval/state_window/session_window。 - Can't be used with window operation, like interval/state_window/session_window
**示例**： **Examples**:
``` ```
taos> select ts,dbig from statef2; taos> select ts,dbig from statef2;
...@@ -1512,9 +1585,9 @@ ts | dbig | stateduration(dbig,gt,2) | ...@@ -1512,9 +1585,9 @@ ts | dbig | stateduration(dbig,gt,2) |
Query OK, 6 row(s) in set (0.002613s) Query OK, 6 row(s) in set (0.002613s)
``` ```
## 时间函数 ## Time Functions
从 2.6.0.0 版本开始，TDengine 查询引擎支持以下时间相关函数： From version 2.6.0.0, below time related functions can be used in TDengine.
### NOW ### NOW
...@@ -1524,21 +1597,21 @@ SELECT select_expr FROM { tb_name | stb_name } WHERE ts_col cond_operatior NOW() ...@@ -1524,21 +1597,21 @@ SELECT select_expr FROM { tb_name | stb_name } WHERE ts_col cond_operatior NOW()
INSERT INTO tb_name VALUES (NOW(), ...); INSERT INTO tb_name VALUES (NOW(), ...);
``` ```
**功能说明**：返回客户端当前系统时间。 **Description**: The current time of the client side system
**返回结果数据类型**：TIMESTAMP 时间戳类型。 **Return value type**: TIMESTAMP
**应用字段**：在 WHERE 或 INSERT 语句中使用时只能作用于 TIMESTAMP 类型的字段。 **Applicable column types**: TIMESTAMP only
**适用于**：表、超级表。 **Applicable table types**: table, stable
**使用说明**： **More explanations**:
- 支持时间加减操作，如 NOW() + 1s, 支持的时间单位如下： - Add and Subtract operation can be performed, for example NOW() + 1s, the time unit can be:
b(纳秒)、u(微秒)、a(毫秒)、s(秒)、m(分)、h(小时)、d(天)、w(周)。 b(nanosecond), u(microsecond), a(millisecond)), s(second), m(minute), h(hour), d(day), w(week)
- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 - The precision of the returned timestamp is same as the precision set for the current data base in use
**示例**： **Examples**:
```sql ```sql
taos> SELECT NOW() FROM meters; taos> SELECT NOW() FROM meters;
...@@ -1571,21 +1644,21 @@ SELECT select_expr FROM { tb_name | stb_name } WHERE ts_col cond_operatior TODAY ...@@ -1571,21 +1644,21 @@ SELECT select_expr FROM { tb_name | stb_name } WHERE ts_col cond_operatior TODAY
INSERT INTO tb_name VALUES (TODAY(), ...); INSERT INTO tb_name VALUES (TODAY(), ...);
``` ```
**功能说明**：返回客户端当日零时的系统时间。 **Description**: The timestamp of 00:00:00 of the client side system
**返回结果数据类型**：TIMESTAMP 时间戳类型。 **Return value type**: TIMESTAMP
**应用字段**：在 WHERE 或 INSERT 语句中使用时只能作用于 TIMESTAMP 类型的字段。 **Applicable column types**: TIMESTAMP only
**适用于**：表、超级表。 **Applicable table types**: table, stable
**使用说明**： **More explanations**:
- 支持时间加减操作，如 TODAY() + 1s, 支持的时间单位如下： - Add and Subtract operation can be performed, for example NOW() + 1s, the time unit can be:
b(纳秒)，u(微秒)，a(毫秒)，s(秒)，m(分)，h(小时)，d(天)，w(周)。 b(nanosecond), u(microsecond), a(millisecond)), s(second), m(minute), h(hour), d(day), w(week)
- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 - The precision of the returned timestamp is same as the precision set for the current data base in use
**示例**： **Examples**:
```sql ```sql
taos> SELECT TODAY() FROM meters; taos> SELECT TODAY() FROM meters;
...@@ -1616,15 +1689,15 @@ Query OK, 1 of 1 row(s) in database (0.002210s) ...@@ -1616,15 +1689,15 @@ Query OK, 1 of 1 row(s) in database (0.002210s)
SELECT TIMEZONE() FROM { tb_name | stb_name } [WHERE clause]; SELECT TIMEZONE() FROM { tb_name | stb_name } [WHERE clause];
``` ```
**功能说明**：返回客户端当前时区信息。 **Description**: The timezone of the client side system
**返回结果数据类型**：BINARY 类型。 **Return value type**: BINARY
**应用字段**：无 **Applicable column types**: None
**适用于**：表、超级表。 **Applicable table types**: table, stable
**示例**： **Examples**:
```sql ```sql
taos> SELECT TIMEZONE() FROM meters; taos> SELECT TIMEZONE() FROM meters;
...@@ -1640,20 +1713,20 @@ Query OK, 1 row(s) in set (0.002093s) ...@@ -1640,20 +1713,20 @@ Query OK, 1 row(s) in set (0.002093s)
SELECT TO_ISO8601(ts_val | ts_col) FROM { tb_name | stb_name } [WHERE clause]; SELECT TO_ISO8601(ts_val | ts_col) FROM { tb_name | stb_name } [WHERE clause];
``` ```
**功能说明**：将 UNIX 时间戳转换成为 ISO8601 标准的日期时间格式，并附加客户端时区信息。 **Description**: The ISO8601 date/time format converted from a UNIX timestamp, plus the timezone of the client side system
**返回结果数据类型**：BINARY 类型。 **Return value type**: BINARY
**应用字段**：UNIX 时间戳常量或是 TIMESTAMP 类型的列 **Applicable column types**: TIMESTAMP, constant or a column
**适用于**：表、超级表。 **Applicable table types**: table, stable
**使用说明**： **More explanations**:
- 如果输入是 UNIX 时间戳常量，返回格式精度由时间戳的位数决定; - If the input is UNIX timestamp constant, the precision of the returned value is determined by the digits of the input timestamp
- 如果输入是 TIMSTAMP 类型的列，返回格式的时间戳精度与当前 DATABASE 设置的时间精度一致。 - 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 ```sql
taos> SELECT TO_ISO8601(1643738400) FROM meters; taos> SELECT TO_ISO8601(1643738400) FROM meters;
...@@ -1675,20 +1748,20 @@ taos> SELECT TO_ISO8601(ts) FROM meters; ...@@ -1675,20 +1748,20 @@ taos> SELECT TO_ISO8601(ts) FROM meters;
SELECT TO_UNIXTIMESTAMP(datetime_string | ts_col) FROM { tb_name | stb_name } [WHERE clause]; SELECT TO_UNIXTIMESTAMP(datetime_string | ts_col) FROM { tb_name | stb_name } [WHERE clause];
``` ```
**功能说明**：将日期时间格式的字符串转换成为 UNIX 时间戳。 **Description**: UNIX timestamp converted from a string of date/time format
**返回结果数据类型**：长整型 INT64。 **Return value type**: Long integer
**应用字段**：字符串常量或是 BINARY/NCHAR 类型的列。 **Applicable column types**: Constant or column of BINARY/NCHAR
**适用于**：表、超级表。 **Applicable table types**: table, stable
**使用说明**： **More explanations**:
- 输入的日期时间字符串须符合 ISO8601/RFC3339 标准，无法转换的字符串格式将返回 0。 - The input string must be compatible with ISO8601/RFC3339 standard, 0 will be returned if the string can't be covnerted
- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 - The precision of the returned timestamp is same as the precision set for the current data base in use
**示例**： **Examples**:
```sql ```sql
taos> SELECT TO_UNIXTIMESTAMP("2022-02-02T02:00:00.000Z") FROM meters; taos> SELECT TO_UNIXTIMESTAMP("2022-02-02T02:00:00.000Z") FROM meters;
...@@ -1710,20 +1783,21 @@ taos> SELECT TO_UNIXTIMESTAMP(col_binary) FROM meters; ...@@ -1710,20 +1783,21 @@ taos> SELECT TO_UNIXTIMESTAMP(col_binary) FROM meters;
SELECT TIMETRUNCATE(ts_val | datetime_string | ts_col, time_unit) FROM { tb_name | stb_name } [WHERE clause]; SELECT TIMETRUNCATE(ts_val | datetime_string | ts_col, time_unit) FROM { tb_name | stb_name } [WHERE clause];
``` ```
**功能说明**：将时间戳按照指定时间单位 time_unit 进行截断。 **Description**: Truncate the input timestamp with unit specified by `time_unit`\
**返回结果数据类型**：TIMESTAMP 时间戳类型。 **Return value type**: TIMESTAMP\
**应用字段**：UNIX 时间戳，日期时间格式的字符串，或者 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 如下：
1u(微秒)，1a(毫秒)，1s(秒)，1m(分)，1h(小时)，1d(天)。
- 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。
**示例**： - 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 ```sql
taos> SELECT TIMETRUNCATE(1643738522000, 1h) FROM meters; taos> SELECT TIMETRUNCATE(1643738522000, 1h) FROM meters;
...@@ -1753,20 +1827,21 @@ Query OK, 3 row(s) in set (0.003903s) ...@@ -1753,20 +1827,21 @@ Query OK, 3 row(s) in set (0.003903s)
SELECT TIMEDIFF(ts_val1 | datetime_string1 | ts_col1, ts_val2 | datetime_string2 | ts_col2 [, time_unit]) FROM { tb_name | stb_name } [WHERE clause]; SELECT TIMEDIFF(ts_val1 | datetime_string1 | ts_col1, ts_val2 | datetime_string2 | ts_col2 [, time_unit]) FROM { tb_name | stb_name } [WHERE clause];
``` ```
**功能说明**：计算两个时间戳之间的差值，并近似到时间单位 time_unit 指定的精度。 **Description**: The difference between two timestamps, and rounded to the time unit specified by `time_unit`
**Return value type**: Long Integer
**返回结果数据类型**：长整型 INT64。 **Applicable column types**: UNIX timestamp constant, string constant of date/time format, or a column of TIMESTAMP type
**应用字段**：UNIX 时间戳，日期时间格式的字符串，或者 TIMESTAMP 类型的列。 **Applicable table types**: table, stable
**适用于**：表、超级表。 **More explanations**:
**使用说明**： - Time unit specified by `time_unit` can be:
- 支持的时间单位 time_unit 如下： 1u(microsecond),1a(millisecond),1s(second),1m(minute),1h(hour),1d(day).
1u(微秒)，1a(毫秒)，1s(秒)，1m(分)，1h(小时)，1d(天)。 - The precision of the returned timestamp is same as the precision set for the current data base in use
- 如果时间单位 time_unit 未指定， 返回的时间差值精度与当前 DATABASE 设置的时间精度一致。
**示例**： **Examples**:
```sql ```sql
taos> SELECT TIMEDIFF(1643738400000, 1643742000000) FROM meters; taos> SELECT TIMEDIFF(1643738400000, 1643742000000) FROM meters;
......
docs-en/12-taos-sql/08-interval.md
浏览文件 @ 6e3b25d2
--- ---
sidebar_label: 按窗口切分聚合 sidebar_label: Window
title: 按窗口切分聚合 title: Aggregate by Window
--- ---
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.
TDengine 支持按时间段窗口切分方式进行聚合结果查询，比如温度传感器每秒采集一次数据，但需查询每隔 10 分钟的温度平均值。这种场景下可以使用窗口子句来获得需要的查询结果。 ## Time Window
窗口子句用于针对查询的数据集合进行按照窗口切分成为查询子集并进行聚合，窗口包含时间窗口（time window）、状态窗口（status window）、会话窗口（session 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 子句用于产生相等时间周期的窗口，SLIDING 用以指定窗口向前滑动的时间。每次执行的查询是一个时间窗口，时间窗口随着时间流动向前滑动。在定义连续查询的时候需要指定时间窗口（time window ）大小和每次前向增量时间（forward sliding times）。如图，[t0s, t0e] ，[t1s , t1e]， [t2s, t2e] 是分别是执行三次连续查询的时间窗口范围，窗口的前向滑动的时间范围 sliding time 标识 。查询过滤、聚合等操作按照每个时间窗口为独立的单位执行。当 SLIDING 与 INTERVAL 相等的时候，滑动窗口即为翻转窗口。 ![Time Window](/img/sql/timewindow-1.png)
![时间窗口示意图](/img/sql/timewindow-1.png) `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`.
INTERVAL 和 SLIDING 子句需要配合聚合和选择函数来使用。以下 SQL 语句非法：
``` ```
SELECT * FROM temp_tb_1 INTERVAL(1m); 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); SELECT COUNT(*) FROM temp_tb_1 INTERVAL(1m) SLIDING(2m);
``` ```
当 SLIDING 与 INTERVAL 取值相等的时候，滑动窗口即为翻转窗口。 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.
_ 聚合时间段的窗口宽度由关键词 INTERVAL 指定，最短时间间隔 10 毫秒（10a）；并且支持偏移 offset（偏移必须小于间隔），也即时间窗口划分与“UTC 时刻 0”相比的偏移量。SLIDING 语句用于指定聚合时间段的前向增量，也即每次窗口向前滑动的时长。
_ 从 2.1.5.0 版本开始，INTERVAL 语句允许的最短时间间隔调整为 1 微秒（1u），当然如果所查询的 DATABASE 的时间精度设置为毫秒级，那么允许的最短时间间隔为 1 毫秒（1a）。 \* **注意**：用到 INTERVAL 语句时，除非极特殊的情况，都要求把客户端和服务端的 taos.cfg 配置文件中的 timezone 参数配置为相同的取值，以避免时间处理函数频繁进行跨时区转换而导致的严重性能影响。
## 状态窗口 ## Status Window
使用整数（布尔值）或字符串来标识产生记录时候设备的状态量。产生的记录如果具有相同的状态量数值则归属于同一个状态窗口，数值改变后该窗口关闭。如下图所示，根据状态量确定的状态窗口分别是[2019-04-28 14:22:07，2019-04-28 14:22:10]和[2019-04-28 14:22:11，2019-04-28 14:22:12]两个。（状态窗口暂不支持对超级表使用） 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.
![时间窗口示意图](/img/sql/timewindow-3.png) ![Status Window](/img/sql/timewindow-3.png)
使用 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); SELECT COUNT(*), FIRST(ts), status FROM temp_tb_1 STATE_WINDOW(status);
``` ```
## 会话窗口 ## Session Window
会话窗口根据记录的时间戳主键的值来确定是否属于同一个会话。如下图所示，如果设置时间戳的连续的间隔小于等于 12 秒，则以下 6 条记录构成 2 个会话窗口，分别是：[2019-04-28 14:22:10，2019-04-28 14:22:30]和[2019-04-28 14:23:10，2019-04-28 14:23:30]。因为 2019-04-28 14:22:30 与 2019-04-28 14:23:10 之间的时间间隔是 40 秒，超过了连续时间间隔（12 秒）。 ```sql
SELECT COUNT(*), FIRST(ts) FROM temp_tb_1 SESSION(ts, tol_val);
```
![时间窗口示意图](/img/sql/timewindow-2.png) 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.
在 tol_value 时间间隔范围内的结果都认为归属于同一个窗口，如果连续的两条记录的时间超过 tol_val，则自动开启下一个窗口。（会话窗口暂不支持对超级表使用） ![Session Window](/img/sql/timewindow-2.png)
``` 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
SELECT function_list FROM tb_name SELECT function_list FROM tb_name
[WHERE where_condition] [WHERE where_condition]
[SESSION(ts_col, tol_val)] [SESSION(ts_col, tol_val)]
...@@ -71,39 +71,38 @@ SELECT function_list FROM stb_name ...@@ -71,39 +71,38 @@ SELECT function_list FROM stb_name
[GROUP BY tags] [GROUP BY tags]
``` ```
- 在聚合查询中，function_list 位置允许使用聚合和选择函数，并要求每个函数仅输出单个结果（例如：COUNT、AVG、SUM、STDDEV、LEASTSQUARES、PERCENTILE、MIN、MAX、FIRST、LAST），而不能使用具有多行输出结果的函数（例如：DIFF 以及四则运算）。 ### Restrictions
- 此外 LAST_ROW 查询也不能与窗口聚合同时出现。
- 标量函数（如：CEIL/FLOOR 等）也不能使用在窗口聚合查询中。
-
- WHERE 语句可以指定查询的起止时间和其他过滤条件。 - 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.
- FILL 语句指定某一窗口区间数据缺失的情况下的填充模式。填充模式包括以下几种： - `LAST_ROW` can't be used together with window aggregate.
1. 不进行填充：NONE（默认填充模式）。 - Scalar functions, like CEIL/FLOOR, can't be used with window aggregate.
2. VALUE 填充：固定值填充，此时需要指定填充的数值。例如：FILL(VALUE, 1.23)。 - `WHERE` clause can be used to specify the starting and ending time and other filter conditions
3. PREV 填充：使用前一个非 NULL 值填充数据。例如：FILL(PREV)。 - `FILL` clause is used to specify how to fill when there is data missing in any window, including: \
4. NULL 填充：使用 NULL 填充数据。例如：FILL(NULL)。 1. NONE: No fill (the default fill mode)
5. LINEAR 填充：根据前后距离最近的非 NULL 值做线性插值填充。例如：FILL(LINEAR)。 2. VALUE：Fill with a fixed value, which should be specified together, for example `FILL(VALUE, 1.23)`
6. NEXT 填充：使用下一个非 NULL 值填充数据。例如：FILL(NEXT)。 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 :::info
1. 使用 FILL 语句的时候可能生成大量的填充输出，务必指定查询的时间区间。针对每次查询，系统可返回不超过 1 千万条具有插值的结果。 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. 在时间维度聚合中，返回的结果中时间序列严格单调递增。 2. The result set is in the ascending order of timestamp in aggregate by time window aggregate.
3. 如果查询对象是超级表，则聚合函数会作用于该超级表下满足值过滤条件的所有表的数据。如果查询中没有使用 GROUP BY 语句，则返回的结果按照时间序列严格单调递增；如果查询中使用了 GROUP BY 语句分组，则返回结果中每个 GROUP 内不按照时间序列严格单调递增。 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).
时间聚合也常被用于连续查询场景，可以参考文档 [连续查询(Continuous Query)](/develop/continuous-query)。 ## Examples
## 示例 The table of intelligent meters can be created like below SQL statement：
智能电表的建表语句如下： ```sql
```
CREATE TABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT); CREATE TABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT);
``` ```
针对智能电表采集的数据，以 10 分钟为一个阶段，计算过去 24 小时的电流数据的平均值、最大值、电流的中位数。如果没有计算值，用前一个非 NULL 值填充。使用的查询语句如下： 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 SELECT AVG(current), MAX(current), APERCENTILE(current, 50) FROM meters
......
docs-en/12-taos-sql/09-limit.md
浏览文件 @ 6e3b25d2
--- ---
sidebar_label: 边界限制 sidebar_label: Limits
title: 边界限制 title: Limits and Restrictions
--- ---
## 一般限制 ## Naming Rules
- 数据库名最大长度为 32。 1. Only English characters, digits and underscore are allowed
- 表名最大长度为 192，不包括数据库名前缀和分隔符 2. Can't be started with digits
- 每行数据最大长度 16k 个字符, 从 2.1.7.0 版本开始，每行数据最大长度 48k 个字符（注意：数据行内每个 BINARY/NCHAR 类型的列还会额外占用 2 个字节的存储位置）。 3. Case Insensitive without escape character "\`"
- 列名最大长度为 64，最多允许 4096 列，最少需要 2 列，第一列必须是时间戳。注：从 2.1.7.0 版本（不含)以前最多允许 4096 列 4. Identifier with escape character "\`"
- 标签名最大长度为 64，最多允许 128 个，至少要有 1 个标签，一个表中标签值的总长度不超过 16k 个字符。 To support more flexible table or column names, a new escape character "\`" is introduced. For more details please refer to [escape](/taos-sql/escape).
- SQL 语句最大长度 1048576 个字符，也可通过客户端配置参数 maxSQLLength 修改，取值范围 65480 ~ 1048576。
- SELECT 语句的查询结果，最多允许返回 4096 列（语句中的函数调用可能也会占用一些列空间），超限时需要显式指定较少的返回数据列，以避免语句执行报错。注： 2.1.7.0 版本（不含）之前为最多允许 1024 列
- 库的数目，超级表的数目、表的数目，系统不做限制，仅受系统资源限制。
## 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. ## Restrictions of `IS NOT NULL`
- 超级表最多两个 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 排序
## 表(列)名合法性说明 `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.
### TDengine 中的表（列）名命名规则如下： ## Restrictions of `ORDER BY`
只能由字母、数字、下划线构成，数字不能在首位，长度不能超过 192 字节，不区分大小写。这里表名称不包括数据库名的前缀和分隔符。
### 转义后表（列）名规则： - Only one `order by` is allowed for normal table and sub table.
为了兼容支持更多形式的表（列）名，TDengine 引入新的转义符 "`"，可以避免表名与关键词的冲突，同时不受限于上述表名合法性约束检查，转义符不计入表名的长度。 - At most two `order by` are allowed for stable, and the second one must be `ts`.
转义后的表（列）名同样受到长度限制要求，且长度计算的时候不计算转义符。使用转义字符以后，不再对转义字符中的内容进行大小写统一。 - `order by tag` must be used with `group by tag` on same tag, this rule is also applicable to `tbname`.
- `order by column` must be used with `group by column` or `top/bottom` on same column. This rule is applicable to table and stable.
- `order by ts` is applicable to table and stable.
- If `order by ts` is used with `group by`, the result set is sorted using `ts` in each group.
例如： ## Restrictions of Table/Column Names
\`aBc\` 和 \`abc\` 是不同的表（列）名，但是 abc 和 aBc 是相同的表（列）名。
### Name Restrictions of Table/Column
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 :::note
转义字符中的内容必须是可打印字符。 The characters inside escape characters must be printable characters.
::: :::
### 支持版本 ### Applicable Versions
支持转义符的功能从 2.3.0.1 版本开始。
\ No newline at end of file Escape character "\`" is available from version 2.3.0.1.
docs-en/12-taos-sql/10-json.md
浏览文件 @ 6e3b25d2
--- ---
sidebar_label: JSON 类型使用说明 sidebar_label: JSON
title: JSON 类型使用说明 title: JSON Type
--- ---
## Syntax
## 语法说明 1. Tag of JSON type
1. 创建 json 类型 tag ```sql
create stable s1 (ts timestamp, v1 int) tags (info json);
create table s1_1 using s1 tags ('{"k1": "v1"}');
``` ```
create stable s1 (ts timestamp, v1 int) tags (info json)
create table s1_1 using s1 tags ('{"k1": "v1"}') 2. -> Operator of JSON
```
2. json 取值操作符 ->
``` ```sql
select * from s1 where info->'k1' = 'v1' select * from s1 where info->'k1' = 'v1';
select info->'k1' from s1 select info->'k1' from s1;
``` ```
3. json key 是否存在操作符 contains 3. contains Operator of JSON
``` ```sql
select * from s1 where info contains 'k2' select * from s1 where info contains 'k2';
select * from s1 where info contains 'k1' select * from s1 where info contains 'k1';
``` ```
## 支持的操作 ## Applicable Operations
1. 在 where 条件中时，支持函数 match/nmatch/between and/like/and/or/is null/is no null，不支持 in 1. When JSON data type is used in `where`, `match/nmatch/between and/like/and/or/is null/is no null` can be used but `in` can't be used.
``` ```sql
select * from s1 where info->'k1' match 'v*'; select * from s1 where info->'k1' match 'v*';
select * from s1 where info->'k1' like 'v%' and info contains 'k2'; select * from s1 where info->'k1' like 'v%' and info contains 'k2';
select * from s1 where info is null; select * from s1 where info is null;
select * from s1 where info->'k1' is not null select * from s1 where info->'k1' is not null;
``` ```
2. 支持 json tag 放在 group by、order by、join 子句、union all 以及子查询中，比如 group by json->'key' 2. Tag of JSON type can be used in `group by`, `order by`, `join`, `union all` and sub query, for example `group by json->'key'`
3. 支持 distinct 操作. 3. `Distinct` can be used with tag of JSON type
```sql
select distinct info->'k1' from s1;
``` ```
select distinct info->'k1' from s1
```
4. 标签操作
支持修改 json 标签值（全量覆盖） 4. Tag Operations
支持修改 json 标签名 The value of JSON tag can be altered. Please be noted that the full JSON will be override when doing this.
不支持添加 json 标签、删除 json 标签、修改 json 标签列宽 The name of JSON tag can be altered. A tag of JSON type can't be added or removed. The column length of a JSON tag can't be changed.
## 其他约束条件 ## Other Restrictions
1. 只有标签列可以使用 json 类型，如果用 json 标签，标签列只能有一个。 - JSON type can only be used for tag. There can be only one tag of JSON type, and it's exclusive to any other types of tag.
2. 长度限制：json 中 key 的长度不能超过 256，并且 key 必须为可打印 ascii 字符；json 字符串总长度不超过 4096 个字节。 - The maximum length of keys in JSON is 256 bytes, and key must be printable ASCII characters. The maximum total length of a JSON is 4,096 bytes.
3. json 格式限制： - JSON format：
1. json 输入字符串可以为空（"","\t"," "或 null）或 object，不能为非空的字符串，布尔型和数组。 - The input string for JSON can be empty, i.e. "", "\t", or NULL, but can't be non-NULL string, bool or array.
2. object 可为{}，如果 object 为{}，则整个 json 串记为空。key 可为""，若 key 为""，则 json 串中忽略该 k-v 对。 - object can be {}, and the whole JSON is empty if so. Key can be "", and it's ignored if so.
3. value 可以为数字(int/double)或字符串或 bool 或 null，暂不可以为数组。不允许嵌套。 - value can be int, double, string, boll or NULL, can't be array. Nesting is not allowed, that means value can't be another JSON.
4. 若 json 字符串中出现两个相同的 key，则第一个生效。 - If one key occurs twice in JSON, only the first one is valid.
5. json 字符串里暂不支持转义。 - Escape characters are not allowed in JSON.
4. 当查询 json 中不存在的 key 时，返回 NULL - NULL is returned if querying a key that doesn't exist in JSON.
5. 当 json tag 作为子查询结果时，不再支持上层查询继续对子查询中的 json 串做解析查询。 - If a tag of JSON is the result of inner query, it can't be parsed and queried in the outer query.
比如暂不支持 For example, below SQL statements are not supported.
``` ```sql;
select jtag->'key' from (select jtag from stable) select jtag->'key' from (select jtag from stable);
``` select jtag->'key' from (select jtag from stable) where jtag->'key'>0;
```
不支持
```
select jtag->'key' from (select jtag from stable) where jtag->'key'>0
```
docs-en/12-taos-sql/11-escape.md
浏览文件 @ 6e3b25d2
--- ---
title: 转义字符说明 sidebar-label: Escape
title: Escape
--- ---
## 转义字符表 ## Escape Characters
| 字符序列 | **代表的字符** | | Escape Character | **Actual Meaning** |
| :------: | -------------- | | :--------------: | ------------------------ |
| `\'` | 单引号' | | `\'` | Single quote ' |
| `\"` | 双引号" | | `\"` | Double quote " |
| \n | 换行符 | | \n | Line Break |
| \r | 回车符 | | \r | Carriage Return |
| \t | tab 符 | | \t | tab |
| `\\` | 斜杠\ | | `\\` | Back Slash \ |
| `\%` | % 规则见下 | | `\%` | % see below for details |
| `\_` | \_ 规则见下 | | `\_` | \_ see below for details |
:::note :::note
转义符的功能从 2.4.0.4 版本开始 Escape characters are available from version 2.4.0.4 .
::: :::
## 转义字符使用规则 ## Restrictions
1. 标识符里有转义字符（数据库名、表名、列名） 1. If there are escape characters in identifiers (database name, table name, column name)
1. 普通标识符： 直接提示错误的标识符，因为标识符规定必须是数字、字母和下划线，并且不能以数字开头。 - Identifier without ``: Error will be returned because identifier must be constituted of digits, ASCII characters or underscore and can't be started with digits
2. 反引号``标识符： 保持原样，不转义 - Identifier quoted with ``： Original content is kept, no escaping
2. 数据里有转义字符 2. If there are escape characters in values
1. 遇到上面定义的转义字符会转义（%和\_见下面说明），如果没有匹配的转义字符会忽略掉转义符\。 - 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.
2. 对于%和\_，因为在 like 里这两个字符是通配符，所以在模式匹配 like 里用`\%`%和`\_`表示字符里本身的%和\_，如果在 like 模式匹配上下文之外使用`\%`或`\_`，则它们的计算结果为字符串`\%`和`\_`，而不是%和\_。 - "%" 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 "\_".
docs-en/12-taos-sql/12-keywords/index.md → docs-en/12-taos-sql/12-keywords.md
浏览文件 @ 6e3b25d2
--- ---
sidebar_label: 参数限制与保留关键字 sidebar_label: Keywords
title: TDengine 参数限制与保留关键字 title: Reserved Keywords
--- ---
## 名称命名规则 ## Reserved Keywords
1. 合法字符：英文字符、数字和下划线 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.
2. 允许英文字符或下划线开头，不允许以数字开头
3. 不区分大小写
4. 转义后表（列）名规则：
为了兼容支持更多形式的表（列）名，TDengine 引入新的转义符 "`"。可用让表名与关键词不冲突，同时不受限于上述表名称合法性约束检查。
转义后的表（列）名同样受到长度限制要求，且长度计算的时候不计算转义符。使用转义字符以后，不再对转义字符中的内容进行大小写统一。
例如：\`aBc\` 和 \`abc\` 是不同的表（列）名，但是 abc 和 aBc 是相同的表（列）名。 **Keywords List**
需要注意的是转义字符中的内容必须是可打印字符。
支持转义符的功能从 2.3.0.1 版本开始。
## 密码合法字符集 | | | | | |
`[a-zA-Z0-9!?$%^&*()_–+={[}]:;@~#|<,>.?/]`
去掉了 `` ‘“`\ `` (单双引号、撇号、反斜杠、空格)
- 数据库名：不能包含“.”以及特殊字符，不能超过 32 个字符
- 表名：不能包含“.”以及特殊字符，与所属数据库名一起，不能超过 192 个字符，每行数据最大长度 16k 个字符
- 表的列名：不能包含特殊字符，不能超过 64 个字符
- 数据库名、表名、列名，都不能以数字开头，合法的可用字符集是“英文字符、数字和下划线”
- 表的列数：不能超过 1024 列，最少需要 2 列，第一列必须是时间戳（从 2.1.7.0 版本开始，改为最多支持 4096 列）
- 记录的最大长度：包括时间戳 8 byte，不能超过 16KB（每个 BINARY/NCHAR 类型的列还会额外占用 2 个 byte 的存储位置）
- 单条 SQL 语句默认最大字符串长度：1048576 byte，但可通过系统配置参数 maxSQLLength 修改，取值范围 65480 ~ 1048576 byte
- 数据库副本数：不能超过 3
- 用户名：不能超过 23 个 byte
- 用户密码：不能超过 15 个 byte
- 标签(Tags)数量：不能超过 128 个，可以 0 个
- 标签的总长度：不能超过 16K byte
- 记录条数：仅受存储空间限制
- 表的个数：仅受节点个数限制
- 库的个数：仅受节点个数限制
- 单个库上虚拟节点个数：不能超过 64 个
- 库的数目，超级表的数目、表的数目，系统不做限制，仅受系统资源限制
- SELECT 语句的查询结果，最多允许返回 1024 列（语句中的函数调用可能也会占用一些列空间），超限时需要显式指定较少的返回数据列，以避免语句执行报错。（从 2.1.7.0 版本开始，改为最多允许 4096 列）
## 保留关键字
目前 TDengine 有将近 200 个内部保留关键字，这些关键字无论大小写均不可以用作库名、表名、STable 名、数据列名及标签列名等。这些关键字列表如下：
| 关键字列表 | | | | |
| ----------- | ---------- | --------- | ---------- | ------------ | | ----------- | ---------- | --------- | ---------- | ------------ |
| ABORT | CREATE | IGNORE | NULL | STAR | | ABORT | CREATE | IGNORE | NULL | STAR |
| ACCOUNT | CTIME | IMMEDIATE | OF | STATE | | ACCOUNT | CTIME | IMMEDIATE | OF | STATE |
......
docs-en/12-taos-sql/12-keywords/_category_.yml 已删除 100644 → 0
浏览文件 @ 2ab429ee
label: 参数限制与保留关键字
\ No newline at end of file
docs-en/12-taos-sql/index.md
浏览文件 @ 6e3b25d2
--- ---
title: TAOS SQL title: TAOS SQL
description: "TAOS SQL 支持的语法规则、主要查询功能、支持的 SQL 查询函数，以及常用技巧等内容" description: "The syntax, select, functions and tips supported by TAOS SQL "
--- ---
本文档说明 TAOS SQL 支持的语法规则、主要查询功能、支持的 SQL 查询函数，以及常用技巧等内容。阅读本文档需要读者具有基本的 SQL 语言的基础。 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 是用户对 TDengine 进行数据写入和查询的主要工具。TAOS SQL 为了便于用户快速上手，在一定程度上提供与标准 SQL 类似的风格和模式。严格意义上，TAOS SQL 并不是也不试图提供标准的 SQL 语法。此外，由于 TDengine 针对的时序性结构化数据不提供删除功能，因此在 TAO 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.
为更好地说明 SQL 语法的规则及其特点，本文假设存在一个数据集。以智能电表(meters)为例，假设每个智能电表采集电流、电压、相位三个量。其建模如下： 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:
``` ```sql
taos> DESCRIBE meters; taos> DESCRIBE meters;
Field | Type | Length | Note | Field | Type | Length | Note |
================================================================================= =================================================================================
...@@ -30,4 +30,4 @@ taos> DESCRIBE meters; ...@@ -30,4 +30,4 @@ taos> DESCRIBE meters;
groupid | INT | 4 | TAG | groupid | INT | 4 | TAG |
``` ```
数据集包含 4 个智能电表的数据，按照 TDengine 的建模规则，对应 4 个子表，其名称分别是 d1001, d1002, d1003, d1004。 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.
\ No newline at end of file
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或