docs.md 54.1 KB
Newer Older
X
Xiaxin Li 已提交
1 2
# TAOS SQL

3
本文档说明 TAOS SQL 支持的语法规则、主要查询功能、支持的 SQL 查询函数,以及常用技巧等内容。阅读本文档需要读者具有基本的 SQL 语言的基础。
X
Xiaxin Li 已提交
4

5
TAOS SQL 是用户对 TDengine 进行数据写入和查询的主要工具。TAOS SQL 为了便于用户快速上手,在一定程度上提供类似于标准 SQL 类似的风格和模式。严格意义上,TAOS SQL 并不是也不试图提供 SQL 标准的语法。此外,由于 TDengine 针对的时序性结构化数据不提供删除功能,因此在 TAO SQL 中不提供数据删除的相关功能。
X
Xiaxin Li 已提交
6

7
TAOS SQL 不支持关键字的缩写,例如 DESCRIBE 不能缩写为 DESC。 
X
Xiaxin Li 已提交
8

9 10 11 12 13
本章节 SQL 语法遵循如下约定:

- < > 里的内容是用户需要输入的,但不要输入 <> 本身
- [ ] 表示内容为可选项,但不能输入 [] 本身
- | 表示多选一,选择其中一个即可,但不能输入 | 本身
X
Xiaxin Li 已提交
14 15
- … 表示前面的项可重复多个

16
为更好地说明 SQL 语法的规则及其特点,本文假设存在一个数据集。以智能电表(meters)为例,假设每个智能电表采集电流、电压、相位三个量。其建模如下:
X
Xiaxin Li 已提交
17 18 19 20 21 22 23 24 25 26 27
```mysql
taos> DESCRIBE meters;
             Field              |        Type        |   Length    |    Note    |
=================================================================================
 ts                             | TIMESTAMP          |           8 |            |
 current                        | FLOAT              |           4 |            |
 voltage                        | INT                |           4 |            |
 phase                          | FLOAT              |           4 |            |
 location                       | BINARY             |          64 | TAG        |
 groupid                        | INT                |           4 | TAG        |
```
28
数据集包含 4 个智能电表的数据,按照 TDengine 的建模规则,对应 4 个子表,其名称分别是 d1001, d1002, d1003, d1004。
X
Xiaxin Li 已提交
29

30
## <a class="anchor" id="data-type"></a>支持的数据类型
X
Xiaxin Li 已提交
31

32
使用 TDengine,最重要的是时间戳。创建并插入记录、查询历史记录的时候,均需要指定时间戳。时间戳有如下规则:
X
Xiaxin Li 已提交
33

34 35 36 37 38
- 时间格式为 ```YYYY-MM-DD HH:mm:ss.MS```,默认时间分辨率为毫秒。比如:```2017-08-12 18:25:58.128```
- 内部函数 now 是客户端的当前时间
- 插入记录时,如果时间戳为 now,插入数据时使用提交这条记录的客户端的当前时间
- Epoch Time:时间戳也可以是一个长整数,表示从 1970-01-01 08:00:00.000 开始的毫秒数
- 时间可以加减,比如 now-2h,表明查询时刻向前推 2 个小时(最近 2 小时)。数字后面的时间单位可以是 u(微秒)、a(毫秒)、s(秒)、m(分)、h(小时)、d(天)、w(周)。 比如 `select * from t1 where ts > now-2w and ts <= now-1w`,表示查询两周前整整一周的数据。在指定降频操作(down sampling)的时间窗口(interval)时,时间单位还可以使用 n(自然月) 和 y(自然年)。
X
Xiaxin Li 已提交
39

40
TDengine 缺省的时间戳是毫秒精度,但通过修改配置参数 enableMicrosecond 就可以支持微秒。
X
Xiaxin Li 已提交
41

42
在TDengine中,普通表的数据模型中可使用以下 10 种数据类型。 
X
Xiaxin Li 已提交
43 44 45

|      |   类型    | Bytes  | 说明                                                         |
| ---- | :-------: | ------ | ------------------------------------------------------------ |
46
| 1    | TIMESTAMP | 8      | 时间戳。缺省精度毫秒,可支持微秒。从格林威治时间 1970-01-01 00:00:00.000 (UTC/GMT) 开始,计时不能早于该时间。(从 2.0.18 版本开始,已经去除了这一时间范围限制) |
47 48 49 50
| 2    |    INT    | 4      | 整型,范围 [-2^31+1,   2^31-1], -2^31 用作 NULL           |
| 3    |  BIGINT   | 8      | 长整型,范围 [-2^63+1,   2^63-1], -2^63 用于 NULL                                 |
| 4    |   FLOAT   | 4      | 浮点型,有效位数 6-7,范围 [-3.4E38, 3.4E38]                  |
| 5    |  DOUBLE   | 8      | 双精度浮点型,有效位数 15-16,范围 [-1.7E308, 1.7E308]      |
51
| 6    |  BINARY   | 自定义 | 记录单字节字符串,建议只用于处理 ASCII 可见字符,中文等多字节字符需使用 nchar。理论上,最长可以有 16374 字节,但由于每行数据最多 16K 字节,实际上限一般小于理论值。binary 仅支持字符串输入,字符串两端需使用单引号引用。使用时须指定大小,如 binary(20) 定义了最长为 20 个单字节字符的字符串,每个字符占 1 byte 的存储空间,此时如果用户字符串超出 20 字节将会报错。对于字符串内的单引号,可以用转义字符反斜线加单引号来表示,即 `\’`。 |
52 53 54
| 7    | SMALLINT  | 2      | 短整型, 范围 [-32767, 32767], -32768 用于 NULL                                |
| 8    |  TINYINT  | 1      | 单字节整型,范围 [-127, 127], -128 用于 NULL                                |
| 9    |   BOOL    | 1      | 布尔型,{true, false}                                      |
55
| 10   |   NCHAR   | 自定义 | 记录包含多字节字符在内的字符串,如中文字符。每个 nchar 字符占用 4 bytes 的存储空间。字符串两端使用单引号引用,字符串内的单引号需用转义字符 `\’`。nchar 使用时须指定字符串大小,类型为 nchar(10) 的列表示此列的字符串最多存储 10 个 nchar 字符,会固定占用 40 bytes 的空间。如果用户字符串长度超出声明长度,将会报错。 |
56 57 58

**Tips**:
1. TDengine 对 SQL 语句中的英文字符不区分大小写,自动转化为小写执行。因此用户大小写敏感的字符串及密码,需要使用单引号将字符串引起来。
59
2. **注意**,虽然 Binary 类型在底层存储上支持字节型的二进制字符,但不同编程语言对二进制数据的处理方式并不保证一致,因此建议在 Binary 类型中只存储 ASCII 可见字符,而避免存储不可见字符。多字节的数据,例如中文字符,则需要使用 nchar 类型进行保存。如果强行使用 Binary 类型保存中文字符,虽然有时也能正常读写,但并不带有字符集信息,很容易出现数据乱码甚至数据损坏等情况。
X
Xiaxin Li 已提交
60

61
## <a class="anchor" id="management"></a>数据库管理
X
Xiaxin Li 已提交
62 63

- **创建数据库**  
64

65 66 67 68 69 70 71 72 73 74 75 76 77 78
    ```mysql
    CREATE DATABASE [IF NOT EXISTS] db_name [KEEP keep] [UPDATE 1];
    ```
    说明:
 
    1) KEEP是该数据库的数据保留多长天数,缺省是3650天(10年),数据库会自动删除超过时限的数据;
 
    2) UPDATE 标志数据库支持更新相同时间戳数据;
 
    3) 数据库名最大长度为33;
 
    4) 一条SQL 语句的最大长度为65480个字符;
 
    5) 数据库还有更多与存储相关的配置参数,请参见系统管理。
79 80 81

- **显示系统当前参数**

82 83 84
    ```mysql
    SHOW VARIABLES;
    ```
X
Xiaxin Li 已提交
85 86

- **使用数据库**
87

X
Xiaxin Li 已提交
88
    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
89
    USE db_name;
X
Xiaxin Li 已提交
90 91 92 93 94
    ```
    使用/切换数据库

- **删除数据库**
    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
95
    DROP DATABASE [IF EXISTS] db_name;
X
Xiaxin Li 已提交
96 97 98
    ```
    删除数据库。所包含的全部数据表将被删除,谨慎使用

99 100 101 102
- **修改数据库参数**
    ```mysql
    ALTER DATABASE db_name COMP 2;
    ```
103
    COMP 参数是指修改数据库文件压缩标志位,缺省值为 2,取值范围为 [0, 2]。0 表示不压缩,1 表示一阶段压缩,2 表示两阶段压缩。
104 105 106 107

    ```mysql
    ALTER DATABASE db_name REPLICA 2;
    ```
108
    REPLICA 参数是指修改数据库副本数,取值范围 [1, 3]。在集群中使用,副本数必须小于或等于 DNODE 的数目。
109

110 111 112
    ```mysql
    ALTER DATABASE db_name KEEP 365;
    ```
113
    KEEP 参数是指修改数据文件保存的天数,缺省值为 3650,取值范围 [days, 365000],必须大于或等于 days 参数值。
114 115

    ```mysql
116
    ALTER DATABASE db_name QUORUM 2;
117
    ```
118
    QUORUM 参数是指数据写入成功所需要的确认数,取值范围 [1, 2]。对于异步复制,quorum 设为 1,具有 master 角色的虚拟节点自己确认即可。对于同步复制,需要至少大于等于 2。原则上,Quorum >= 1 并且 Quorum <= replica(副本数),这个参数在启动一个同步模块实例时需要提供。
119 120

    ```mysql
121
    ALTER DATABASE db_name BLOCKS 100;
122
    ```
123 124 125 126 127
    BLOCKS 参数是每个 VNODE (TSDB) 中有多少 cache 大小的内存块,因此一个 VNODE 的用的内存大小粗略为(cache * blocks)。取值范围 [3, 1000]。

    ```mysql
    ALTER DATABASE db_name CACHELAST 0;
    ```
128
    CACHELAST 参数控制是否在内存中缓存数据子表的 last_row。缺省值为 0,取值范围 [0, 1]。其中 0 表示不启用、1 表示启用。(从 2.0.11 版本开始支持,修改后需要重启服务器生效。)
129 130

    **Tips**: 以上所有参数修改后都可以用show databases来确认是否修改成功。
X
Xiaxin Li 已提交
131 132

- **显示系统所有数据库**
133

X
Xiaxin Li 已提交
134
    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
135
    SHOW DATABASES;
X
Xiaxin Li 已提交
136 137
    ```

138 139
## <a class="anchor" id="table"></a>表管理

X
Xiaxin Li 已提交
140
- **创建数据表**
141

X
Xiaxin Li 已提交
142
    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
143
    CREATE TABLE [IF NOT EXISTS] tb_name (timestamp_field_name TIMESTAMP, field1_name data_type1 [, field2_name data_type2 ...]);
X
Xiaxin Li 已提交
144 145
    ```
    说明:
146

147
    1) 表的第一个字段必须是 TIMESTAMP,并且系统自动将其设为主键;
148

149
    2) 表名最大长度为 192;
150

151
    3) 表的每行长度不能超过 16k 个字符;(注意:每个 BINARY/NCHAR 类型的列还会额外占用 2 个字节的存储位置)
152

Z
zyyang 已提交
153
    4) 子表名只能由字母、数字和下划线组成,且不能以数字开头
154

155
    5) 使用数据类型 binary 或 nchar,需指定其最长的字节数,如 binary(20),表示 20 字节;
156

157
- **以超级表为模板创建数据表**
X
Xiaxin Li 已提交
158 159

    ```mysql
160
    CREATE TABLE [IF NOT EXISTS] tb_name USING stb_name TAGS (tag_value1, ...);
X
Xiaxin Li 已提交
161
    ```
162
    以指定的超级表为模板,指定 tags 的值来创建数据表。
X
Xiaxin Li 已提交
163

164 165 166 167 168 169 170 171
- **以超级表为模板创建数据表,并指定具体的 tags 列**

    ```mysql
    CREATE TABLE [IF NOT EXISTS] tb_name USING stb_name (tag_name1, ...) TAGS (tag_value1, ...);
    ```
    以指定的超级表为模板,指定一部分 tags 列的值来创建数据表。(没被指定的 tags 列会设为空值。)  
    说明:从 2.0.17 版本开始支持这种方式。在之前的版本中,不允许指定 tags 列,而必须显式给出所有 tags 列的取值。

172
- **批量创建数据表**
X
Xiaxin Li 已提交
173 174

    ```mysql
175
    CREATE TABLE [IF NOT EXISTS] tb_name1 USING stb_name TAGS (tag_value1, ...) tb_name2 USING stb_name TAGS (tag_value2, ...) ...;
X
Xiaxin Li 已提交
176
    ```
177
    以更快的速度批量创建大量数据表。(服务器端 2.0.14 及以上版本)
178 179 180 181 182 183
    
    说明:

    1)批量建表方式要求数据表必须以超级表为模板。

    2)在不超出 SQL 语句长度限制的前提下,单条语句中的建表数量建议控制在 1000~3000 之间,将会获得比较理想的建表速度。
X
Xiaxin Li 已提交
184 185 186 187

- **删除数据表**

    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
188
    DROP TABLE [IF EXISTS] tb_name;
X
Xiaxin Li 已提交
189
    ```
190

X
Xiaxin Li 已提交
191 192 193
- **显示当前数据库下的所有数据表信息**

    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
194
    SHOW TABLES [LIKE tb_name_wildcar];
X
Xiaxin Li 已提交
195 196
    ```

197
    显示当前数据库下的所有数据表信息。
198

199
    说明:可在like中使用通配符进行名称的匹配,这一通配符字符串最长不能超过24字节。
200

201
    通配符匹配:1)’%’ (百分号)匹配0到任意个字符;2)’\_’下划线匹配一个字符。
X
Xiaxin Li 已提交
202

203
- **在线修改显示字符宽度**
X
Xiaxin Li 已提交
204 205

    ```mysql
206
    SET MAX_BINARY_DISPLAY_WIDTH <nn>;
X
Xiaxin Li 已提交
207 208 209
    ```

- **获取表的结构信息**
210

X
Xiaxin Li 已提交
211
    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
212
    DESCRIBE tb_name;
X
Xiaxin Li 已提交
213 214 215 216 217
    ```

- **表增加列**

    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
218
    ALTER TABLE tb_name ADD COLUMN field_name data_type;
X
Xiaxin Li 已提交
219 220
    ```
    说明:
221

X
Xiaxin Li 已提交
222
    1) 列的最大个数为1024,最小个数为2;
223

224
    2) 列名最大长度为64;
X
Xiaxin Li 已提交
225 226 227 228

- **表删除列**

    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
229
    ALTER TABLE tb_name DROP COLUMN field_name; 
X
Xiaxin Li 已提交
230 231 232
    ```
    如果表是通过[超级表](../super-table/)创建,更改表结构的操作只能对超级表进行。同时针对超级表的结构更改对所有通过该结构创建的表生效。对于不是通过超级表创建的表,可以直接修改表结构

233
## <a class="anchor" id="super-table"></a>超级表STable管理
234

235
注意:在 2.0.15.0 及以后的版本中,开始支持 STABLE 保留字。也即,在本节后文的指令说明中,CREATE、DROP、ALTER 三个指令在老版本中保留字需写作 TABLE 而不是 STABLE。
236

X
Xiaxin Li 已提交
237 238 239
- **创建超级表**

    ```mysql
240
    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]);
X
Xiaxin Li 已提交
241
    ```
242
    创建 STable,与创建表的 SQL 语法相似,但需指定 TAGS 字段的名称和类型
X
Xiaxin Li 已提交
243 244

    说明:
245

246
    1) TAGS 列的数据类型不能是 timestamp 类型;
247

X
Xiaxin Li 已提交
248
    2) TAGS 列名不能与其他列名相同;
249

X
Xiaxin Li 已提交
250
    3) TAGS 列名不能为预留关键字;
251

252
    4) TAGS 最多允许 128 个,至少 1 个,总长度不超过 16 KB。
253

X
Xiaxin Li 已提交
254
- **删除超级表**
255 256

    ```mysql
257
    DROP STABLE [IF EXISTS] stb_name;
258
    ```
259
    删除 STable 会自动删除通过 STable 创建的子表。
260

X
Xiaxin Li 已提交
261
- **显示当前数据库下的所有超级表信息**
262 263

    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
264
    SHOW STABLES [LIKE tb_name_wildcar];
265
    ```
266
    查看数据库内全部 STable,及其相关信息,包括 STable 的名称、创建时间、列数量、标签(TAG)数量、通过该 STable 建表的数量。
267

X
Xiaxin Li 已提交
268
- **获取超级表的结构信息**
269 270

    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
271
    DESCRIBE stb_name;
272 273
    ```

X
Xiaxin Li 已提交
274
- **超级表增加列**
275 276

    ```mysql
277
    ALTER STABLE stb_name ADD COLUMN field_name data_type;
278 279
    ```

X
Xiaxin Li 已提交
280
- **超级表删除列**
281 282

    ```mysql
283
    ALTER STABLE stb_name DROP COLUMN field_name; 
284 285
    ```

286
## <a class="anchor" id="tags"></a>超级表 STable 中 TAG 管理
287

X
Xiaxin Li 已提交
288
- **添加标签**
289 290

    ```mysql
291
    ALTER STABLE stb_name ADD TAG new_tag_name tag_type;
292
    ```
293
    为 STable 增加一个新的标签,并指定新标签的类型。标签总数不能超过 128 个,总长度不超过 16k 个字符。
294

X
Xiaxin Li 已提交
295
- **删除标签**
296 297

    ```mysql
298
    ALTER STABLE stb_name DROP TAG tag_name;
299
    ```
X
Xiaxin Li 已提交
300
    删除超级表的一个标签,从超级表删除某个标签后,该超级表下的所有子表也会自动删除该标签。
301

X
Xiaxin Li 已提交
302
- **修改标签名**
303 304

    ```mysql
305
    ALTER STABLE stb_name CHANGE TAG old_tag_name new_tag_name;
306
    ```
X
Xiaxin Li 已提交
307
    修改超级表的标签名,从超级表修改某个标签名后,该超级表下的所有子表也会自动更新该标签名。
308

P
Ping Xiao 已提交
309
- **修改子表标签值**
310 311

    ```mysql
312
    ALTER TABLE tb_name SET TAG tag_name=new_tag_value;
313
    ```
314
    说明:除了更新标签的值的操作是针对子表进行,其他所有的标签操作(添加标签、删除标签等)均只能作用于 STable,不能对单个子表操作。对 STable 添加标签以后,依托于该 STable 建立的所有表将自动增加了一个标签,所有新增标签的默认值都是 NULL。
315

316
## <a class="anchor" id="insert"></a>数据写入
X
Xiaxin Li 已提交
317 318 319 320 321 322 323 324 325

- **插入一条记录**
    ```mysql
    INSERT INTO tb_name VALUES (field_value, ...);
    ```
    向表tb_name中插入一条记录

- **插入一条记录,数据对应到指定的列**
    ```mysql
326
    INSERT INTO tb_name (field1_name, ...) VALUES (field1_value1, ...);
X
Xiaxin Li 已提交
327 328 329 330 331
    ```
    向表tb_name中插入一条记录,数据对应到指定的列。SQL语句中没有出现的列,数据库将自动填充为NULL。主键(时间戳)不能为NULL。

- **插入多条记录**
    ```mysql
332
    INSERT INTO tb_name VALUES (field1_value1, ...) (field1_value2, ...) ...;
X
Xiaxin Li 已提交
333
    ```
334 335
    向表tb_name中插入多条记录  
    **注意**:在使用“插入多条记录”方式写入数据时,不能把第一列的时间戳取值都设为now,否则会导致语句中的多条记录使用相同的时间戳,于是就可能出现相互覆盖以致这些数据行无法全部被正确保存。
X
Xiaxin Li 已提交
336 337 338

- **按指定的列插入多条记录**
    ```mysql
339
    INSERT INTO tb_name (field1_name, ...) VALUES (field1_value1, ...) (field1_value2, ...) ...;
X
Xiaxin Li 已提交
340 341 342 343 344
    ```
    向表tb_name中按指定的列插入多条记录

- **向多个表插入多条记录**
    ```mysql
345 346
    INSERT INTO tb1_name VALUES (field1_value1, ...) (field1_value2, ...) ...
                tb2_name VALUES (field1_value1, ...) (field1_value2, ...) ...;
X
Xiaxin Li 已提交
347 348 349 350 351
    ```
    同时向表tb1_name和tb2_name中分别插入多条记录

- **同时向多个表按列插入多条记录**
    ```mysql
352 353
    INSERT INTO tb1_name (tb1_field1_name, ...) VALUES (field1_value1, ...) (field1_value2, ...) ...
                tb2_name (tb2_field1_name, ...) VALUES (field1_value1, ...) (field1_value2, ...) ...;
X
Xiaxin Li 已提交
354 355 356
    ```
    同时向表tb1_name和tb2_name中按列分别插入多条记录 

357
    注意:允许插入的最老记录的时间戳,是相对于当前服务器时间,减去配置的keep值(数据保留的天数),允许插入的最新记录的时间戳,是相对于当前服务器时间,加上配置的days值(数据文件存储数据的时间跨度,单位为天)。keep和days都是可以在创建数据库时指定的,缺省值分别是3650天和10天。
X
Xiaxin Li 已提交
358

359 360 361 362 363 364 365 366 367 368 369 370
- <a class="anchor" id="auto_create_table"></a>**插入记录时自动建表**
    ```mysql
    INSERT INTO tb_name USING stb_name TAGS (tag_value1, ...) VALUES (field_value1, ...);
    ```
    如果用户在写数据时并不确定某个表是否存在,此时可以在写入数据时使用自动建表语法来创建不存在的表,若该表已存在则不会建立新表。自动建表时,要求必须以超级表为模板,并写明数据表的 tags 取值。

- **插入记录时自动建表,并指定具体的 tags 列**
    ```mysql
    INSERT INTO tb_name USING stb_name (tag_name1, ...) TAGS (tag_value1, ...) VALUES (field_value1, ...);
    ```
    在自动建表时,可以只是指定部分 tags 列的取值,未被指定的 tags 列将取为空值。

X
Xiaxin Li 已提交
371 372
**历史记录写入**:可使用IMPORT或者INSERT命令,IMPORT的语法,功能与INSERT完全一样。

P
Ping Xiao 已提交
373
说明:针对 insert 类型的 SQL 语句,我们采用的流式解析策略,在发现后面的错误之前,前面正确的部分SQL仍会执行。下面的sql中,insert语句是无效的,但是d1001仍会被创建。
374

P
Ping Xiao 已提交
375
```mysql
376
taos> CREATE TABLE meters(ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS(location BINARY(30), groupId INT);
P
Ping Xiao 已提交
377 378
Query OK, 0 row(s) affected (0.008245s)

379
taos> SHOW STABLES;
P
Ping Xiao 已提交
380 381 382 383 384
              name              |      created_time       | columns |  tags  |   tables    |
============================================================================================
 meters                         | 2020-08-06 17:50:27.831 |       4 |      2 |           0 |
Query OK, 1 row(s) in set (0.001029s)

385
taos> SHOW TABLES;
P
Ping Xiao 已提交
386 387
Query OK, 0 row(s) in set (0.000946s)

388
taos> INSERT INTO d1001 USING meters TAGS('Beijing.Chaoyang', 2);
P
Ping Xiao 已提交
389 390 391

DB error: invalid SQL: keyword VALUES or FILE required

392
taos> SHOW TABLES;
P
Ping Xiao 已提交
393 394 395 396 397
           table_name           |      created_time       | columns |          stable_name           |
======================================================================================================
 d1001                          | 2020-08-06 17:52:02.097 |       4 | meters                         |
Query OK, 1 row(s) in set (0.001091s)
```
X
Xiaxin Li 已提交
398

399 400 401 402 403 404 405 406 407
## <a class="anchor" id="select"></a>数据查询

### 查询语法:

```mysql
SELECT select_expr [, select_expr ...]
    FROM {tb_name_list}
    [WHERE where_condition]
    [INTERVAL (interval_val [, interval_offset])]
408
    [SLIDING sliding_val]
409
    [FILL fill_val]
410
    [GROUP BY col_list]
411
    [ORDER BY col_list { DESC | ASC }]
412 413
    [SLIMIT limit_val [SOFFSET offset_val]]
    [LIMIT limit_val [OFFSET offset_val]]
414
    [>> export_file];
415 416
```

417
#### 通配符
418

X
Xiaxin Li 已提交
419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468
通配符 * 可以用于代指全部列。对于普通表,结果中只有普通列。
```mysql
taos> SELECT * FROM d1001;
           ts            |       current        |   voltage   |        phase         |
======================================================================================
 2018-10-03 14:38:05.000 |             10.30000 |         219 |              0.31000 |
 2018-10-03 14:38:15.000 |             12.60000 |         218 |              0.33000 |
 2018-10-03 14:38:16.800 |             12.30000 |         221 |              0.31000 |
Query OK, 3 row(s) in set (0.001165s)
```

在针对超级表,通配符包含 _标签列_ 。
```mysql
taos> SELECT * FROM meters;
           ts            |       current        |   voltage   |        phase         |            location            |   groupid   |
=====================================================================================================================================
 2018-10-03 14:38:05.500 |             11.80000 |         221 |              0.28000 | Beijing.Haidian                |           2 |
 2018-10-03 14:38:16.600 |             13.40000 |         223 |              0.29000 | Beijing.Haidian                |           2 |
 2018-10-03 14:38:05.000 |             10.80000 |         223 |              0.29000 | Beijing.Haidian                |           3 |
 2018-10-03 14:38:06.500 |             11.50000 |         221 |              0.35000 | Beijing.Haidian                |           3 |
 2018-10-03 14:38:04.000 |             10.20000 |         220 |              0.23000 | Beijing.Chaoyang               |           3 |
 2018-10-03 14:38:16.650 |             10.30000 |         218 |              0.25000 | Beijing.Chaoyang               |           3 |
 2018-10-03 14:38:05.000 |             10.30000 |         219 |              0.31000 | Beijing.Chaoyang               |           2 |
 2018-10-03 14:38:15.000 |             12.60000 |         218 |              0.33000 | Beijing.Chaoyang               |           2 |
 2018-10-03 14:38:16.800 |             12.30000 |         221 |              0.31000 | Beijing.Chaoyang               |           2 |
Query OK, 9 row(s) in set (0.002022s)
```

通配符支持表名前缀,以下两个SQL语句均为返回全部的列:
```mysql
SELECT * FROM d1001;
SELECT d1001.* FROM d1001;
```
在Join查询中,带前缀的\*和不带前缀\*返回的结果有差别, \*返回全部表的所有列数据(不包含标签),带前缀的通配符,则只返回该表的列数据。
```mysql
taos> SELECT * FROM d1001, d1003 WHERE d1001.ts=d1003.ts;
           ts            | current |   voltage   |    phase     |           ts            | current |   voltage   |    phase     |
==================================================================================================================================
 2018-10-03 14:38:05.000 | 10.30000|         219 |      0.31000 | 2018-10-03 14:38:05.000 | 10.80000|         223 |      0.29000 |
Query OK, 1 row(s) in set (0.017385s)
```
```mysql
taos> SELECT d1001.* FROM d1001,d1003 WHERE d1001.ts = d1003.ts;
           ts            |       current        |   voltage   |        phase         |
======================================================================================
 2018-10-03 14:38:05.000 |             10.30000 |         219 |              0.31000 |
Query OK, 1 row(s) in set (0.020443s)
```

在使用SQL函数来进行查询过程中,部分SQL函数支持通配符操作。其中的区别在于:
469
```count(*)```函数只返回一列。```first```、```last```、```last_row```函数则是返回全部列。
X
Xiaxin Li 已提交
470

471 472
```mysql
taos> SELECT COUNT(*) FROM d1001;
X
Xiaxin Li 已提交
473 474 475 476 477 478
       count(*)        |
========================
                     3 |
Query OK, 1 row(s) in set (0.001035s)
```

479 480
```mysql
taos> SELECT FIRST(*) FROM d1001;
X
Xiaxin Li 已提交
481 482 483 484 485 486
        first(ts)        |    first(current)    | first(voltage) |     first(phase)     |
=========================================================================================
 2018-10-03 14:38:05.000 |             10.30000 |            219 |              0.31000 |
Query OK, 1 row(s) in set (0.000849s)
```

487
#### 标签列
488 489 490 491 492 493 494 495 496 497 498 499 500

从 2.0.14 版本开始,支持在普通表的查询中指定 _标签列_,且标签列的值会与普通列的数据一起返回。
```mysql
taos> SELECT location, groupid, current FROM d1001 LIMIT 2;
            location            |   groupid   |       current        |
======================================================================
 Beijing.Chaoyang               |           2 |             10.30000 |
 Beijing.Chaoyang               |           2 |             12.60000 |
Query OK, 2 row(s) in set (0.003112s)
```

注意:普通表的通配符 * 中并不包含 _标签列_。

501 502 503 504 505 506 507 508 509 510 511
##### 获取标签列的去重取值

从 2.0.15 版本开始,支持在超级表查询标签列时,指定 distinct 关键字,这样将返回指定标签列的所有不重复取值。
```mysql
SELECT DISTINCT tag_name FROM stb_name;
```

注意:目前 distinct 关键字只支持对超级表的标签列进行去重,而不能用于普通列。



X
Xiaxin Li 已提交
512 513 514
#### 结果集列名

```SELECT```子句中,如果不指定返回结果集合的列名,结果集列名称默认使用```SELECT```子句中的表达式名称作为列名称。此外,用户可使用```AS```来重命名返回结果集合中列的名称。例如:
515 516
```mysql
taos> SELECT ts, ts AS primary_key_ts FROM d1001;
X
Xiaxin Li 已提交
517 518 519 520 521 522 523 524 525 526
           ts            |     primary_key_ts      |
====================================================
 2018-10-03 14:38:05.000 | 2018-10-03 14:38:05.000 |
 2018-10-03 14:38:15.000 | 2018-10-03 14:38:15.000 |
 2018-10-03 14:38:16.800 | 2018-10-03 14:38:16.800 |
Query OK, 3 row(s) in set (0.001191s)
```
但是针对```first(*)```、```last(*)```、```last_row(*)```不支持针对单列的重命名。

#### 隐式结果列
527

X
Xiaxin Li 已提交
528 529 530 531 532 533
```Select_exprs```可以是表所属列的列名,也可以是基于列的函数表达式或计算式,数量的上限256个。当用户使用了```interval```或```group by tags```的子句以后,在最后返回结果中会强制返回时间戳列(第一列)和group by子句中的标签列。后续的版本中可以支持关闭group by子句中隐式列的输出,列输出完全由select子句控制。

#### 表(超级表)列表

FROM关键字后面可以是若干个表(超级表)列表,也可以是子查询的结果。
如果没有指定用户的当前数据库,可以在表名称之前使用数据库的名称来指定表所属的数据库。例如:```power.d1001``` 方式来跨库使用表。
534
```mysql
X
Xiaxin Li 已提交
535 536
SELECT * FROM power.d1001;
------------------------------
537
USE power;
X
Xiaxin Li 已提交
538 539 540 541
SELECT * FROM d1001;
```

#### 特殊功能
542

X
Xiaxin Li 已提交
543
部分特殊的查询功能可以不使用FROM子句执行。获取当前所在的数据库 database() 
544 545
```mysql
taos> SELECT DATABASE();
X
Xiaxin Li 已提交
546 547 548 549 550
           database()           |
=================================
 power                          |
Query OK, 1 row(s) in set (0.000079s)
```
H
haojun Liao 已提交
551
如果登录的时候没有指定默认数据库,且没有使用```use```命令切换数据,则返回NULL。
552 553
```mysql
taos> SELECT DATABASE();
X
Xiaxin Li 已提交
554 555 556 557 558 559
           database()           |
=================================
 NULL                           |
Query OK, 1 row(s) in set (0.000184s)
```
获取服务器和客户端版本号:
560 561
```mysql
taos> SELECT CLIENT_VERSION();
X
Xiaxin Li 已提交
562 563 564 565 566
 client_version() |
===================
 2.0.0.0          |
Query OK, 1 row(s) in set (0.000070s)

567
taos> SELECT SERVER_VERSION();
X
Xiaxin Li 已提交
568 569 570 571 572 573
 server_version() |
===================
 2.0.0.0          |
Query OK, 1 row(s) in set (0.000077s)
```
服务器状态检测语句。如果服务器正常,返回一个数字(例如 1)。如果服务器异常,返回error code。该SQL语法能兼容连接池对于TDengine状态的检查及第三方工具对于数据库服务器状态的检查。并可以避免出现使用了错误的心跳检测SQL语句导致的连接池连接丢失的问题。
574 575
```mysql
taos> SELECT SERVER_STATUS();
X
Xiaxin Li 已提交
576 577 578 579 580
 server_status() |
==================
               1 |
Query OK, 1 row(s) in set (0.000074s)

581
taos> SELECT SERVER_STATUS() AS status;
X
Xiaxin Li 已提交
582 583 584 585 586
   status    |
==============
           1 |
Query OK, 1 row(s) in set (0.000081s)
```
587

X
Xiaxin Li 已提交
588 589 590 591 592 593
#### TAOS SQL中特殊关键词

 >   TBNAME: 在超级表查询中可视为一个特殊的标签,代表查询涉及的子表名<br>
    \_c0: 表示表(超级表)的第一列

#### 小技巧
594

X
Xiaxin Li 已提交
595
获取一个超级表所有的子表名及相关的标签信息:
596
```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
597
SELECT TBNAME, location FROM meters;
X
Xiaxin Li 已提交
598 599
```
统计超级表下辖子表数量:
600
```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
601
SELECT COUNT(TBNAME) FROM meters;
X
Xiaxin Li 已提交
602 603
```
以上两个查询均只支持在Where条件子句中添加针对标签(TAGS)的过滤条件。例如:
604
```mysql
X
Xiaxin Li 已提交
605 606 607 608 609 610 611 612 613
taos> SELECT TBNAME, location FROM meters;
             tbname             |            location            |
==================================================================
 d1004                          | Beijing.Haidian                |
 d1003                          | Beijing.Haidian                |
 d1002                          | Beijing.Chaoyang               |
 d1001                          | Beijing.Chaoyang               |
Query OK, 4 row(s) in set (0.000881s)

614
taos> SELECT COUNT(tbname) FROM meters WHERE groupId > 2;
X
Xiaxin Li 已提交
615 616 617 618 619 620
     count(tbname)     |
========================
                     2 |
Query OK, 1 row(s) in set (0.001091s)
```

621
- 可以使用 * 返回所有列,或指定列名。可以对数字列进行四则运算,可以给输出的列取列名。
622 623
  * 暂不支持含列名的四则运算表达式用于条件过滤算子(例如,不支持 `where a*2>6;`,但可以写 `where a>6/2;`)。
  * 暂不支持含列名的四则运算表达式作为 SQL 函数的应用对象(例如,不支持 `select min(2*a) from t;`,但可以写 `select 2*min(a) from t;`)。
624
- WHERE 语句可以使用各种逻辑判断来过滤数字值,或使用通配符来过滤字符串。
625 626
- 输出结果缺省按首列时间戳升序排序,但可以指定按降序排序( _c0 指首列时间戳)。使用 ORDER BY 对其他字段进行排序为非法操作。
- 参数 LIMIT 控制输出条数,OFFSET 指定从第几条开始输出。LIMIT/OFFSET 对结果集的执行顺序在 ORDER BY 之后。
627 628
  * 在有 GROUP BY 子句的情况下,LIMIT 参数控制的是每个分组中至多允许输出的条数。
- 参数 SLIMIT 控制由 GROUP BY 指令划分的分组中,至多允许输出几个分组的数据。
629
- 通过 ">>" 输出结果可以导出到指定文件。
X
Xiaxin Li 已提交
630 631 632

### 支持的条件过滤操作

633 634 635 636 637 638 639 640 641 642 643
| Operation   | Note                          | Applicable Data Types                 |
| ----------- | ----------------------------- | ------------------------------------- |
| >           | larger than                   | **`timestamp`** and all numeric types |
| <           | smaller than                  | **`timestamp`** and all numeric types |
| >=          | larger than or equal to       | **`timestamp`** and all numeric types |
| <=          | smaller than or equal to      | **`timestamp`** and all numeric types |
| =           | equal to                      | all types                             |
| <>          | not equal to                  | all types                             |
| between and | within a certain range        | **`timestamp`** and all numeric types |
| %           | match with any char sequences | **`binary`** **`nchar`**              |
| _           | match with a single char      | **`binary`** **`nchar`**              |
X
Xiaxin Li 已提交
644

645
1. 同时进行多个字段的范围过滤,需要使用关键词 AND 来连接不同的查询条件,暂不支持 OR 连接的不同列之间的查询过滤条件。
646 647
2. 针对单一字段的过滤,如果是时间过滤条件,则一条语句中只支持设定一个;但针对其他的(普通)列或标签列,则可以使用 `OR` 关键字进行组合条件的查询过滤。例如:((value > 20 AND value < 30) OR (value < 12)) 。
3. 从 2.0.17 版本开始,条件过滤开始支持 BETWEEN AND 语法,例如 `WHERE col2 BETWEEN 1.5 AND 3.25` 表示查询条件为“1.5 ≤ col2 ≤ 3.25”。
X
Xiaxin Li 已提交
648

649
<!-- 
650
### <a class="anchor" id="having"></a>GROUP BY 之后的 HAVING 过滤
651 652 653 654 655 656 657

从 2.0.20 版本开始,GROUP BY 之后允许再跟一个 HAVING 子句,对成组后的各组数据再做筛选。HAVING 子句可以使用聚合函数和选择函数作为过滤条件(但暂时不支持 LEASTSQUARES、TOP、BOTTOM、LAST_ROW)。

例如,如下语句只会输出 `AVG(f1) > 0` 的分组:
```mysql
SELECT AVG(f1), SPREAD(f1, f2, st2.f1) FROM st2 WHERE f1 > 0 GROUP BY f1 HAVING AVG(f1) > 0;
```
658
-->
659

660 661 662 663 664 665 666 667 668 669
### <a class="anchor" id="union"></a>UNION ALL 操作符

```mysql
SELECT ...
UNION ALL SELECT ...
[UNION ALL SELECT ...]
```

TDengine 支持 UNION ALL 操作符。也就是说,如果多个 SELECT 子句返回结果集的结构完全相同(列名、列类型、列数、顺序),那么可以通过 UNION ALL 把这些结果集合并到一起。目前只支持 UNION ALL 模式,也即在结果集的合并过程中是不去重的。

H
haojun Liao 已提交
670
### SQL 示例 
X
Xiaxin Li 已提交
671 672 673 674

- 对于下面的例子,表tb1用以下语句创建

    ```mysql
675
    CREATE TABLE tb1 (ts TIMESTAMP, col1 INT, col2 FLOAT, col3 BINARY(50));
X
Xiaxin Li 已提交
676 677 678 679 680
    ```

- 查询tb1刚过去的一个小时的所有记录

    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
681
    SELECT * FROM tb1 WHERE ts >= NOW - 1h;
X
Xiaxin Li 已提交
682 683 684 685 686
    ```

- 查询表tb1从2018-06-01 08:00:00.000 到2018-06-02 08:00:00.000时间范围,并且col3的字符串是'nny'结尾的记录,结果按照时间戳降序

    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
687
    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;
X
Xiaxin Li 已提交
688 689 690 691 692
    ```

- 查询col1与col2的和,并取名complex, 时间大于2018-06-01 08:00:00.000, col2大于1.2,结果输出仅仅10条记录,从第5条开始

    ```mysql
693
    SELECT (col1 + col2) AS 'complex' FROM tb1 WHERE ts > '2018-06-01 08:00:00.000' AND col2 > 1.2 LIMIT 10 OFFSET 5;
X
Xiaxin Li 已提交
694 695 696 697 698
    ```

- 查询过去10分钟的记录,col2的值大于3.14,并且将结果输出到文件 `/home/testoutpu.csv`.

    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
699
    SELECT COUNT(*) FROM tb1 WHERE ts >= NOW - 10m AND col2 > 3.14 >> /home/testoutpu.csv;
X
Xiaxin Li 已提交
700 701
    ```

702
## <a class="anchor" id="functions"></a>SQL 函数
X
Xiaxin Li 已提交
703 704 705 706 707 708 709

### 聚合函数

TDengine支持针对数据的聚合查询。提供支持的聚合和选择函数如下:

- **COUNT**
    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
710
    SELECT COUNT([*|field_name]) FROM tb_name [WHERE clause];
X
Xiaxin Li 已提交
711
    ```
712
    功能说明:统计表/超级表中记录行数或某列的非空值个数。
713

714
    返回结果数据类型:长整型INT64。
715

716
    应用字段:应用全部字段。
717

718
    适用于:**表、超级表**。
719 720 721

    说明:

722
    1)可以使用星号\*来替代具体的字段,使用星号(\*)返回全部记录数量。
723 724 725 726

    2)针对同一表的(不包含NULL值)字段查询结果均相同。

    3)如果统计对象是具体的列,则返回该列中非NULL值的记录数量。
X
Xiaxin Li 已提交
727 728 729

    示例:
    ```mysql
730
    taos> SELECT COUNT(*), COUNT(voltage) FROM meters;
X
Xiaxin Li 已提交
731 732 733 734 735
        count(*)        |    count(voltage)     |
    ================================================
                        9 |                     9 |
    Query OK, 1 row(s) in set (0.004475s)

736
    taos> SELECT COUNT(*), COUNT(voltage) FROM d1001;
X
Xiaxin Li 已提交
737 738 739 740 741 742 743 744
        count(*)        |    count(voltage)     |
    ================================================
                        3 |                     3 |
    Query OK, 1 row(s) in set (0.001075s)
    ```

- **AVG**
    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
745
    SELECT AVG(field_name) FROM tb_name [WHERE clause];
X
Xiaxin Li 已提交
746
    ```
747
    功能说明:统计表/超级表中某列的平均值。
748

749
    返回结果数据类型:双精度浮点数Double。
750

751
    应用字段:不能应用在timestamp、binary、nchar、bool字段。
752

753
    适用于:**表、超级表**。
754

X
Xiaxin Li 已提交
755 756 757 758 759 760 761 762
    示例:
    ```mysql
    taos> SELECT AVG(current), AVG(voltage), AVG(phase) FROM meters;
        avg(current)        |       avg(voltage)        |        avg(phase)         |
    ====================================================================================
                11.466666751 |             220.444444444 |               0.293333333 |
    Query OK, 1 row(s) in set (0.004135s)

763
    taos> SELECT AVG(current), AVG(voltage), AVG(phase) FROM d1001;
X
Xiaxin Li 已提交
764 765 766 767 768 769 770 771
        avg(current)        |       avg(voltage)        |        avg(phase)         |
    ====================================================================================
                11.733333588 |             219.333333333 |               0.316666673 |
    Query OK, 1 row(s) in set (0.000943s)
    ```

- **TWA**
    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
772
    SELECT TWA(field_name) FROM tb_name WHERE clause;
X
Xiaxin Li 已提交
773
    ```
774
    功能说明:时间加权平均函数。统计表中某列在一段时间内的时间加权平均。
775

776
    返回结果数据类型:双精度浮点数Double。
777

X
Xiaxin Li 已提交
778
    应用字段:不能应用在timestamp、binary、nchar、bool类型字段。
779

780
    适用于:**表**。
X
Xiaxin Li 已提交
781 782 783

- **SUM**
    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
784
    SELECT SUM(field_name) FROM tb_name [WHERE clause];
X
Xiaxin Li 已提交
785
    ```
786
    功能说明:统计表/超级表中某列的和。
787

788
    返回结果数据类型:双精度浮点数Double和长整型INT64。
789

790
    应用字段:不能应用在timestamp、binary、nchar、bool类型字段。
791

792
    适用于:**表、超级表**。
X
Xiaxin Li 已提交
793 794 795

    示例:
    ```mysql
796
    taos> SELECT SUM(current), SUM(voltage), SUM(phase) FROM meters;
X
Xiaxin Li 已提交
797 798 799 800 801
        sum(current)        |     sum(voltage)      |        sum(phase)         |
    ================================================================================
                103.200000763 |                  1984 |               2.640000001 |
    Query OK, 1 row(s) in set (0.001702s)

802
    taos> SELECT SUM(current), SUM(voltage), SUM(phase) FROM d1001;
X
Xiaxin Li 已提交
803 804 805 806 807 808 809 810
        sum(current)        |     sum(voltage)      |        sum(phase)         |
    ================================================================================
                35.200000763 |                   658 |               0.950000018 |
    Query OK, 1 row(s) in set (0.000980s)
    ```

- **STDDEV**
    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
811
    SELECT STDDEV(field_name) FROM tb_name [WHERE clause];
X
Xiaxin Li 已提交
812
    ```
813
    功能说明:统计表中某列的均方差。
814

815
    返回结果数据类型:双精度浮点数Double。
816

817
    应用字段:不能应用在timestamp、binary、nchar、bool类型字段。
818

819
    适用于:**表**。(从 2.0.15.1 版本开始,本函数也支持**超级表**)
X
Xiaxin Li 已提交
820 821 822 823 824 825 826 827 828 829 830 831

    示例:
    ```mysql
    taos> SELECT STDDEV(current) FROM d1001;
        stddev(current)      |
    ============================
                1.020892909 |
    Query OK, 1 row(s) in set (0.000915s)
    ```

- **LEASTSQUARES**
    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
832
    SELECT LEASTSQUARES(field_name, start_val, step_val) FROM tb_name [WHERE clause];
X
Xiaxin Li 已提交
833
    ```
834
    功能说明:统计表中某列的值是主键(时间戳)的拟合直线方程。start_val是自变量初始值,step_val是自变量的步长值。
835

836
    返回结果数据类型:字符串表达式(斜率, 截距)。
837

838
    应用字段:不能应用在timestamp、binary、nchar、bool类型字段。
839

840
    说明:自变量是时间戳,因变量是该列的值。
841

842
    适用于:**表**。
X
Xiaxin Li 已提交
843 844 845 846 847 848 849 850 851 852 853 854 855 856

    示例:
    ```mysql
    taos> SELECT LEASTSQUARES(current, 1, 1) FROM d1001;
                leastsquares(current, 1, 1)             |
    =====================================================
    {slop:1.000000, intercept:9.733334}                 |
    Query OK, 1 row(s) in set (0.000921s)
    ```

### 选择函数

- **MIN**
    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
857
    SELECT MIN(field_name) FROM {tb_name | stb_name} [WHERE clause];
X
Xiaxin Li 已提交
858
    ```
859
    功能说明:统计表/超级表中某列的值最小值。
860

861
    返回结果数据类型:同应用的字段。
862

X
Xiaxin Li 已提交
863 864
    应用字段:不能应用在timestamp、binary、nchar、bool类型字段。

865 866
    适用于:**表、超级表**。

X
Xiaxin Li 已提交
867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883
    示例:
    ```mysql
    taos> SELECT MIN(current), MIN(voltage) FROM meters;
        min(current)     | min(voltage) |
    ======================================
                10.20000 |          218 |
    Query OK, 1 row(s) in set (0.001765s)

    taos> SELECT MIN(current), MIN(voltage) FROM d1001;
        min(current)     | min(voltage) |
    ======================================
                10.30000 |          218 |
    Query OK, 1 row(s) in set (0.000950s)
    ```

- **MAX**
    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
884
    SELECT MAX(field_name) FROM { tb_name | stb_name } [WHERE clause];
X
Xiaxin Li 已提交
885
    ```
886
    功能说明:统计表/超级表中某列的值最大值。
887

888
    返回结果数据类型:同应用的字段。
889

X
Xiaxin Li 已提交
890 891
    应用字段:不能应用在timestamp、binary、nchar、bool类型字段。

892 893
    适用于:**表、超级表**。

X
Xiaxin Li 已提交
894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910
    示例:
    ```mysql
    taos> SELECT MAX(current), MAX(voltage) FROM meters;
        max(current)     | max(voltage) |
    ======================================
                13.40000 |          223 |
    Query OK, 1 row(s) in set (0.001123s)

    taos> SELECT MAX(current), MAX(voltage) FROM d1001;
        max(current)     | max(voltage) |
    ======================================
                12.60000 |          221 |
    Query OK, 1 row(s) in set (0.000987s)
    ```

- **FIRST**
    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
911
    SELECT FIRST(field_name) FROM { tb_name | stb_name } [WHERE clause];
X
Xiaxin Li 已提交
912
    ```
913
    功能说明:统计表/超级表中某列的值最先写入的非NULL值。
914

915
    返回结果数据类型:同应用的字段。
916

917
    应用字段:所有字段。
918

919 920
    适用于:**表、超级表**。

921 922 923 924 925 926 927
    说明:

    1)如果要返回各个列的首个(时间戳最小)非NULL值,可以使用FIRST(\*);

    2) 如果结果集中的某列全部为NULL值,则该列的返回结果也是NULL;

    3) 如果结果集中所有列全部为NULL值,则不返回结果。
X
Xiaxin Li 已提交
928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945

    示例:
    ```mysql
    taos> SELECT FIRST(*) FROM meters;
            first(ts)        |    first(current)    | first(voltage) |     first(phase)     |
    =========================================================================================
    2018-10-03 14:38:04.000 |             10.20000 |            220 |              0.23000 |
    Query OK, 1 row(s) in set (0.004767s)

    taos> SELECT FIRST(current) FROM d1002;
        first(current)    |
    =======================
                10.20000 |
    Query OK, 1 row(s) in set (0.001023s)
    ```

- **LAST**
    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
946
    SELECT LAST(field_name) FROM { tb_name | stb_name } [WHERE clause];
X
Xiaxin Li 已提交
947
    ```
948
    功能说明:统计表/超级表中某列的值最后写入的非NULL值。
949

950
    返回结果数据类型:同应用的字段。
951

952
    应用字段:所有字段。
953

954 955
    适用于:**表、超级表**。

956 957 958 959 960
    说明:

    1)如果要返回各个列的最后(时间戳最大)一个非NULL值,可以使用LAST(\*);

    2)如果结果集中的某列全部为NULL值,则该列的返回结果也是NULL;如果结果集中所有列全部为NULL值,则不返回结果。
X
Xiaxin Li 已提交
961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978

    示例:
    ```mysql
    taos> SELECT LAST(*) FROM meters;
            last(ts)         |    last(current)     | last(voltage) |     last(phase)      |
    ========================================================================================
    2018-10-03 14:38:16.800 |             12.30000 |           221 |              0.31000 |
    Query OK, 1 row(s) in set (0.001452s)

    taos> SELECT LAST(current) FROM d1002;
        last(current)     |
    =======================
                10.30000 |
    Query OK, 1 row(s) in set (0.000843s)
    ```

- **TOP**
    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
979
    SELECT TOP(field_name, K) FROM { tb_name | stb_name } [WHERE clause];
X
Xiaxin Li 已提交
980
    ```
981
    功能说明: 统计表/超级表中某列的值最大 *k* 个非 NULL 值。如果多条数据取值一样,全部取用又会超出 k 条限制时,系统会从相同值中随机选取符合要求的数量返回。
982

983
    返回结果数据类型:同应用的字段。
984

985
    应用字段:不能应用在timestamp、binary、nchar、bool类型字段。
986

987 988
    适用于:**表、超级表**。

989 990 991 992 993
    说明:

    1)*k*值取值范围1≤*k*≤100;

    2)系统同时返回该记录关联的时间戳列。
X
Xiaxin Li 已提交
994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014

    示例:
    ```mysql
    taos> SELECT TOP(current, 3) FROM meters;
            ts            |   top(current, 3)    |
    =================================================
    2018-10-03 14:38:15.000 |             12.60000 |
    2018-10-03 14:38:16.600 |             13.40000 |
    2018-10-03 14:38:16.800 |             12.30000 |
    Query OK, 3 row(s) in set (0.001548s)

    taos> SELECT TOP(current, 2) FROM d1001;
            ts            |   top(current, 2)    |
    =================================================
    2018-10-03 14:38:15.000 |             12.60000 |
    2018-10-03 14:38:16.800 |             12.30000 |
    Query OK, 2 row(s) in set (0.000810s)
    ```

- **BOTTOM**
    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
1015
    SELECT BOTTOM(field_name, K) FROM { tb_name | stb_name } [WHERE clause];
X
Xiaxin Li 已提交
1016
    ```
1017
    功能说明:统计表/超级表中某列的值最小 *k* 个非 NULL 值。如果多条数据取值一样,全部取用又会超出 k 条限制时,系统会从相同值中随机选取符合要求的数量返回。
1018

1019
    返回结果数据类型:同应用的字段。
1020

1021
    应用字段:不能应用在timestamp、binary、nchar、bool类型字段。
1022

1023 1024
    适用于:**表、超级表**。

1025 1026 1027 1028 1029
    说明:

    1)*k*值取值范围1≤*k*≤100;

    2)系统同时返回该记录关联的时间戳列。
X
Xiaxin Li 已提交
1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049

    示例:
    ```mysql
    taos> SELECT BOTTOM(voltage, 2) FROM meters;
            ts            | bottom(voltage, 2) |
    ===============================================
    2018-10-03 14:38:15.000 |                218 |
    2018-10-03 14:38:16.650 |                218 |
    Query OK, 2 row(s) in set (0.001332s)

    taos> SELECT BOTTOM(current, 2) FROM d1001;
            ts            |  bottom(current, 2)  |
    =================================================
    2018-10-03 14:38:05.000 |             10.30000 |
    2018-10-03 14:38:16.800 |             12.30000 |
    Query OK, 2 row(s) in set (0.000793s)
    ```

- **PERCENTILE**
    ```mysql
P
Ping Xiao 已提交
1050
    SELECT PERCENTILE(field_name, P) FROM { tb_name } [WHERE clause];
X
Xiaxin Li 已提交
1051
    ```
1052
    功能说明:统计表中某列的值百分比分位数。
1053

1054
    返回结果数据类型: 双精度浮点数Double。
1055

1056
    应用字段:不能应用在timestamp、binary、nchar、bool类型字段。
1057

1058 1059
    适用于:**表**。

X
Xiaxin Li 已提交
1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072
    说明:*P*值取值范围0≤*P*≤100,为0的时候等同于MIN,为100的时候等同于MAX。

    示例:
    ```mysql
    taos> SELECT PERCENTILE(current, 20) FROM d1001;
    percentile(current, 20)  |
    ============================
                11.100000191 |
    Query OK, 1 row(s) in set (0.000787s)
    ```

- **APERCENTILE**
    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
1073
    SELECT APERCENTILE(field_name, P) FROM { tb_name | stb_name } [WHERE clause];
X
Xiaxin Li 已提交
1074
    ```
1075
    功能说明:统计表/超级表中某列的值百分比分位数,与PERCENTILE函数相似,但是返回近似结果。
1076

1077
    返回结果数据类型: 双精度浮点数Double。
1078

1079
    应用字段:不能应用在timestamp、binary、nchar、bool类型字段。
1080

1081 1082
    适用于:**表、超级表**。

X
Xiaxin Li 已提交
1083
    说明:*P*值取值范围0≤*P*≤100,为0的时候等同于MIN,为100的时候等同于MAX。推荐使用```APERCENTILE```函数,该函数性能远胜于```PERCENTILE```函数
1084

X
Xiaxin Li 已提交
1085 1086 1087 1088 1089 1090 1091 1092 1093 1094
    ```mysql
    taos> SELECT APERCENTILE(current, 20) FROM d1001;
    apercentile(current, 20)  |
    ============================
                10.300000191 |
    Query OK, 1 row(s) in set (0.000645s)
    ```
    
- **LAST_ROW**
    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
1095
    SELECT LAST_ROW(field_name) FROM { tb_name | stb_name };
X
Xiaxin Li 已提交
1096
    ```
1097
    功能说明:返回表/超级表的最后一条记录。
1098

1099
    返回结果数据类型:同应用的字段。
1100

1101
    应用字段:所有字段。
1102

1103 1104
    适用于:**表、超级表**。

X
Xiaxin Li 已提交
1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124
    说明:与last函数不同,last_row不支持时间范围限制,强制返回最后一条记录。

    示例:
    ```mysql
    taos> SELECT LAST_ROW(current) FROM meters;
    last_row(current)   |
    =======================
                12.30000 |
    Query OK, 1 row(s) in set (0.001238s)

    taos> SELECT LAST_ROW(current) FROM d1002;
    last_row(current)   |
    =======================
                10.30000 |
    Query OK, 1 row(s) in set (0.001042s)
    ```

### 计算函数
- **DIFF**
    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
1125
    SELECT DIFF(field_name) FROM tb_name [WHERE clause];
X
Xiaxin Li 已提交
1126
    ```
1127
    功能说明:统计表中某列的值与前一行对应值的差。
1128

1129
    返回结果数据类型: 同应用字段。
1130

1131
    应用字段:不能应用在timestamp、binary、nchar、bool类型字段。
1132

1133 1134
    适用于:**表**。

X
Xiaxin Li 已提交
1135
    说明:输出结果行数是范围内总行数减一,第一行没有结果输出。
1136

X
Xiaxin Li 已提交
1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148
    示例:
    ```mysql
    taos> SELECT DIFF(current) FROM d1001;
            ts            |    diff(current)     |
    =================================================
    2018-10-03 14:38:15.000 |              2.30000 |
    2018-10-03 14:38:16.800 |             -0.30000 |
    Query OK, 2 row(s) in set (0.001162s)
    ```

- **SPREAD**
    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
1149
    SELECT SPREAD(field_name) FROM { tb_name | stb_name } [WHERE clause];
X
Xiaxin Li 已提交
1150
    ```
1151
    功能说明:统计表/超级表中某列的最大值和最小值之差。
1152

1153
    返回结果数据类型: 双精度浮点数。
1154

1155
    应用字段:不能应用在binary、nchar、bool类型字段。
1156

1157 1158
    适用于:**表、超级表**。

X
Xiaxin Li 已提交
1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178
    说明:可用于TIMESTAMP字段,此时表示记录的时间覆盖范围。

    示例:
    ```mysql
    taos> SELECT SPREAD(voltage) FROM meters;
        spread(voltage)      |
    ============================
                5.000000000 |
    Query OK, 1 row(s) in set (0.001792s)

    taos> SELECT SPREAD(voltage) FROM d1001;
        spread(voltage)      |
    ============================
                3.000000000 |
    Query OK, 1 row(s) in set (0.000836s)
    ```

- **四则运算**

    ```mysql
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
1179
    SELECT field_name [+|-|*|/|%][Value|field_name] FROM { tb_name | stb_name }  [WHERE clause];
X
Xiaxin Li 已提交
1180
    ```
1181
    功能说明:统计表/超级表中某列或多列间的值加、减、乘、除、取余计算结果。
1182

1183
    返回结果数据类型:双精度浮点数。
1184

1185
    应用字段:不能应用在timestamp、binary、nchar、bool类型字段。
1186

1187 1188
    适用于:**表、超级表**。

1189 1190 1191 1192 1193
    说明:

    1)支持两列或多列之间进行计算,可使用括号控制计算优先级;

    2)NULL字段不参与计算,如果参与计算的某行中包含NULL,该行的计算结果为NULL。
X
Xiaxin Li 已提交
1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204

    ```mysql
    taos> SELECT current + voltage * phase FROM d1001;
    (current+(voltage*phase)) |
    ============================
                78.190000713 |
                84.540003240 |
                80.810000718 |
    Query OK, 3 row(s) in set (0.001046s)
    ```

1205 1206
## <a class="anchor" id="aggregation"></a>时间维度聚合

X
Xiaxin Li 已提交
1207 1208 1209
TDengine支持按时间段进行聚合,可以将表中数据按照时间段进行切割后聚合生成结果,比如温度传感器每秒采集一次数据,但需查询每隔10分钟的温度平均值。这个聚合适合于降维(down sample)操作, 语法如下:

```mysql
1210
SELECT function_list FROM tb_name
X
Xiaxin Li 已提交
1211
  [WHERE where_condition]
1212
  INTERVAL (interval [, offset])
1213
  [SLIDING sliding]
X
Xiaxin Li 已提交
1214 1215
  [FILL ({NONE | VALUE | PREV | NULL | LINEAR})]

1216
SELECT function_list FROM stb_name
X
Xiaxin Li 已提交
1217
  [WHERE where_condition]
1218
  INTERVAL (interval [, offset])
1219
  [SLIDING sliding]
X
Xiaxin Li 已提交
1220 1221 1222 1223
  [FILL ({ VALUE | PREV | NULL | LINEAR})]
  [GROUP BY tags]
```

1224
- 聚合时间段的长度由关键词INTERVAL指定,最短时间间隔10毫秒(10a),并且支持偏移(偏移必须小于间隔)。聚合查询中,能够同时执行的聚合和选择函数仅限于单个输出的函数:count、avg、sum 、stddev、leastsquares、percentile、min、max、first、last,不能使用具有多行输出结果的函数(例如:top、bottom、diff以及四则运算)。
1225
- WHERE语句可以指定查询的起止时间和其他过滤条件
1226
- SLIDING语句用于指定聚合时间段的前向增量
X
Xiaxin Li 已提交
1227
- FILL语句指定某一时间区间数据缺失的情况下的填充模式。填充模式包括以下几种:
1228 1229 1230 1231
  * 不进行填充:NONE(默认填充模式)。
  * VALUE填充:固定值填充,此时需要指定填充的数值。例如:fill(value, 1.23)。
  * NULL填充:使用NULL填充数据。例如:fill(null)。
  * PREV填充:使用前一个非NULL值填充数据。例如:fill(prev)。
1232 1233

说明:
X
Xiaxin Li 已提交
1234 1235 1236 1237
  1. 使用FILL语句的时候可能生成大量的填充输出,务必指定查询的时间区间。针对每次查询,系统可返回不超过1千万条具有插值的结果。
  2. 在时间维度聚合中,返回的结果中时间序列严格单调递增。
  3. 如果查询对象是超级表,则聚合函数会作用于该超级表下满足值过滤条件的所有表的数据。如果查询中没有使用group by语句,则返回的结果按照时间序列严格单调递增;如果查询中使用了group by语句分组,则返回结果中每个group内不按照时间序列严格单调递增。

1238 1239
时间聚合也常被用于连续查询场景,可以参考文档 [连续查询(Continuous Query)](https://www.taosdata.com/cn/documentation/advanced-features#continuous-query)。

X
Xiaxin Li 已提交
1240 1241 1242
**示例:** 智能电表的建表语句如下:

```mysql
1243
CREATE TABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT);
X
Xiaxin Li 已提交
1244 1245 1246 1247 1248 1249
```

针对智能电表采集的数据,以10分钟为一个阶段,计算过去24小时的电流数据的平均值、最大值、电流的中位数、以及随着时间变化的电流走势拟合直线。如果没有计算值,用前一个非NULL值填充。
使用的查询语句如下:

```mysql
1250 1251
SELECT AVG(current), MAX(current), LEASTSQUARES(current, start_val, step_val), PERCENTILE(current, 50) FROM meters
  WHERE ts>=NOW-1d
X
Xiaxin Li 已提交
1252 1253 1254 1255
  INTERVAL(10m)
  FILL(PREV);
```

1256 1257
## <a class="anchor" id="limitation"></a>TAOS SQL 边界限制

1258 1259 1260 1261 1262
- 数据库名最大长度为 32
- 表名最大长度为 192,每行数据最大长度 16k 个字符(注意:数据行内每个 BINARY/NCHAR 类型的列还会额外占用 2 个字节的存储位置)
- 列名最大长度为 64,最多允许 1024 列,最少需要 2 列,第一列必须是时间戳
- 标签最多允许 128 个,可以 1 个,标签总长度不超过 16k 个字符
- SQL 语句最大长度 65480 个字符,但可通过系统配置参数 maxSQLLength 修改,最长可配置为 1M
1263
- SELECT 语句的查询结果,最多允许返回 1024 列(语句中的函数调用可能也会占用一些列空间),超限时需要显式指定较少的返回数据列,以避免语句执行报错。
P
Ping Xiao 已提交
1264
- 库的数目,超级表的数目、表的数目,系统不做限制,仅受系统资源限制
1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277

##  TAOS SQL其他约定

**group by的限制**

TAOS  SQL支持对标签、tbname进行group by操作,也支持普通列进行group by,前提是:仅限一列且该列的唯一值小于10万个。

**join操作的限制**

TAOS SQL支持表之间按主键时间戳来join两张表的列,暂不支持两个表之间聚合后的四则运算。

**is not null与不为空的表达式适用范围**

1278 1279
is not null支持所有类型的列。不为空的表达式为 <>"",仅对非数值类型的列适用。