-
+
- + + TDengine-server-2.4.0.12-Linux-x64.rpm (14.5 M) + + +
- + + TDengine-server-2.4.0.12-Linux-x64.deb (12.8 M) + + +
- + + TDengine-server-2.4.0.12-Linux-x64.tar.gz (15.5 M) + + +
- + + TDengine-server-2.4.0.12-Linux-x64-Lite.tar.gz (3.4 M) + + +
- + + TDengine-server-2.3.5.0-beta-Linux-x64-Lite.tar.gz (3 M) + + +
- + + TDengine-server-2.3.5.0-beta-Linux-x64.rpm (18.4 M) + + +
- + + TDengine-server-2.3.5.0-beta-Linux-x64.deb (16.8 M) + + +
- + + TDengine-server-2.3.5.0-beta-Linux-x64.tar.gz (18.8 M) + + +
1：1-1；
2：1-2；
\>=3：1-3 | ALTER DATABASE
| 设备ID | +时间戳 | +采集量 | +标签 | +|||
|---|---|---|---|---|---|---|
| Device ID | +Time Stamp | +current | +voltage | +phase | +location | +groupId | +
| d1001 | +1538548685000 | +10.3 | +219 | +0.31 | +Beijing.Chaoyang | +2 | +
| d1002 | +1538548684000 | +10.2 | +220 | +0.23 | +Beijing.Chaoyang | +3 | +
| d1003 | +1538548686500 | +11.5 | +221 | +0.35 | +Beijing.Haidian | +3 | +
| d1004 | +1538548685500 | +13.4 | +223 | +0.29 | +Beijing.Haidian | +2 | +
| d1001 | +1538548695000 | +12.6 | +218 | +0.33 | +Beijing.Chaoyang | +2 | +
| d1004 | +1538548696600 | +11.8 | +221 | +0.28 | +Beijing.Haidian | +2 | +
| d1002 | +1538548696650 | +10.3 | +218 | +0.25 | +Beijing.Chaoyang | +3 | +
| d1001 | +1538548696800 | +12.3 | +221 | +0.31 | +Beijing.Chaoyang | +2 | +
**P**值有效取值范围 0≤P≤100，为 0 的时候等同于 MIN，为 100 的时候等同于 MAX；
**algo_type**的有效输入：**default** 和 **t-digest**。 用于指定计算近似分位数的算法。可不提供第三个参数的输入，此时将使用 default 的算法进行计算，即 apercentile(column_name, 50, "default") 与 apercentile(column_name, 50) 等价。当使用“t-digest”参数的时候，将使用 t-digest 方式采样计算近似分位数。但该参数指定计算算法的功能从 2.2.0.x 版本开始支持，2.2.0.0 之前的版本不支持指定使用算法的功能。
+ +嵌套子查询支持：适用于内层查询和外层查询。 + +``` +taos> SELECT APERCENTILE(current, 20) FROM d1001; +apercentile(current, 20) | +============================ + 10.300000191 | +Query OK, 1 row(s) in set (0.000645s) + +taos> select apercentile (count, 80, 'default') from stb1; + apercentile (c0, 80, 'default') | +================================== + 601920857.210056424 | +Query OK, 1 row(s) in set (0.012363s) + +taos> select apercentile (count, 80, 't-digest') from stb1; + apercentile (c0, 80, 't-digest') | +=================================== + 605869120.966666579 | +Query OK, 1 row(s) in set (0.011639s) +``` + +### LAST_ROW + +``` +SELECT LAST_ROW(field_name) FROM { tb_name | stb_name }; +``` + +**功能说明**：返回表/超级表的最后一条记录。 + +**返回数据类型**：同应用的字段。 + +**应用字段**：所有字段。 + +**适用于**：表、超级表。 + +限制：LAST_ROW() 不能与 INTERVAL 一起使用。 + +说明：在用于超级表时，时间戳完全一样且同为最大的数据行可能有多个，那么会从中随机返回一条，而并不保证多次运行所挑选的数据行必然一致。
+ +{" "} + +{" "} + +
+示例： + +``` + taos> SELECT LAST_ROW(current) FROM meters; + last_row(current) | + ======================= + 12.30000 | + Query OK, 1 row(s) in set (0.001238s) + + taos> SELECT LAST_ROW(current) FROM d1002; + last_row(current) | + ======================= + 10.30000 | + Query OK, 1 row(s) in set (0.001042s) +``` + +### INTERP [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})]; +``` + +**功能说明**：返回表/超级表的指定时间截面指定列的记录值（插值）。 + +**返回数据类型**：同字段类型。 + +**应用字段**：数值型字段。 + +适用于：**表、超级表、嵌套查询**。 + +说明： +1）INTERP 用于在指定时间断面获取指定列的记录值，如果该时间断面不存在符合条件的行数据，那么会根据 FILL 参数的设定进行插值。 + +2）INTERP 的输入数据为指定列的数据，可以通过条件语句（where 子句）来对原始列数据进行过滤，如果没有指定过滤条件则输入为全部数据。 + +3）INTERP 的输出时间范围根据 RANGE(timestamp1,timestamp2)字段来指定，需满足 timestamp1<=timestamp2。其中 timestamp1（必选值）为输出时间范围的起始值，即如果 timestamp1 时刻符合插值条件则 timestamp1 为输出的第一条记录，timestamp2（必选值）为输出时间范围的结束值，即输出的最后一条记录的 timestamp 不能大于 timestamp2。如果没有指定 RANGE，那么满足过滤条件的输入数据中第一条记录的 timestamp 即为 timestamp1，最后一条记录的 timestamp 即为 timestamp2，同样也满足 timestamp1 <= timestamp2。 + +4）INTERP 根据 EVERY 字段来确定输出时间范围内的结果条数，即从 timestamp1 开始每隔固定长度的时间（EVERY 值）进行插值。如果没有指定 EVERY，则默认窗口大小为无穷大，即从 timestamp1 开始只有一个窗口。 + +5）INTERP 根据 FILL 字段来决定在每个符合输出条件的时刻如何进行插值，如果没有 FILL 字段则默认不插值，即输出为原始记录值或不输出（原始记录不存在）。 + +6）INTERP 只能在一个时间序列内进行插值，因此当作用于超级表时必须跟 group by tbname 一起使用，当作用嵌套查询外层时内层子查询不能含 GROUP BY 信息。 + +7）INTERP 的插值结果不受 ORDER BY timestamp 的影响，ORDER BY timestamp 只影响输出结果的排序。 + +SQL 示例： + + 1) 单点线性插值 + +``` + taos> SELECT INTERP(*) FROM t1 RANGE('2017-7-14 18:40:00'，'2017-7-14 18:40:00') FILL(LINEAR); +``` + + 2) 在2017-07-14 18:00:00到2017-07-14 19:00:00间每隔5秒钟进行取值(不插值) + +``` + taos> SELECT INTERP(*) FROM t1 RANGE('2017-7-14 18:00:00'，'2017-7-14 19:00:00') EVERY(5s); +``` + + 3) 在2017-07-14 18:00:00到2017-07-14 19:00:00间每隔5秒钟进行线性插值 + +``` + taos> SELECT INTERP(*) FROM t1 RANGE('2017-7-14 18:00:00'，'2017-7-14 19:00:00') EVERY(5s) FILL(LINEAR); +``` + +4.在所有时间范围内每隔 5 秒钟进行向后插值 + +``` + taos> SELECT INTERP(*) FROM t1 EVERY(5s) FILL(NEXT); +``` + +5.根据 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 秒钟进行线性插值 + +``` + taos> SELECT INTERP(*) 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 之前的版本] + +``` +SELECT INTERP(field_name) FROM { tb_name | stb_name } WHERE ts='timestamp' [FILL ({ VALUE | PREV | NULL | LINEAR | NEXT})]; +``` + +**功能说明**：返回表/超级表的指定时间截面、指定字段的记录。 + +**返回数据类型**：同字段类型。 + +**应用字段**：数值型字段。 + +**适用于**：表、超级表。 + +说明：（从 2.0.15.0 版本开始新增此函数）
1）INTERP 必须指定时间断面，如果该时间断面不存在直接对应的数据，那么会根据 FILL 参数的设定进行插值。此外，条件语句里面可附带筛选条件，例如标签、tbname。
2）INTERP 查询要求查询的时间区间必须位于数据集合（表）的所有记录的时间范围之内。如果给定的时间戳位于时间范围之外，即使有插值指令，仍然不返回结果。
3）单个 INTERP 函数查询只能够针对一个时间点进行查询，如果需要返回等时间间隔的断面数据，可以通过 INTERP 配合 EVERY 的方式来进行查询处理（而不是使用 INTERVAL），其含义是每隔固定长度的时间进行插值。
+ 示例： + +``` + taos> SELECT INTERP(*) FROM meters WHERE ts='2017-7-14 18:40:00.004'; + interp(ts) | interp(current) | interp(voltage) | interp(phase) | + ========================================================================================== + 2017-07-14 18:40:00.004 | 9.84020 | 216 | 0.32222 | + Query OK, 1 row(s) in set (0.002652s) +``` + +如果给定的时间戳无对应的数据，在不指定插值生成策略的情况下，不会返回结果，如果指定了插值策略，会根据插值策略返回结果。 + +``` + taos> SELECT INTERP(*) FROM meters WHERE tbname IN ('d636') AND ts='2017-7-14 18:40:00.005'; + Query OK, 0 row(s) in set (0.004022s) + + taos> SELECT INTERP(*) FROM meters WHERE tbname IN ('d636') AND ts='2017-7-14 18:40:00.005' FILL(PREV); + interp(ts) | interp(current) | interp(voltage) | interp(phase) | + ========================================================================================== + 2017-07-14 18:40:00.005 | 9.88150 | 217 | 0.32500 | + Query OK, 1 row(s) in set (0.003056s) +``` + +如下所示代码表示在时间区间 `['2017-7-14 18:40:00', '2017-7-14 18:40:00.014']` 中每隔 5 毫秒 进行一次断面计算。 + +``` + taos> SELECT INTERP(current) FROM d636 WHERE ts>='2017-7-14 18:40:00' AND ts<='2017-7-14 18:40:00.014' EVERY(5a); + ts | interp(current) | + ================================================= + 2017-07-14 18:40:00.000 | 10.04179 | + 2017-07-14 18:40:00.010 | 10.16123 | + Query OK, 2 row(s) in set (0.003487s) +``` + +### TAIL + +``` +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`。 + +**参数范围**：k: [1,100] offset_val: [0,100]。 + +**返回结果数据类型**：同应用的字段。 + +**应用字段**：适合于除时间主列外的任何类型字段。 + +**支持版本**：2.6 开始的版本。 + +示例： + +``` +taos> select ts,dbig from tail2; + ts | dbig | +================================================== +2021-10-15 00:31:33.000 | 1 | +2021-10-17 00:31:31.000 | NULL | +2021-12-24 00:31:34.000 | 2 | +2022-01-01 08:00:05.000 | 19 | +2022-01-01 08:00:06.000 | NULL | +2022-01-01 08:00:07.000 | 9 | +Query OK, 6 row(s) in set (0.001952s) + +taos> select tail(dbig,2,2) from tail2; +ts | tail(dbig,2,2) | +================================================== +2021-12-24 00:31:34.000 | 2 | +2022-01-01 08:00:05.000 | 19 | +Query OK, 2 row(s) in set (0.002307s) +``` + +### UNIQUE + +``` +SELECT UNIQUE(field_name) FROM {tb_name | stb_name} [WHERE clause]; +``` + +**功能说明**：返回该列的数值首次出现的值。该函数功能与 distinct 相似，但是可以匹配标签和时间戳信息。可以针对除时间列以外的字段进行查询，可以匹配标签和时间戳，其中的标签和时间戳是第一次出现时刻的标签和时间戳。 + +**返回结果数据类型**：同应用的字段。 + +**应用字段**：适合于除时间类型以外的字段。 + +**支持版本**：2.6 开始的版本。 + +**说明**： + +- 该函数可以应用在普通表和超级表上。不能和窗口操作一起使用，例如 interval/state_window/session_window 。 +- 由于返回数据量未知，考虑到内存因素，为了函数可以正常返回结果，建议不重复的数据量在 10 万级别，否则会报错。 + +示例： + +``` +taos> select ts,voltage from unique1; + ts | voltage | +================================================== +2021-10-17 00:31:31.000 | 1 | +2022-01-24 00:31:31.000 | 1 | +2021-10-17 00:31:31.000 | 1 | +2021-12-24 00:31:31.000 | 2 | +2022-01-01 08:00:01.000 | 19 | +2021-10-17 00:31:31.000 | NULL | +2022-01-01 08:00:02.000 | NULL | +2022-01-01 08:00:03.000 | 9 | +Query OK, 8 row(s) in set (0.003018s) + +taos> select unique(voltage) from unique1; +ts | unique(voltage) | +================================================== +2021-10-17 00:31:31.000 | 1 | +2021-10-17 00:31:31.000 | NULL | +2021-12-24 00:31:31.000 | 2 | +2022-01-01 08:00:01.000 | 19 | +2022-01-01 08:00:03.000 | 9 | +Query OK, 5 row(s) in set (0.108458s) +``` + +## 计算函数 + +- **DIFF** + + ```sql + SELECT {DIFF(field_name, ignore_negative) | DIFF(field_name)} FROM tb_name [WHERE clause]; + ``` + + 功能说明：统计表中某列的值与前一行对应值的差。 ignore_negative 取值为 0|1 , 可以不填，默认值为 0. 不忽略负值。ignore_negative 为 1 时表示忽略负数。 + + 返回结果数据类型：同应用字段。 + + 应用字段：不能应用在 timestamp、binary、nchar、bool 类型字段。 + + 适用于：**表、（超级表）**。 + + 说明：输出结果行数是范围内总行数减一，第一行没有结果输出。从 2.1.3.0 版本开始，DIFF 函数可以在由 GROUP BY 划分出单独时间线的情况下用于超级表（也即 GROUP BY tbname）。从 2.6.0 开始，DIFF 函数支持 ignore_negative 参数 + + 示例： + + ```sql + taos> SELECT DIFF(current) FROM d1001; + ts | diff(current) | + ================================================= + 2018-10-03 14:38:15.000 | 2.30000 | + 2018-10-03 14:38:16.800 | -0.30000 | + Query OK, 2 row(s) in set (0.001162s) + ``` + +### DERIVATIVE + +``` +SELECT DERIVATIVE(field_name, time_interval, ignore_negative) FROM tb_name [WHERE clause]; +``` + +**功能说明**：统计表中某列数值的单位变化率。其中单位时间区间的长度可以通过 time_interval 参数指定，最小可以是 1 秒（1s）；ignore_negative 参数的值可以是 0 或 1，为 1 时表示忽略负值。 + +**返回数据类型**：双精度浮点数。 + +**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。 + +适用于：**表、（超级表）**。 + +说明：（从 2.1.3.0 版本开始新增此函数）输出结果行数是范围内总行数减一，第一行没有结果输出。DERIVATIVE 函数可以在由 GROUP BY 划分出单独时间线的情况下用于超级表（也即 GROUP BY tbname）。 + +示例： + +``` +taos> select derivative(current, 10m, 0) from t1; + ts | derivative(current, 10m, 0) | +======================================================== + 2021-08-20 10:11:22.790 | 0.500000000 | + 2021-08-20 11:11:22.791 | 0.166666620 | + 2021-08-20 12:11:22.791 | 0.000000000 | + 2021-08-20 13:11:22.792 | 0.166666620 | + 2021-08-20 14:11:22.792 | -0.666666667 | +Query OK, 5 row(s) in set (0.004883s) +``` + +### SPREAD + +``` +SELECT SPREAD(field_name) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：统计表/超级表中某列的最大值和最小值之差。 + +**返回数据类型**：双精度浮点数。 + +**应用字段**：不能应用在 binary、nchar、bool 类型字段。 + +**适用于**：表、超级表。 + +说明：可用于 TIMESTAMP 字段，此时表示记录的时间覆盖范围。 + +示例： + +``` +taos> SELECT SPREAD(voltage) FROM meters; + spread(voltage) | +============================ + 5.000000000 | +Query OK, 1 row(s) in set (0.001792s) + +taos> SELECT SPREAD(voltage) FROM d1001; + spread(voltage) | +============================ + 3.000000000 | +Query OK, 1 row(s) in set (0.000836s) +``` + +### CEIL + +``` +SELECT CEIL(field_name) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：获得指定列的向上取整数的结果。 + +返回结果类型：与指定列的原始数据类型一致。例如，如果指定列的原始数据类型为 Float，那么返回的数据类型也为 Float；如果指定列的原始数据类型为 Double，那么返回的数据类型也为 Double。 + +适用数据类型：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列，无论 tag 列的类型是什么类型。 + +嵌套子查询支持：适用于内层查询和外层查询。 + +说明： +支持 +、-、\*、/ 运算，如 ceil(col1) + ceil(col2)。 +只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 +该函数可以应用在普通表和超级表上。 + +### FLOOR + +``` +SELECT FLOOR(field_name) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：获得指定列的向下取整数的结果。 + 其他使用说明参见 CEIL 函数描述。 + +### ROUND + +``` +SELECT ROUND(field_name) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：获得指定列的四舍五入的结果。 + 其他使用说明参见 CEIL 函数描述。 + +### CSUM + + ```sql + SELECT CSUM(field_name) FROM { tb_name | stb_name } [WHERE clause] + ``` + + **功能说明**：累加和（Cumulative sum），输出行与输入行数相同。 + + **返回结果类型**： 输入列如果是整数类型返回值为长整型 （int64_t），浮点数返回值为双精度浮点数（Double）。无符号整数类型返回值为无符号长整型（uint64_t）。 返回结果中同时带有每行记录对应的时间戳。 + + **适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在标签之上。 + + **嵌套子查询支持**： 适用于内层查询和外层查询。 + + **补充说明**： 不支持 +、-、*、/ 运算，如 csum(col1) + csum(col2)。只能与聚合（Aggregation）函数一起使用。 该函数可以应用在普通表和超级表上。 使用在超级表上的时候，需要搭配 Group by tbname使用，将结果强制规约到单个时间线。 + + **支持版本**： 从2.3.0.x开始支持 + +### MAVG + + ```sql + SELECT MAVG(field_name, K) FROM { tb_name | stb_name } [WHERE clause] + ``` + + **功能说明**： 计算连续 k 个值的移动平均数（moving average）。如果输入行数小于 k，则无结果输出。参数 k 的合法输入范围是 1≤ k ≤ 1000。 + + **返回结果类型**： 返回双精度浮点数类型。 + + **适用数据类型**： 不能应用在 timestamp、binary、nchar、bool 类型上；在超级表查询中使用时，不能应用在标签之上。 + + **嵌套子查询支持**： 适用于内层查询和外层查询。 + + **补充说明**： 不支持 +、-、*、/ 运算，如 mavg(col1, k1) + mavg(col2, k1); 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用；该函数可以应用在普通表和超级表上；使用在超级表上的时候，需要搭配 Group by tbname使用，将结果强制规约到单个时间线。 + + **支持版本**： 从2.3.0.x开始支持 + +### SAMPLE + + ```sql + SELECT SAMPLE(field_name, K) FROM { tb_name | stb_name } [WHERE clause] + ``` + + **功能说明**： 获取数据的 k 个采样值。参数 k 的合法输入范围是 1≤ k ≤ 1000。 + + **返回结果类型**： 同原始数据类型， 返回结果中带有该行记录的时间戳。 + + **适用数据类型**： 在超级表查询中使用时，不能应用在标签之上。 + + **嵌套子查询支持**： 适用于内层查询和外层查询。 + + **补充说明**： 不能参与表达式计算；该函数可以应用在普通表和超级表上；使用在超级表上的时候，需要搭配 Group by tbname 使用，将结果强制规约到单个时间线。 + + **支持版本**： 从2.3.0.x开始支持 + +### ASIN + + ```sql + SELECT ASIN(field_name) FROM { tb_name | stb_name } [WHERE clause] + ``` + +**功能说明**：获得指定列的反正弦结果 + +**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**： + + 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + + 该函数可以应用在普通表和超级表上。 + + 版本2.6.0.x后支持 + +### ACOS + + ```sql + SELECT ACOS(field_name) FROM { tb_name | stb_name } [WHERE clause] + ``` + +**功能说明**：获得指定列的反余弦结果 + +**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**： + + 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + + 该函数可以应用在普通表和超级表上。 + + 版本2.6.0.x后支持 + +### ATAN + + ```sql + SELECT ATAN(field_name) FROM { tb_name | stb_name } [WHERE clause] + ``` + +**功能说明**：获得指定列的反正切结果 + +**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**： + + 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + + 该函数可以应用在普通表和超级表上。 + + 版本2.6.0.x后支持 + +### SIN + + ```sql + SELECT SIN(field_name) FROM { tb_name | stb_name } [WHERE clause] + ``` + +**功能说明**：获得指定列的正弦结果 + +**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**： + + 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + + 该函数可以应用在普通表和超级表上。 + + 版本2.6.0.x后支持 + +### COS + + ```sql + SELECT COS(field_name) FROM { tb_name | stb_name } [WHERE clause] + ``` + +**功能说明**：获得指定列的余弦结果 + +**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**： + + 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + + 该函数可以应用在普通表和超级表上。 + + 版本2.6.0.x后支持 + +### TAN + + ```sql + SELECT TAN(field_name) FROM { tb_name | stb_name } [WHERE clause] + ``` + +**功能说明**：获得指定列的正切结果 + +**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**： + + 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + + 该函数可以应用在普通表和超级表上。 + + 版本2.6.0.x后支持 + +### POW + + ```sql + SELECT POW(field_name, power) FROM { tb_name | stb_name } [WHERE clause] + ``` + +**功能说明**：获得指定列的指数为 power 的幂 + +**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**： + + 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + + 该函数可以应用在普通表和超级表上。 + + 版本2.6.0.x后支持 + +### LOG + + ```sql + SELECT LOG(field_name, base) FROM { tb_name | stb_name } [WHERE clause] + ``` + +**功能说明**：获得指定列对于底数 base 的对数 + +**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**： + + 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + + 该函数可以应用在普通表和超级表上。 + + 版本2.6.0.x后支持 + +### ABS + + ```sql + SELECT ABS(field_name) FROM { tb_name | stb_name } [WHERE clause] + ``` + +**功能说明**：获得指定列的绝对值 + +**返回结果类型**：如果输入值为整数，输出值是 UBIGINT 类型。如果输入值是 FLOAT/DOUBLE 数据类型，输出值是 DOUBLE 数据类型。 + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**： + + 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + + 该函数可以应用在普通表和超级表上。 + + 版本2.6.0.x后支持 + +### SQRT + + ```sql + SELECT SQRT(field_name) FROM { tb_name | stb_name } [WHERE clause] + ``` + +**功能说明**：获得指定列的平方根 + +**返回结果类型**：DOUBLE。如果输入值为 NULL，输出值也为 NULL + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上；在超级表查询中使用时，不能应用在 tag 列 + +**嵌套子查询支持**：适用于内层查询和外层查询。 + +**使用说明**： + + 只能与普通列，选择（Selection）、投影（Projection）函数一起使用，不能与聚合（Aggregation）函数一起使用。 + + 该函数可以应用在普通表和超级表上。 + + 版本2.6.0.x后支持 + +### CAST + + ```sql + SELECT CAST(expression AS type_name) FROM { tb_name | stb_name } [WHERE clause] + ``` + +**功能说明**：数据类型转换函数，输入参数 expression 支持普通列、常量、标量函数及它们之间的四则运算，不支持 tag 列，只适用于 select 子句中。 + +**返回结果类型**：CAST 中指定的类型（type_name）。 + +**适用数据类型**：输入参数 expression 的类型可以是除 JSON 外目前所有类型字段（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。 + + 说明： + + 对于不能支持的类型转换会直接报错。 + + 如果输入值为NULL则输出值也为NULL。 + + 对于类型支持但某些值无法正确转换的情况对应的转换后的值以转换函数输出为准。目前可能遇到的几种情况： + 1）BINARY/NCHAR转BIGINT/BIGINT UNSIGNED时可能出现的无效字符情况，例如"a"可能转为0。 + 2）有符号数或TIMESTAMP转BIGINT UNSIGNED可能遇到的溢出问题。 + 3）BIGINT UNSIGNED转BIGINT可能遇到的溢出问题。 + 4）FLOAT/DOUBLE转BIGINT/BIGINT UNSIGNED可能遇到的溢出问题。 + 版本2.6.0.x后支持 + +### CONCAT + + ```sql + SELECT CONCAT(str1|column1, str2|column2, ...) FROM { tb_name | stb_name } [WHERE clause] + ``` + +**功能说明**：字符串连接函数。 + +**返回结果类型**：同输入参数类型，BINARY 或者 NCHAR。 + +**适用数据类型**：输入参数或者全部是 BINARY 格式的字符串或者列，或者全部是 NCHAR 格式的字符串或者列。不能应用在 TAG 列。 + +**说明**： + + 如果输入值为NULL，输出值为NULL。 + 该函数最小参数个数为2个，最大参数个数为8个。 + 该函数可以应用在普通表和超级表上。 + 该函数适用于内层查询和外层查询。 + 版本2.6.0.x后支持 + +### CONCAT_WS + + ``` + SELECT CONCAT_WS(separator, str1|column1, str2|column2, ...) FROM { tb_name | stb_name } [WHERE clause] + ``` + +**功能说明**：带分隔符的字符串连接函数。 + +**返回结果类型**：同输入参数类型，BINARY 或者 NCHAR。 + +**适用数据类型**：输入参数或者全部是 BINARY 格式的字符串或者列，或者全部是 NCHAR 格式的字符串或者列。不能应用在 TAG 列。 + +**说明**： + + 如果separator值为NULL，输出值为NULL。如果separator值不为NULL，其他输入为NULL，输出为空串 + 该函数最小参数个数为3个，最大参数个数为9个。 + 该函数可以应用在普通表和超级表上。 + 该函数适用于内层查询和外层查询。 + 版本2.6.0.x后支持 + +### LENGTH + + ``` + SELECT LENGTH(str|column) FROM { tb_name | stb_name } [WHERE clause] + ``` + +**功能说明**：以字节计数的字符串长度。 + +**返回结果类型**：INT。 + +**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 + +**说明** + + 如果输入值为NULL，输出值为NULL。 + 该函数可以应用在普通表和超级表上。 + 该函数适用于内层查询和外层查询。 + 版本2.6.0.x后支持 + +### CHAR_LENGTH + + ``` + SELECT CHAR_LENGTH(str|column) FROM { tb_name | stb_name } [WHERE clause] + ``` + +**功能说明**：以字符计数的字符串长度。 + +**返回结果类型**：INT。 + +**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 + +**说明** + + 如果输入值为NULL，输出值为NULL。 + 该函数可以应用在普通表和超级表上。 + 该函数适用于内层查询和外层查询。 + 版本2.6.0.x后支持 + +### LOWER + + ``` + SELECT LOWER(str|column) FROM { tb_name | stb_name } [WHERE clause] + ``` + +**功能说明**：将字符串参数值转换为全小写字母。 + +**返回结果类型**：同输入类型。 + +**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 + +**说明**： + + 如果输入值为NULL，输出值为NULL。 + 该函数可以应用在普通表和超级表上。 + 该函数适用于内层查询和外层查询。 + 版本2.6.0.x后支持 + +### UPPER + + ``` + SELECT UPPER(str|column) FROM { tb_name | stb_name } [WHERE clause] + ``` + +**功能说明**：将字符串参数值转换为全大写字母。 + +**返回结果类型**：同输入类型。 + +**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 + +**说明**： + + 如果输入值为NULL，输出值为NULL。 + 该函数可以应用在普通表和超级表上。 + 该函数适用于内层查询和外层查询。 + 版本2.6.0.x后支持 + +### LTRIM + + ``` + SELECT LTRIM(str|column) FROM { tb_name | stb_name } [WHERE clause] + ``` + +**功能说明**：返回清除左边空格后的字符串。 + +**返回结果类型**：同输入类型。 + +**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 + +**说明**： + + 如果输入值为NULL，输出值为NULL。 + 该函数可以应用在普通表和超级表上。 + 该函数适用于内层查询和外层查询。 + 版本2.6.0.x后支持 + +### RTRIM + + ``` + SELECT RTRIM(str|column) FROM { tb_name | stb_name } [WHERE clause] + ``` + +**功能说明**：返回清除右边空格后的字符串。 + +**返回结果类型**：同输入类型。 + +**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 + +**说明**： + + 如果输入值为NULL，输出值为NULL。 + 该函数可以应用在普通表和超级表上。 + 该函数适用于内层查询和外层查询。 + 版本2.6.0.x后支持 + +### SUBSTR + + ``` + SELECT SUBSTR(str,pos[,len]) FROM { tb_name | stb_name } [WHERE clause] + ``` + +**功能说明**：从源字符串 str 中的指定位置 pos 开始取一个长度为 len 的子串并返回。 + +**返回结果类型**：同输入类型。 + +**适用数据类型**：输入参数是 BINARY 类型或者 NCHAR 类型的字符串或者列。不能应用在 TAG 列。 + +**说明**： + + 如果输入值为NULL，输出值为NULL。 + 输入参数pos可以为正数，也可以为负数。如果pos是正数，表示开始位置从字符串开头正数计算。如果pos为负数，表示开始位置从字符串结尾倒数计算。如果输入参数len被忽略，返回的子串包含从pos开始的整个字串。 + 该函数可以应用在普通表和超级表上。 + 该函数适用于内层查询和外层查询。 + 版本2.6.0.x后支持 + +### 四则运算 + +``` +SELECT field_name [+|-|*|/|%][Value|field_name] FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：统计表/超级表中某列或多列间的值加、减、乘、除、取余计算结果。 + +**返回数据类型**：双精度浮点数。 + +**应用字段**：不能应用在 timestamp、binary、nchar、bool 类型字段。 + +**适用于**：表、超级表。 + +**说明**： + +1）支持两列或多列之间进行计算，可使用括号控制计算优先级； + +2）NULL 字段不参与计算，如果参与计算的某行中包含 NULL，该行的计算结果为 NULL。 + +``` +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) +``` + +### STATECOUNT + +``` +SELECT STATECOUNT(field_name, oper, val) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：返回满足某个条件的连续记录的个数，结果作为新的一列追加在每行后面。条件根据参数计算，如果条件为 true 则加 1，条件为 false 则重置为-1，如果数据为 NULL，跳过该条数据。 + +**参数范围**： + +- oper : LT (小于)、GT（大于）、LE（小于等于）、GE（大于等于）、NE（不等于）、EQ（等于），不区分大小写。 +- val : 数值型 + +**返回结果类型**：整形。 + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上。 + +**嵌套子查询支持**：不支持应用在子查询上。 + +**支持的版本**：2.6 开始的版本。 + +**说明**： + +- 该函数可以应用在普通表上，在由 GROUP BY 划分出单独时间线的情况下用于超级表（也即 GROUP BY tbname） + +- 不能和窗口操作一起使用，例如 interval/state_window/session_window。 + +**示例**： + +``` +taos> select ts,dbig from statef2; + ts | dbig | +======================================================== +2021-10-15 00:31:33.000000000 | 1 | +2021-10-17 00:31:31.000000000 | NULL | +2021-12-24 00:31:34.000000000 | 2 | +2022-01-01 08:00:05.000000000 | 19 | +2022-01-01 08:00:06.000000000 | NULL | +2022-01-01 08:00:07.000000000 | 9 | +Query OK, 6 row(s) in set (0.002977s) + +taos> select stateCount(dbig,GT,2) from statef2; +ts | dbig | statecount(dbig,gt,2) | +================================================================================ +2021-10-15 00:31:33.000000000 | 1 | -1 | +2021-10-17 00:31:31.000000000 | NULL | NULL | +2021-12-24 00:31:34.000000000 | 2 | -1 | +2022-01-01 08:00:05.000000000 | 19 | 1 | +2022-01-01 08:00:06.000000000 | NULL | NULL | +2022-01-01 08:00:07.000000000 | 9 | 2 | +Query OK, 6 row(s) in set (0.002791s) +``` + +### STATEDURATION + +``` +SELECT stateDuration(field_name, oper, val, unit) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：返回满足某个条件的连续记录的时间长度，结果作为新的一列追加在每行后面。条件根据参数计算，如果条件为 true 则加上两个记录之间的时间长度（第一个满足条件的记录时间长度记为 0），条件为 false 则重置为-1，如果数据为 NULL，跳过该条数据。 + +**参数范围**： + +- oper : LT (小于)、GT（大于）、LE（小于等于）、GE（大于等于）、NE（不等于）、EQ（等于），不区分大小写。 +- val : 数值型 +- unit : 时间长度的单位，范围[1s、1m、1h ]，不足一个单位舍去。默认为 1s。 + +**返回结果类型**：整形。 + +**适用数据类型**：不能应用在 timestamp、binary、nchar、bool 类型字段上。 + +**嵌套子查询支持**：不支持应用在子查询上。 + +**支持的版本**：2.6 开始的版本。 + +**说明**： + +- 该函数可以应用在普通表上，在由 GROUP BY 划分出单独时间线的情况下用于超级表（也即 GROUP BY tbname） + +- 不能和窗口操作一起使用，例如 interval/state_window/session_window。 + +**示例**： + +``` +taos> select ts,dbig from statef2; + ts | dbig | +======================================================== +2021-10-15 00:31:33.000000000 | 1 | +2021-10-17 00:31:31.000000000 | NULL | +2021-12-24 00:31:34.000000000 | 2 | +2022-01-01 08:00:05.000000000 | 19 | +2022-01-01 08:00:06.000000000 | NULL | +2022-01-01 08:00:07.000000000 | 9 | +Query OK, 6 row(s) in set (0.002407s) + +taos> select stateDuration(dbig,GT,2) from statef2; +ts | dbig | stateduration(dbig,gt,2) | +=================================================================================== +2021-10-15 00:31:33.000000000 | 1 | -1 | +2021-10-17 00:31:31.000000000 | NULL | NULL | +2021-12-24 00:31:34.000000000 | 2 | -1 | +2022-01-01 08:00:05.000000000 | 19 | 0 | +2022-01-01 08:00:06.000000000 | NULL | NULL | +2022-01-01 08:00:07.000000000 | 9 | 2 | +Query OK, 6 row(s) in set (0.002613s) +``` + +## 时间函数 + +从 2.6.0.0 版本开始，TDengine 查询引擎支持以下时间相关函数： + +### NOW + +```sql +SELECT NOW() FROM { tb_name | stb_name } [WHERE clause]; +SELECT select_expr FROM { tb_name | stb_name } WHERE ts_col cond_operatior NOW(); +INSERT INTO tb_name VALUES (NOW(), ...); +``` + +**功能说明**：返回客户端当前系统时间。 + +**返回结果数据类型**：TIMESTAMP 时间戳类型。 + +**应用字段**：在 WHERE 或 INSERT 语句中使用时只能作用于 TIMESTAMP 类型的字段。 + +**适用于**：表、超级表。 + +**说明**： +1）支持时间加减操作，如 NOW() + 1s, 支持的时间单位如下： +b(纳秒)、u(微秒)、a(毫秒)、s(秒)、m(分)、h(小时)、d(天)、w(周)。 +2）返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 + +**示例**： + +```sql +taos> SELECT NOW() FROM meters; + now() | +========================== + 2022-02-02 02:02:02.456 | +Query OK, 1 row(s) in set (0.002093s) + +taos> SELECT NOW() + 1h FROM meters; + now() + 1h | +========================== + 2022-02-02 03:02:02.456 | +Query OK, 1 row(s) in set (0.002093s) + +taos> SELECT COUNT(voltage) FROM d1001 WHERE ts < NOW(); + count(voltage) | +============================= + 5 | +Query OK, 5 row(s) in set (0.004475s) + +taos> INSERT INTO d1001 VALUES (NOW(), 10.2, 219, 0.32); +Query OK, 1 of 1 row(s) in database (0.002210s) +``` + +### TODAY + +```sql +SELECT TODAY() FROM { tb_name | stb_name } [WHERE clause]; +SELECT select_expr FROM { tb_name | stb_name } WHERE ts_col cond_operatior TODAY()]; +INSERT INTO tb_name VALUES (TODAY(), ...); +``` + +**功能说明**：返回客户端当日零时的系统时间。 + +**返回结果数据类型**：TIMESTAMP 时间戳类型。 + +**应用字段**：在 WHERE 或 INSERT 语句中使用时只能作用于 TIMESTAMP 类型的字段。 + +**适用于**：表、超级表。 + +**说明**： +1）支持时间加减操作，如 TODAY() + 1s, 支持的时间单位如下： +b(纳秒)，u(微秒)，a(毫秒)，s(秒)，m(分)，h(小时)，d(天)，w(周)。 +2）返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 + +**示例**： + +```sql +taos> SELECT TODAY() FROM meters; + today() | +========================== + 2022-02-02 00:00:00.000 | +Query OK, 1 row(s) in set (0.002093s) + +taos> SELECT TODAY() + 1h FROM meters; + today() + 1h | +========================== + 2022-02-02 01:00:00.000 | +Query OK, 1 row(s) in set (0.002093s) + +taos> SELECT COUNT(voltage) FROM d1001 WHERE ts < TODAY(); + count(voltage) | +============================= + 5 | +Query OK, 5 row(s) in set (0.004475s) + +taos> INSERT INTO d1001 VALUES (TODAY(), 10.2, 219, 0.32); +Query OK, 1 of 1 row(s) in database (0.002210s) +``` + +### TIMEZONE + +```sql +SELECT TIMEZONE() FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：返回客户端当前时区信息。 + +**返回结果数据类型**：BINARY 类型。 + +**应用字段**：无 + +**适用于**：表、超级表。 + +**示例**： + +```sql +taos> SELECT TIMEZONE() FROM meters; + timezone() | +================================= + UTC (UTC, +0000) | +Query OK, 1 row(s) in set (0.002093s) +``` + +### TO_ISO8601 + +```sql +SELECT TO_ISO8601(ts_val | ts_col) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：将 UNIX 时间戳转换成为 ISO8601 标准的日期时间格式，并附加客户端时区信息。 + +**返回结果数据类型**：BINARY 类型。 + +**应用字段**：UNIX 时间戳常量或是 TIMESTAMP 类型的列 + +**适用于**：表、超级表。 + +**说明**：如果输入是 UNIX 时间戳常量，返回格式精度由时间戳的位数决定，如果输入是 TIMSTAMP 类型的列，返回格式的时间戳精度与当前 DATABASE 设置的时间精度一致。 + +**示例**： + +```sql +taos> SELECT TO_ISO8601(1643738400) FROM meters; + to_iso8601(1643738400) | +============================== + 2022-02-02T02:00:00+0800 | + +taos> SELECT TO_ISO8601(ts) FROM meters; + to_iso8601(ts) | +============================== + 2022-02-02T02:00:00+0800 | + 2022-02-02T02:00:00+0800 | + 2022-02-02T02:00:00+0800 | +``` + +### TO_UNIXTIMESTAMP + +```sql +SELECT TO_UNIXTIMESTAMP(datetime_string | ts_col) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：将日期时间格式的字符串转换成为 UNIX 时间戳。 + +**返回结果数据类型**：长整型 INT64。 + +**应用字段**：字符串常量或是 BINARY/NCHAR 类型的列。 + +**适用于**：表、超级表。 + +**说明**： +1）输入的日期时间字符串须符合 ISO8601/RFC3339 标准，无法转换的字符串格式将返回 0。 +2）返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 + +**示例**： + +```sql +taos> SELECT TO_UNIXTIMESTAMP("2022-02-02T02:00:00.000Z") FROM meters; +to_unixtimestamp("2022-02-02T02:00:00.000Z") | +============================================== + 1643767200000 | + +taos> SELECT TO_UNIXTIMESTAMP(col_binary) FROM meters; + to_unixtimestamp(col_binary) | +======================================== + 1643767200000 | + 1643767200000 | + 1643767200000 | +``` + +### TIMETRUNCATE + +```sql +SELECT TIMETRUNCATE(ts_val | datetime_string | ts_col, time_unit) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：将时间戳按照指定时间单位 time_unit 进行截断。 + +**返回结果数据类型**：TIMESTAMP 时间戳类型。 + +**应用字段**：UNIX 时间戳，日期时间格式的字符串，或者 TIMESTAMP 类型的列。 + +**适用于**：表、超级表。 + +**说明**： +1）支持的时间单位 time_unit 如下： +1u(微秒)，1a(毫秒)，1s(秒)，1m(分)，1h(小时)，1d(天)。 +2）返回的时间戳精度与当前 DATABASE 设置的时间精度一致。 + +**示例**： + +```sql +taos> SELECT TIMETRUNCATE(1643738522000, 1h) FROM meters; + timetruncate(1643738522000, 1h) | +=================================== + 2022-02-02 02:00:00.000 | +Query OK, 1 row(s) in set (0.001499s) + +taos> SELECT TIMETRUNCATE("2022-02-02 02:02:02", 1h) FROM meters; + timetruncate("2022-02-02 02:02:02", 1h) | +=========================================== + 2022-02-02 02:00:00.000 | +Query OK, 1 row(s) in set (0.003903s) + +taos> SELECT TIMETRUNCATE(ts, 1h) FROM meters; + timetruncate(ts, 1h) | +========================== + 2022-02-02 02:00:00.000 | + 2022-02-02 02:00:00.000 | + 2022-02-02 02:00:00.000 | +Query OK, 3 row(s) in set (0.003903s) +``` + +### TIMEDIFF + +```sql +SELECT TIMEDIFF(ts_val1 | datetime_string1 | ts_col1, ts_val2 | datetime_string2 | ts_col2 [, time_unit]) FROM { tb_name | stb_name } [WHERE clause]; +``` + +**功能说明**：计算两个时间戳之间的差值，并近似到时间单位 time_unit 指定的精度。 + +**返回结果数据类型**：长整型 INT64。 + +**应用字段**：UNIX 时间戳，日期时间格式的字符串，或者 TIMESTAMP 类型的列。 + +**适用于**：表、超级表。 + +**说明**： +1）支持的时间单位 time_unit 如下： +1u(微秒)，1a(毫秒)，1s(秒)，1m(分)，1h(小时)，1d(天)。 +2）如果时间单位 time_unit 未指定， 返回的时间差值精度与当前 DATABASE 设置的时间精度一致。 + +**示例**： + +```sql +taos> SELECT TIMEDIFF(1643738400000, 1643742000000) FROM meters; + timediff(1643738400000, 1643742000000) | +========================================= + 3600000 | +Query OK, 1 row(s) in set (0.002553s) +taos> SELECT TIMEDIFF(1643738400000, 1643742000000, 1h) FROM meters; + timediff(1643738400000, 1643742000000, 1h) | +============================================= + 1 | +Query OK, 1 row(s) in set (0.003726s) + +taos> SELECT TIMEDIFF("2022-02-02 03:00:00", "2022-02-02 02:00:00", 1h) FROM meters; + timediff("2022-02-02 03:00:00", "2022-02-02 02:00:00", 1h) | +============================================================= + 1 | +Query OK, 1 row(s) in set (0.001937s) + +taos> SELECT TIMEDIFF(ts_col1, ts_col2, 1h) FROM meters; + timediff(ts_col1, ts_col2, 1h) | +=================================== + 1 | +Query OK, 1 row(s) in set (0.001937s) +``` diff --git a/docs-cn/14-reference/01-taos-sql/08-interval.md b/docs-cn/14-reference/01-taos-sql/08-interval.md new file mode 100644 index 0000000000000000000000000000000000000000..362ca1bef6ffa2b1e01d739907da5ebff726a500 --- /dev/null +++ b/docs-cn/14-reference/01-taos-sql/08-interval.md @@ -0,0 +1,113 @@ +--- +sidebar_label: 按窗口切分聚合 +--- + +# 按窗口切分聚合 + +TDengine 支持按时间段窗口切分方式进行聚合结果查询，比如温度传感器每秒采集一次数据，但需查询每隔 10 分钟的温度平均值。这种场景下可以使用窗口子句来获得需要的查询结果。 +窗口子句用于针对查询的数据集合进行按照窗口切分成为查询子集并进行聚合，窗口包含时间窗口（time window）、状态窗口（status window）、会话窗口（session window）三种窗口。其中时间窗口又可划分为滑动时间窗口和翻转时间窗口。 + +## 时间窗口 + +INTERVAL 子句用于产生相等时间周期的窗口，SLIDING 用以指定窗口向前滑动的时间。每次执行的查询是一个时间窗口，时间窗口随着时间流动向前滑动。在定义连续查询的时候需要指定时间窗口（time window ）大小和每次前向增量时间（forward sliding times）。如图，[t0s, t0e] ，[t1s , t1e]， [t2s, t2e] 是分别是执行三次连续查询的时间窗口范围，窗口的前向滑动的时间范围 sliding time 标识 。查询过滤、聚合等操作按照每个时间窗口为独立的单位执行。当 SLIDING 与 INTERVAL 相等的时候，滑动窗口即为翻转窗口。 + + + +INTERVAL 和 SLIDING 子句需要配合聚合和选择函数来使用。以下 SQL 语句非法： + +``` +SELECT * FROM temp_table INTERVAL(1S) +``` + +SLIDING 的向前滑动的时间不能超过一个窗口的时间范围。以下语句非法： + +``` +SELECT COUNT(*) FROM temp_table INTERVAL(1D) SLIDING(2D) +``` + +当 SLIDING 与 INTERVAL 取值相等的时候，滑动窗口即为翻转窗口。 +_ 聚合时间段的窗口宽度由关键词 INTERVAL 指定，最短时间间隔 10 毫秒（10a）；并且支持偏移 offset（偏移必须小于间隔），也即时间窗口划分与“UTC 时刻 0”相比的偏移量。SLIDING 语句用于指定聚合时间段的前向增量，也即每次窗口向前滑动的时长。 +_ 从 2.1.5.0 版本开始，INTERVAL 语句允许的最短时间间隔调整为 1 微秒（1u），当然如果所查询的 DATABASE 的时间精度设置为毫秒级，那么允许的最短时间间隔为 1 毫秒（1a）。 \* **注意**：用到 INTERVAL 语句时，除非极特殊的情况，都要求把客户端和服务端的 taos.cfg 配置文件中的 timezone 参数配置为相同的取值，以避免时间处理函数频繁进行跨时区转换而导致的严重性能影响。 + +## 状态窗口 + +使用整数（布尔值）或字符串来标识产生记录时候设备的状态量。产生的记录如果具有相同的状态量数值则归属于同一个状态窗口，数值改变后该窗口关闭。如下图所示，根据状态量确定的状态窗口分别是[2019-04-28 14:22:07，2019-04-28 14:22:10]和[2019-04-28 14:22:11，2019-04-28 14:22:12]两个。（状态窗口暂不支持对超级表使用） + + + +使用 STATE_WINDOW 来确定状态窗口划分的列。例如： + +``` +SELECT COUNT(*), FIRST(ts), status FROM temp_tb_1 STATE_WINDOW(status) +``` + +## 会话窗口 + +会话窗口根据记录的时间戳主键的值来确定是否属于同一个会话。如下图所示，如果设置时间戳的连续的间隔小于等于 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 秒）。 + + + +在 tol_value 时间间隔范围内的结果都认为归属于同一个窗口，如果连续的两条记录的时间超过 tol_val，则自动开启下一个窗口。（会话窗口暂不支持对超级表使用） + +``` + +SELECT COUNT(*), FIRST(ts) FROM temp_tb_1 SESSION(ts, tol_val) +``` + +这种类型的查询语法如下： + +``` +SELECT function_list FROM tb_name + [WHERE where_condition] + [SESSION(ts_col, tol_val)] + [STATE_WINDOW(col)] + [INTERVAL(interval [, offset]) [SLIDING sliding]] + [FILL({NONE | VALUE | PREV | NULL | LINEAR | NEXT})] + +SELECT function_list FROM stb_name + [WHERE where_condition] + [INTERVAL(interval [, offset]) [SLIDING sliding]] + [FILL({NONE | VALUE | PREV | NULL | LINEAR | NEXT})] + [GROUP BY tags] +``` + +- 在聚合查询中，function_list 位置允许使用聚合和选择函数，并要求每个函数仅输出单个结果（例如：COUNT、AVG、SUM、STDDEV、LEASTSQUARES、PERCENTILE、MIN、MAX、FIRST、LAST），而不能使用具有多行输出结果的函数（例如：DIFF 以及四则运算）。 +- 此外也 LAST_ROW 查询也不能与窗口聚合同时出现。 +- 标量函数（如：CEIL/FLOOR 等）也不能使用在窗口聚合查询中。 +- + +- WHERE 语句可以指定查询的起止时间和其他过滤条件。 +- FILL 语句指定某一窗口区间数据缺失的情况下的填充模式。填充模式包括以下几种： + 1. 不进行填充：NONE（默认填充模式）。 + 2. VALUE 填充：固定值填充，此时需要指定填充的数值。例如：FILL(VALUE, 1.23)。 + 3. PREV 填充：使用前一个非 NULL 值填充数据。例如：FILL(PREV)。 + 4. NULL 填充：使用 NULL 填充数据。例如：FILL(NULL)。 + 5. LINEAR 填充：根据前后距离最近的非 NULL 值做线性插值填充。例如：FILL(LINEAR)。 + 6. NEXT 填充：使用下一个非 NULL 值填充数据。例如：FILL(NEXT)。 + +:::info + +1. 使用 FILL 语句的时候可能生成大量的填充输出，务必指定查询的时间区间。针对每次查询，系统可返回不超过 1 千万条具有插值的结果。 +2. 在时间维度聚合中，返回的结果中时间序列严格单调递增。 +3. 如果查询对象是超级表，则聚合函数会作用于该超级表下满足值过滤条件的所有表的数据。如果查询中没有使用 GROUP BY 语句，则返回的结果按照时间序列严格单调递增；如果查询中使用了 GROUP BY 语句分组，则返回结果中每个 GROUP 内不按照时间序列严格单调递增。 + +::: + +时间聚合也常被用于连续查询场景，可以参考文档 [连续查询(Continuous Query)](https://www.taosdata.com/cn/documentation/advanced-features#continuous-query)。 + +## 示例 + +智能电表的建表语句如下： + +``` +CREATE TABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT); +``` + +针对智能电表采集的数据，以 10 分钟为一个阶段，计算过去 24 小时的电流数据的平均值、最大值、电流的中位数。如果没有计算值，用前一个非 NULL 值填充。使用的查询语句如下： + +``` +SELECT AVG(current), MAX(current), APERCENTILE(current, 50) FROM meters + WHERE ts>=NOW-1d and ts<=now + INTERVAL(10m) + FILL(PREV); +``` diff --git a/docs-cn/14-reference/01-taos-sql/09-limit.md b/docs-cn/14-reference/01-taos-sql/09-limit.md new file mode 100644 index 0000000000000000000000000000000000000000..c4e7c6b2f03f3a3f469d32f713bf15bba32f54bc --- /dev/null +++ b/docs-cn/14-reference/01-taos-sql/09-limit.md @@ -0,0 +1,51 @@ +--- +sidebar_label: 边界限制 +--- + +# 边界限制 + +## 一般限制 + +- 数据库名最大长度为 32。 +- 表名最大长度为 192，每行数据最大长度 16k 个字符, 从 2.1.7.0 版本开始，每行数据最大长度 48k 个字符（注意：数据行内每个 BINARY/NCHAR 类型的列还会额外占用 2 个字节的存储位置）。 +- 列名最大长度为 64，最多允许 1024 列，最少需要 2 列，第一列必须是时间戳。（从 2.1.7.0 版本开始，改为最多允许 4096 列） +- 标签名最大长度为 64，最多允许 128 个，可以 1 个，一个表中标签值的总长度不超过 16k 个字符。 +- SQL 语句最大长度 1048576 个字符，也可通过客户端配置参数 maxSQLLength 修改，取值范围 65480 ~ 1048576。 +- SELECT 语句的查询结果，最多允许返回 1024 列（语句中的函数调用可能也会占用一些列空间），超限时需要显式指定较少的返回数据列，以避免语句执行报错。（从 2.1.7.0 版本开始，改为最多允许 4096 列） +- 库的数目，超级表的数目、表的数目，系统不做限制，仅受系统资源限制。 + +## GROUP BY 的限制 + +TAOS SQL 支持对标签、TBNAME 进行 GROUP BY 操作，也支持普通列进行 GROUP BY，前提是：仅限一列且该列的唯一值小于 10 万个。注意：group by 不支持 float,double 类型。 + +## IS NOT NULL 的限制 + +IS NOT NULL 与不为空的表达式适用范围。 + +IS NOT NULL 支持所有类型的列。不为空的表达式为 <\>""，仅对非数值类型的列适用。 + +## ORDER BY 的限制 + +- 非超级表只能有一个 order by. +- 超级表最多两个 order by， 并且第二个必须为 ts. +- order by tag，必须和 group by tag 一起，并且是同一个 tag。 tbname 和 tag 一样逻辑。 只适用于超级表 +- order by 普通列，必须和 group by 一起或者和 top/bottom 一起，并且是同一个普通列。 适用于超级表和普通表。如果同时存在 group by 和 top/bottom 一起，order by 优先必须和 group by 同一列。 +- order by ts. 适用于超级表和普通表。 +- order by ts 同时含有 group by 时 针对 group 内部用 ts 排序 + +## 表(列)名合法性说明 + +TDengine 中的表（列）名命名规则如下： +只能由字母、数字、下划线构成，数字不能在首位，长度不能超过 192 字节，不区分大小写。这里表名称不包括数据库名的前缀和分隔符。 + +转移后表（列）名规则： +为了兼容支持更多形式的表（列）名，TDengine 引入新的转义符 "`"。可用让表名与关键词不冲突，同时不受限于上述表名称合法性约束检查，转义符不计入表名称的长度。 +转义后的表（列）名同样受到长度限制要求，且长度计算的时候不计算转义符。使用转义字符以后，不再对转义字符中的内容进行大小写统一。 + +例如： +\`aBc\` 和 \`abc\` 是不同的表（列）名，但是 abc 和 aBc 是相同的表（列）名。 + +需要注意的是转义字符中的内容必须是可打印字符。 + +支持版本 +支持转义符的功能从 2.3.0.1 版本开始。 \ No newline at end of file diff --git a/docs-cn/14-reference/01-taos-sql/10-json.md b/docs-cn/14-reference/01-taos-sql/10-json.md new file mode 100644 index 0000000000000000000000000000000000000000..6a06bd30ea9eec9eb8e1471d60f74416f6e45e96 --- /dev/null +++ b/docs-cn/14-reference/01-taos-sql/10-json.md @@ -0,0 +1,91 @@ +--- +sidebar_label: JSON 类型使用说明 +--- + +# JSON 类型使用说明 + +## 语法说明 + +1. 创建 json 类型 tag + + ``` + create stable s1 (ts timestamp, v1 int) tags (info json) + + create table s1_1 using s1 tags ('{"k1": "v1"}') + ``` + +2. json 取值操作符 -> + + ``` + select * from s1 where info->'k1' = 'v1' + + select info->'k1' from s1 + ``` + +3. json key 是否存在操作符 contains + + ``` + select * from s1 where info contains 'k2' + + select * from s1 where info contains 'k1' + ``` + +## 支持的操作 + +1. 在 where 条件中时，支持函数 match/nmatch/between and/like/and/or/is null/is no null，不支持 in + + ``` + 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 is null; + + select * from s1 where info->'k1' is not null + ``` + +2. 支持 json tag 放在 group by、order by、join 子句、union all 以及子查询中，比如 group by json->'key' + +3. 支持 distinct 操作. + + ``` + select distinct info->'k1' from s1 + ``` + +4. 标签操作 + + 支持修改 json 标签值（全量覆盖） + + 支持修改 json 标签名 + + 不支持添加 json 标签、删除 json 标签、修改 json 标签列宽 + +## 其他约束条件 + +1. 只有标签列可以使用 json 类型，如果用 json 标签，标签列只能有一个。 + +2. 长度限制：json 中 key 的长度不能超过 256，并且 key 必须为可打印 ascii 字符；json 字符串总长度不超过 4096 个字节。 + +3. json 格式限制： + + 1. json 输入字符串可以为空（"","\t"," "或 null）或 object，不能为非空的字符串，布尔型和数组。 + 2. object 可为{}，如果 object 为{}，则整个 json 串记为空。key 可为""，若 key 为""，则 json 串中忽略该 k-v 对。 + 3. value 可以为数字(int/double)或字符串或 bool 或 null，暂不可以为数组。不允许嵌套。 + 4. 若 json 字符串中出现两个相同的 key，则第一个生效。 + 5. json 字符串里暂不支持转义。 + +4. 当查询 json 中不存在的 key 时，返回 NULL + +5. 当 json tag 作为子查询结果时，不再支持上层查询继续对子查询中的 json 串做解析查询。 + + 比如暂不支持 + + ``` + select jtag->'key' from (select jtag from stable) + ``` + + 不支持 + + ``` + select jtag->'key' from (select jtag from stable) where jtag->'key'>0 + ``` diff --git a/docs-cn/14-reference/01-taos-sql/11-escape.md b/docs-cn/14-reference/01-taos-sql/11-escape.md new file mode 100644 index 0000000000000000000000000000000000000000..be27dd4e7b6dd59264d8740f47d4baaf4182a678 --- /dev/null +++ b/docs-cn/14-reference/01-taos-sql/11-escape.md @@ -0,0 +1,28 @@ +# 转义字符说明 + +## 转义字符表 + +| 字符序列 | **代表的字符** | +| :------: | -------------- | +| `\'` | 单引号' | +| `\"` | 双引号" | +| \n | 换行符 | +| \r | 回车符 | +| \t | tab 符 | +| `\\` | 斜杠\ | +| `\%` | % 规则见下 | +| `\_` | \_ 规则见下 | + +:::note +转义符的功能从 2.4.0.4 版本开始 + +::: + +## 转义字符使用规则 + +1. 标识符里有转义字符（数据库名、表名、列名） + 1. 普通标识符： 直接提示错误的标识符，因为标识符规定必须是数字、字母和下划线，并且不能以数字开头。 + 2. 反引号``标识符： 保持原样，不转义 +2. 数据里有转义字符 + 1. 遇到上面定义的转义字符会转义（%和\_见下面说明），如果没有匹配的转义字符会忽略掉转义符\。 + 2. 对于%和*，因为在 like 里这两个字符是通配符，所以在模式匹配 like 里用`\%`%和`\_`表示字符里本身的%和*，如果在 like 模式匹配上下文之外使用`\%`或`\_`，则它们的计算结果为字符串`\%`和`\_`，而不是%和\_。 diff --git a/docs-cn/14-reference/01-taos-sql/12-errorcode.md b/docs-cn/14-reference/01-taos-sql/12-errorcode.md new file mode 100644 index 0000000000000000000000000000000000000000..2013e1e640d10bbd09572ca1d9c4ba12a38620d8 --- /dev/null +++ b/docs-cn/14-reference/01-taos-sql/12-errorcode.md @@ -0,0 +1,176 @@ +--- +sidebar_label: 错误码 +--- + +# 错误码以及对应的十进制码 + +| 状态码 | 模 | 错误码（十六进制） | 错误描述 | 错误码（十进制） | +| :-------------------------------------- | :-: | :----------------: | :------------------------------------------- | :--------------- | +| TSDB_CODE_RPC_ACTION_IN_PROGRESS | 0 | 0x0001 | "Action in progress" | -2147483647 | +| TSDB_CODE_RPC_AUTH_REQUIRED | 0 | 0x0002 | "Authentication required" | -2147483646 | +| TSDB_CODE_RPC_AUTH_FAILURE | 0 | 0x0003 | "Authentication failure" | -2147483645 | +| TSDB_CODE_RPC_REDIRECT | 0 | 0x0004 | "Redirect" | -2147483644 | +| TSDB_CODE_RPC_NOT_READY | 0 | 0x0005 | "System not ready" | -2147483643 | +| TSDB_CODE_RPC_ALREADY_PROCESSED | 0 | 0x0006 | "Message already processed" | -2147483642 | +| TSDB_CODE_RPC_LAST_SESSION_NOT_FINISHED | 0 | 0x0007 | "Last session not finished" | -2147483641 | +| TSDB_CODE_RPC_MISMATCHED_LINK_ID | 0 | 0x0008 | "Mismatched meter id" | -2147483640 | +| TSDB_CODE_RPC_TOO_SLOW | 0 | 0x0009 | "Processing of request timed out" | -2147483639 | +| TSDB_CODE_RPC_MAX_SESSIONS | 0 | 0x000A | "Number of sessions reached limit" | -2147483638 | +| TSDB_CODE_RPC_NETWORK_UNAVAIL | 0 | 0x000B | "Unable to establish connection" | -2147483637 | +| TSDB_CODE_RPC_APP_ERROR | 0 | 0x000C | "Unexpected generic error in RPC" | -2147483636 | +| TSDB_CODE_RPC_UNEXPECTED_RESPONSE | 0 | 0x000D | "Unexpected response" | -2147483635 | +| TSDB_CODE_RPC_INVALID_VALUE | 0 | 0x000E | "Invalid value" | -2147483634 | +| TSDB_CODE_RPC_INVALID_TRAN_ID | 0 | 0x000F | "Invalid transaction id" | -2147483633 | +| TSDB_CODE_RPC_INVALID_SESSION_ID | 0 | 0x0010 | "Invalid session id" | -2147483632 | +| TSDB_CODE_RPC_INVALID_MSG_TYPE | 0 | 0x0011 | "Invalid message type" | -2147483631 | +| TSDB_CODE_RPC_INVALID_RESPONSE_TYPE | 0 | 0x0012 | "Invalid response type" | -2147483630 | +| TSDB_CODE_RPC_INVALID_TIME_STAMP | 0 | 0x0013 | "Invalid timestamp" | -2147483629 | +| TSDB_CODE_COM_OPS_NOT_SUPPORT | 0 | 0x0100 | "Operation not supported" | -2147483392 | +| TSDB_CODE_COM_MEMORY_CORRUPTED | 0 | 0x0101 | "Memory corrupted" | -2147483391 | +| TSDB_CODE_COM_OUT_OF_MEMORY | 0 | 0x0102 | "Out of memory" | -2147483390 | +| TSDB_CODE_COM_INVALID_CFG_MSG | 0 | 0x0103 | "Invalid config message" | -2147483389 | +| TSDB_CODE_COM_FILE_CORRUPTED | 0 | 0x0104 | "Data file corrupted" | -2147483388 | +| TSDB_CODE_TSC_INVALID_OPERATION | 0 | 0x0200 | "Invalid SQL statement" | -2147483136 | +| TSDB_CODE_TSC_INVALID_QHANDLE | 0 | 0x0201 | "Invalid qhandle" | -2147483135 | +| TSDB_CODE_TSC_INVALID_TIME_STAMP | 0 | 0x0202 | "Invalid combination of client/service time" | -2147483134 | +| TSDB_CODE_TSC_INVALID_VALUE | 0 | 0x0203 | "Invalid value in client" | -2147483133 | +| TSDB_CODE_TSC_INVALID_VERSION | 0 | 0x0204 | "Invalid client version" | -2147483132 | +| TSDB_CODE_TSC_INVALID_IE | 0 | 0x0205 | "Invalid client ie" | -2147483131 | +| TSDB_CODE_TSC_INVALID_FQDN | 0 | 0x0206 | "Invalid host name" | -2147483130 | +| TSDB_CODE_TSC_INVALID_USER_LENGTH | 0 | 0x0207 | "Invalid user name" | -2147483129 | +| TSDB_CODE_TSC_INVALID_PASS_LENGTH | 0 | 0x0208 | "Invalid password" | -2147483128 | +| TSDB_CODE_TSC_INVALID_DB_LENGTH | 0 | 0x0209 | "Database name too long" | -2147483127 | +| TSDB_CODE_TSC_INVALID_TABLE_ID_LENGTH | 0 | 0x020A | "Table name too long" | -2147483126 | +| TSDB_CODE_TSC_INVALID_CONNECTION | 0 | 0x020B | "Invalid connection" | -2147483125 | +| TSDB_CODE_TSC_OUT_OF_MEMORY | 0 | 0x020C | "System out of memory" | -2147483124 | +| TSDB_CODE_TSC_NO_DISKSPACE | 0 | 0x020D | "System out of disk space" | -2147483123 | +| TSDB_CODE_TSC_QUERY_CACHE_ERASED | 0 | 0x020E | "Query cache erased" | -2147483122 | +| TSDB_CODE_TSC_QUERY_CANCELLED | 0 | 0x020F | "Query terminated" | -2147483121 | +| TSDB_CODE_TSC_SORTED_RES_TOO_MANY | 0 | 0x0210 | "Result set too large to be sorted" | -2147483120 | +| TSDB_CODE_TSC_APP_ERROR | 0 | 0x0211 | "Application error" | -2147483119 | +| TSDB_CODE_TSC_ACTION_IN_PROGRESS | 0 | 0x0212 | "Action in progress" | -2147483118 | +| TSDB_CODE_TSC_DISCONNECTED | 0 | 0x0213 | "Disconnected from service" | -2147483117 | +| TSDB_CODE_TSC_NO_WRITE_AUTH | 0 | 0x0214 | "No write permission" | -2147483116 | +| TSDB_CODE_MND_MSG_NOT_PROCESSED | 0 | 0x0300 | "Message not processed" | -2147482880 | +| TSDB_CODE_MND_ACTION_IN_PROGRESS | 0 | 0x0301 | "Message is progressing" | -2147482879 | +| TSDB_CODE_MND_ACTION_NEED_REPROCESSED | 0 | 0x0302 | "Messag need to be reprocessed" | -2147482878 | +| TSDB_CODE_MND_NO_RIGHTS | 0 | 0x0303 | "Insufficient privilege for operation" | -2147482877 | +| TSDB_CODE_MND_APP_ERROR | 0 | 0x0304 | "Unexpected generic error in mnode" | -2147482876 | +| TSDB_CODE_MND_INVALID_CONNECTION | 0 | 0x0305 | "Invalid message connection" | -2147482875 | +| TSDB_CODE_MND_INVALID_MSG_VERSION | 0 | 0x0306 | "Incompatible protocol version" | -2147482874 | +| TSDB_CODE_MND_INVALID_MSG_LEN | 0 | 0x0307 | "Invalid message length" | -2147482873 | +| TSDB_CODE_MND_INVALID_MSG_TYPE | 0 | 0x0308 | "Invalid message type" | -2147482872 | +| TSDB_CODE_MND_TOO_MANY_SHELL_CONNS | 0 | 0x0309 | "Too many connections" | -2147482871 | +| TSDB_CODE_MND_OUT_OF_MEMORY | 0 | 0x030A | "Out of memory in mnode" | -2147482870 | +| TSDB_CODE_MND_INVALID_SHOWOBJ | 0 | 0x030B | "Data expired" | -2147482869 | +| TSDB_CODE_MND_INVALID_QUERY_ID | 0 | 0x030C | "Invalid query id" | -2147482868 | +| TSDB_CODE_MND_INVALID_STREAM_ID | 0 | 0x030D | "Invalid stream id" | -2147482867 | +| TSDB_CODE_MND_INVALID_CONN_ID | 0 | 0x030E | "Invalid connection id" | -2147482866 | +| TSDB_CODE_MND_SDB_OBJ_ALREADY_THERE | 0 | 0x0320 | "Object already there" | -2147482848 | +| TSDB_CODE_MND_SDB_ERROR | 0 | 0x0321 | "Unexpected generic error in sdb" | -2147482847 | +| TSDB_CODE_MND_SDB_INVALID_TABLE_TYPE | 0 | 0x0322 | "Invalid table type" | -2147482846 | +| TSDB_CODE_MND_SDB_OBJ_NOT_THERE | 0 | 0x0323 | "Object not there" | -2147482845 | +| TSDB_CODE_MND_SDB_INVAID_META_ROW | 0 | 0x0324 | "Invalid meta row" | -2147482844 | +| TSDB_CODE_MND_SDB_INVAID_KEY_TYPE | 0 | 0x0325 | "Invalid key type" | -2147482843 | +| TSDB_CODE_MND_DNODE_ALREADY_EXIST | 0 | 0x0330 | "DNode already exists" | -2147482832 | +| TSDB_CODE_MND_DNODE_NOT_EXIST | 0 | 0x0331 | "DNode does not exist" | -2147482831 | +| TSDB_CODE_MND_VGROUP_NOT_EXIST | 0 | 0x0332 | "VGroup does not exist" | -2147482830 | +| TSDB_CODE_MND_NO_REMOVE_MASTER | 0 | 0x0333 | "Master DNode cannot be removed" | -2147482829 | +| TSDB_CODE_MND_NO_ENOUGH_DNODES | 0 | 0x0334 | "Out of DNodes" | -2147482828 | +| TSDB_CODE_MND_CLUSTER_CFG_INCONSISTENT | 0 | 0x0335 | "Cluster cfg inconsistent" | -2147482827 | +| TSDB_CODE_MND_INVALID_DNODE_CFG_OPTION | 0 | 0x0336 | "Invalid dnode cfg option" | -2147482826 | +| TSDB_CODE_MND_BALANCE_ENABLED | 0 | 0x0337 | "Balance already enabled" | -2147482825 | +| TSDB_CODE_MND_VGROUP_NOT_IN_DNODE | 0 | 0x0338 | "Vgroup not in dnode" | -2147482824 | +| TSDB_CODE_MND_VGROUP_ALREADY_IN_DNODE | 0 | 0x0339 | "Vgroup already in dnode" | -2147482823 | +| TSDB_CODE_MND_DNODE_NOT_FREE | 0 | 0x033A | "Dnode not avaliable" | -2147482822 | +| TSDB_CODE_MND_INVALID_CLUSTER_ID | 0 | 0x033B | "Cluster id not match" | -2147482821 | +| TSDB_CODE_MND_NOT_READY | 0 | 0x033C | "Cluster not ready" | -2147482820 | +| TSDB_CODE_MND_ACCT_ALREADY_EXIST | 0 | 0x0340 | "Account already exists" | -2147482816 | +| TSDB_CODE_MND_INVALID_ACCT | 0 | 0x0341 | "Invalid account" | -2147482815 | +| TSDB_CODE_MND_INVALID_ACCT_OPTION | 0 | 0x0342 | "Invalid account options" | -2147482814 | +| TSDB_CODE_MND_USER_ALREADY_EXIST | 0 | 0x0350 | "User already exists" | -2147482800 | +| TSDB_CODE_MND_INVALID_USER | 0 | 0x0351 | "Invalid user" | -2147482799 | +| TSDB_CODE_MND_INVALID_USER_FORMAT | 0 | 0x0352 | "Invalid user format" | -2147482798 | +| TSDB_CODE_MND_INVALID_PASS_FORMAT | 0 | 0x0353 | "Invalid password format" | -2147482797 | +| TSDB_CODE_MND_NO_USER_FROM_CONN | 0 | 0x0354 | "Can not get user from conn" | -2147482796 | +| TSDB_CODE_MND_TOO_MANY_USERS | 0 | 0x0355 | "Too many users" | -2147482795 | +| TSDB_CODE_MND_TABLE_ALREADY_EXIST | 0 | 0x0360 | "Table already exists" | -2147482784 | +| TSDB_CODE_MND_INVALID_TABLE_ID | 0 | 0x0361 | "Table name too long" | -2147482783 | +| TSDB_CODE_MND_INVALID_TABLE_NAME | 0 | 0x0362 | "Table does not exist" | -2147482782 | +| TSDB_CODE_MND_INVALID_TABLE_TYPE | 0 | 0x0363 | "Invalid table type in tsdb" | -2147482781 | +| TSDB_CODE_MND_TOO_MANY_TAGS | 0 | 0x0364 | "Too many tags" | -2147482780 | +| TSDB_CODE_MND_TOO_MANY_TIMESERIES | 0 | 0x0366 | "Too many time series" | -2147482778 | +| TSDB_CODE_MND_NOT_SUPER_TABLE | 0 | 0x0367 | "Not super table" | -2147482777 | +| TSDB_CODE_MND_COL_NAME_TOO_LONG | 0 | 0x0368 | "Tag name too long" | -2147482776 | +| TSDB_CODE_MND_TAG_ALREAY_EXIST | 0 | 0x0369 | "Tag already exists" | -2147482775 | +| TSDB_CODE_MND_TAG_NOT_EXIST | 0 | 0x036A | "Tag does not exist" | -2147482774 | +| TSDB_CODE_MND_FIELD_ALREAY_EXIST | 0 | 0x036B | "Field already exists" | -2147482773 | +| TSDB_CODE_MND_FIELD_NOT_EXIST | 0 | 0x036C | "Field does not exist" | -2147482772 | +| TSDB_CODE_MND_INVALID_STABLE_NAME | 0 | 0x036D | "Super table does not exist" | -2147482771 | +| TSDB_CODE_MND_DB_NOT_SELECTED | 0 | 0x0380 | "Database not specified or available" | -2147482752 | +| TSDB_CODE_MND_DB_ALREADY_EXIST | 0 | 0x0381 | "Database already exists" | -2147482751 | +| TSDB_CODE_MND_INVALID_DB_OPTION | 0 | 0x0382 | "Invalid database options" | -2147482750 | +| TSDB_CODE_MND_INVALID_DB | 0 | 0x0383 | "Invalid database name" | -2147482749 | +| TSDB_CODE_MND_MONITOR_DB_FORBIDDEN | 0 | 0x0384 | "Cannot delete monitor database" | -2147482748 | +| TSDB_CODE_MND_TOO_MANY_DATABASES | 0 | 0x0385 | "Too many databases for account" | -2147482747 | +| TSDB_CODE_MND_DB_IN_DROPPING | 0 | 0x0386 | "Database not available" | -2147482746 | +| TSDB_CODE_DND_MSG_NOT_PROCESSED | 0 | 0x0400 | "Message not processed" | -2147482624 | +| TSDB_CODE_DND_OUT_OF_MEMORY | 0 | 0x0401 | "Dnode out of memory" | -2147482623 | +| TSDB_CODE_DND_NO_WRITE_ACCESS | 0 | 0x0402 | "No permission for disk files in dnode" | -2147482622 | +| TSDB_CODE_DND_INVALID_MSG_LEN | 0 | 0x0403 | "Invalid message length" | -2147482621 | +| TSDB_CODE_VND_ACTION_IN_PROGRESS | 0 | 0x0500 | "Action in progress" | -2147482368 | +| TSDB_CODE_VND_MSG_NOT_PROCESSED | 0 | 0x0501 | "Message not processed" | -2147482367 | +| TSDB_CODE_VND_ACTION_NEED_REPROCESSED | 0 | 0x0502 | "Action need to be reprocessed" | -2147482366 | +| TSDB_CODE_VND_INVALID_VGROUP_ID | 0 | 0x0503 | "Invalid Vgroup ID" | -2147482365 | +| TSDB_CODE_VND_INIT_FAILED | 0 | 0x0504 | "Vnode initialization failed" | -2147482364 | +| TSDB_CODE_VND_NO_DISKSPACE | 0 | 0x0505 | "System out of disk space" | -2147482363 | +| TSDB_CODE_VND_NO_DISK_PERMISSIONS | 0 | 0x0506 | "No write permission for disk files" | -2147482362 | +| TSDB_CODE_VND_NO_SUCH_FILE_OR_DIR | 0 | 0x0507 | "Missing data file" | -2147482361 | +| TSDB_CODE_VND_OUT_OF_MEMORY | 0 | 0x0508 | "Out of memory" | -2147482360 | +| TSDB_CODE_VND_APP_ERROR | 0 | 0x0509 | "Unexpected generic error in vnode" | -2147482359 | +| TSDB_CODE_VND_INVALID_STATUS | 0 | 0x0510 | "Database not ready" | -2147482352 | +| TSDB_CODE_VND_NOT_SYNCED | 0 | 0x0511 | "Database suspended" | -2147482351 | +| TSDB_CODE_VND_NO_WRITE_AUTH | 0 | 0x0512 | "Write operation denied" | -2147482350 | +| TSDB_CODE_TDB_INVALID_TABLE_ID | 0 | 0x0600 | "Invalid table ID" | -2147482112 | +| TSDB_CODE_TDB_INVALID_TABLE_TYPE | 0 | 0x0601 | "Invalid table type" | -2147482111 | +| TSDB_CODE_TDB_IVD_TB_SCHEMA_VERSION | 0 | 0x0602 | "Invalid table schema version" | -2147482110 | +| TSDB_CODE_TDB_TABLE_ALREADY_EXIST | 0 | 0x0603 | "Table already exists" | -2147482109 | +| TSDB_CODE_TDB_INVALID_CONFIG | 0 | 0x0604 | "Invalid configuration" | -2147482108 | +| TSDB_CODE_TDB_INIT_FAILED | 0 | 0x0605 | "Tsdb init failed" | -2147482107 | +| TSDB_CODE_TDB_NO_DISKSPACE | 0 | 0x0606 | "No diskspace for tsdb" | -2147482106 | +| TSDB_CODE_TDB_NO_DISK_PERMISSIONS | 0 | 0x0607 | "No permission for disk files" | -2147482105 | +| TSDB_CODE_TDB_FILE_CORRUPTED | 0 | 0x0608 | "Data file(s) corrupted" | -2147482104 | +| TSDB_CODE_TDB_OUT_OF_MEMORY | 0 | 0x0609 | "Out of memory" | -2147482103 | +| TSDB_CODE_TDB_TAG_VER_OUT_OF_DATE | 0 | 0x060A | "Tag too old" | -2147482102 | +| TSDB_CODE_TDB_TIMESTAMP_OUT_OF_RANGE | 0 | 0x060B | "Timestamp data out of range" | -2147482101 | +| TSDB_CODE_TDB_SUBMIT_MSG_MSSED_UP | 0 | 0x060C | "Submit message is messed up" | -2147482100 | +| TSDB_CODE_TDB_INVALID_ACTION | 0 | 0x060D | "Invalid operation" | -2147482099 | +| TSDB_CODE_TDB_INVALID_CREATE_TB_MSG | 0 | 0x060E | "Invalid creation of table" | -2147482098 | +| TSDB_CODE_TDB_NO_TABLE_DATA_IN_MEM | 0 | 0x060F | "No table data in memory skiplist" | -2147482097 | +| TSDB_CODE_TDB_FILE_ALREADY_EXISTS | 0 | 0x0610 | "File already exists" | -2147482096 | +| TSDB_CODE_TDB_TABLE_RECONFIGURE | 0 | 0x0611 | "Need to reconfigure table" | -2147482095 | +| TSDB_CODE_TDB_IVD_CREATE_TABLE_INFO | 0 | 0x0612 | "Invalid information to create table" | -2147482094 | +| TSDB_CODE_QRY_INVALID_QHANDLE | 0 | 0x0700 | "Invalid handle" | -2147481856 | +| TSDB_CODE_QRY_INVALID_MSG | 0 | 0x0701 | "Invalid message" | -2147481855 | +| TSDB_CODE_QRY_NO_DISKSPACE | 0 | 0x0702 | "No diskspace for query" | -2147481854 | +| TSDB_CODE_QRY_OUT_OF_MEMORY | 0 | 0x0703 | "System out of memory" | -2147481853 | +| TSDB_CODE_QRY_APP_ERROR | 0 | 0x0704 | "Unexpected generic error in query" | -2147481852 | +| TSDB_CODE_QRY_DUP_JOIN_KEY | 0 | 0x0705 | "Duplicated join key" | -2147481851 | +| TSDB_CODE_QRY_EXCEED_TAGS_LIMIT | 0 | 0x0706 | "Tag conditon too many" | -2147481850 | +| TSDB_CODE_QRY_NOT_READY | 0 | 0x0707 | "Query not ready" | -2147481849 | +| TSDB_CODE_QRY_HAS_RSP | 0 | 0x0708 | "Query should response" | -2147481848 | +| TSDB_CODE_GRANT_EXPIRED | 0 | 0x0800 | "License expired" | -2147481600 | +| TSDB_CODE_GRANT_DNODE_LIMITED | 0 | 0x0801 | "DNode creation limited by licence" | -2147481599 | +| TSDB_CODE_GRANT_ACCT_LIMITED | 0 | 0x0802 | "Account creation limited by license" | -2147481598 | +| TSDB_CODE_GRANT_TIMESERIES_LIMITED | 0 | 0x0803 | "Table creation limited by license" | -2147481597 | +| TSDB_CODE_GRANT_DB_LIMITED | 0 | 0x0804 | "DB creation limited by license" | -2147481596 | +| TSDB_CODE_GRANT_USER_LIMITED | 0 | 0x0805 | "User creation limited by license" | -2147481595 | +| TSDB_CODE_GRANT_CONN_LIMITED | 0 | 0x0806 | "Conn creation limited by license" | -2147481594 | +| TSDB_CODE_GRANT_STREAM_LIMITED | 0 | 0x0807 | "Stream creation limited by license" | -2147481593 | +| TSDB_CODE_GRANT_SPEED_LIMITED | 0 | 0x0808 | "Write speed limited by license" | -2147481592 | +| TSDB_CODE_GRANT_STORAGE_LIMITED | 0 | 0x0809 | "Storage capacity limited by license" | -2147481591 | +| TSDB_CODE_GRANT_QUERYTIME_LIMITED | 0 | 0x080A | "Query time limited by license" | -2147481590 | +| TSDB_CODE_GRANT_CPU_LIMITED | 0 | 0x080B | "CPU cores limited by license" | -2147481589 | +| TSDB_CODE_SYN_INVALID_CONFIG | 0 | 0x0900 | "Invalid Sync Configuration" | -2147481344 | +| TSDB_CODE_SYN_NOT_ENABLED | 0 | 0x0901 | "Sync module not enabled" | -2147481343 | +| TSDB_CODE_WAL_APP_ERROR | 0 | 0x1000 | "Unexpected generic error in wal" | -2147479552 | diff --git a/docs-cn/14-reference/01-taos-sql/_category_.yml b/docs-cn/14-reference/01-taos-sql/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..62290997ece68ce1a61d391c3976e338033c0dd1 --- /dev/null +++ b/docs-cn/14-reference/01-taos-sql/_category_.yml @@ -0,0 +1 @@ +label: SQL 手册 diff --git a/docs-cn/14-reference/01-taos-sql/index.md b/docs-cn/14-reference/01-taos-sql/index.md new file mode 100644 index 0000000000000000000000000000000000000000..2c8d11288e55fd007b62b0a5fecc7dc7f2dc2737 --- /dev/null +++ b/docs-cn/14-reference/01-taos-sql/index.md @@ -0,0 +1,30 @@ +# TAOS SQL + +本文档说明 TAOS SQL 支持的语法规则、主要查询功能、支持的 SQL 查询函数，以及常用技巧等内容。阅读本文档需要读者具有基本的 SQL 语言的基础。 + +TAOS SQL 是用户对 TDengine 进行数据写入和查询的主要工具。TAOS SQL 为了便于用户快速上手，在一定程度上提供类似于标准 SQL 类似的风格和模式。严格意义上，TAOS SQL 并不是也不试图提供 SQL 标准的语法。此外，由于 TDengine 针对的时序性结构化数据不提供删除功能，因此在 TAO SQL 中不提供数据删除的相关功能。 + +TAOS SQL 不支持关键字的缩写，例如 DESCRIBE 不能缩写为 DESC。 + +本章节 SQL 语法遵循如下约定： + +- <\> 里的内容是用户需要输入的，但不要输入 <\> 本身 +- \[ \] 表示内容为可选项，但不能输入 [] 本身 +- | 表示多选一，选择其中一个即可，但不能输入 | 本身 +- … 表示前面的项可重复多个 + +为更好地说明 SQL 语法的规则及其特点，本文假设存在一个数据集。以智能电表(meters)为例，假设每个智能电表采集电流、电压、相位三个量。其建模如下： + +``` +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 | +``` + +数据集包含 4 个智能电表的数据，按照 TDengine 的建模规则，对应 4 个子表，其名称分别是 d1001, d1002, d1003, d1004。 \ No newline at end of file diff --git a/docs-cn/14-reference/02-restful-api/02-restful-api.mdx b/docs-cn/14-reference/02-restful-api/02-restful-api.mdx new file mode 100644 index 0000000000000000000000000000000000000000..6173c3215ac5a5dccc1caa206f89b77d101a6e70 --- /dev/null +++ b/docs-cn/14-reference/02-restful-api/02-restful-api.mdx @@ -0,0 +1,302 @@ +# RESTful API + +为支持各种不同类型平台的开发，TDengine 提供符合 REST 设计标准的 API，即 RESTful API。为最大程度降低学习成本，不同于其他数据库 RESTful API 的设计方法，TDengine 直接通过 HTTP POST 请求 BODY 中包含的 SQL 语句来操作数据库，仅需要一个 URL。RESTful 连接器的使用参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1965.html)。 + +注意：与原生连接器的一个区别是，RESTful 接口是无状态的，因此 `USE db_name` 指令没有效果，所有对表名、超级表名的引用都需要指定数据库名前缀。（从 2.2.0.0 版本开始，支持在 RESTful url 中指定 db_name，这时如果 SQL 语句中没有指定数据库名前缀的话，会使用 url 中指定的这个 db_name。从 2.4.0.0 版本开始，RESTful 默认由 taosAdapter 提供，要求必须在 url 中指定 db_name。） + +## 安装 + +RESTful 接口不依赖于任何 TDengine 的库，因此客户端不需要安装任何 TDengine 的库，只要客户端的开发语言支持 HTTP 协议即可。 + +## 验证 + +在已经安装 TDengine 服务器端的情况下，可以按照如下方式进行验证。 + +下面以 Ubuntu 环境中使用 curl 工具（确认已经安装）来验证 RESTful 接口的正常。 + +下面示例是列出所有的数据库，请把 h1.taosdata.com 和 6041（缺省值）替换为实际运行的 TDengine 服务 fqdn 和端口号： + +```html +curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'show databases;' +h1.taosdata.com:6041/rest/sql +``` + +返回值结果如下表示验证通过： + +```json +{ + "status": "succ", + "head": [ + "name", + "created_time", + "ntables", + "vgroups", + "replica", + "quorum", + "days", + "keep1,keep2,keep(D)", + "cache(MB)", + "blocks", + "minrows", + "maxrows", + "wallevel", + "fsync", + "comp", + "precision", + "status" + ], + "data": [ + [ + "log", + "2020-09-02 17:23:00.039", + 4, + 1, + 1, + 1, + 10, + "30,30,30", + 1, + 3, + 100, + 4096, + 1, + 3000, + 2, + "us", + "ready" + ] + ], + "rows": 1 +} +``` + +## RESTful 连接器的使用 + +### HTTP 请求格式 + +``` +http://
| 对比项 | +JDBC-JNI | +JDBC-RESTful | +
|---|---|---|
| 支持的操作系统 | +linux、windows | +全平台 | +
| 是否需要安装 client | +需要 | +不需要 | +
| server 升级后是否需要升级 client | +需要 | +不需要 | +
| 写入性能 | +JDBC-RESTful 是 JDBC-JNI 的 50%～90% | +|
| 查询性能 | +JDBC-RESTful 与 JDBC-JNI 没有差别 | +|
1：允许 | +| 缺省值 | 1 | + +### balance + +| 属性 | 说明 | +| -------- | ---------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 是否启动负载均衡 | +| 取值范围 | 0，1 | +| 缺省值 | 1 | + +### stream + +| 属性 | 说明 | +| -------- | ------------------------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 是否启用连续查询（流计算功能） | +| 取值范围 | 0：不允许
1：允许 | +| 缺省值 | 1 | + +### enableCoreFile + +| 属性 | 说明 | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 是否开启服务 crash 时生成 core 文件 | +| 取值范围 | 0：否，1：是 | +| 缺省值 | 1 | +| 补充说明 | 不同的启动方式，生成 core 文件的目录如下：1、systemctl start taosd 启动：生成的 core 在根目录下
2、手动启动，就在 taosd 执行目录下。 | + +## 区域相关 + +### timezone + +| 属性 | 说明 | +| -------- | ------------------------------ | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 时区 | +| 缺省值 | 从系统中动态获取当前的时区设置 | + +### locale + +| 属性 | 说明 | +| -------- | ----------------------------------------------------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 系统区位信息及编码格式 | +| 缺省值 | 系统中动态获取，如果自动获取失败，需要用户在配置文件设置或通过 API 设置 | + +### charset + +| 属性 | 说明 | +| -------- | ----------------------------------------------------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 字符集编码 | +| 缺省值 | 系统中动态获取，如果自动获取失败，需要用户在配置文件设置或通过 API 设置 | + +## 存储相关 + +### cache + +| 属性 | 说明 | +| -------- | ------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 内存块的大小 | +| 单位 | MB | +| 缺省值 | 16 | + +### blocks + +| 属性 | 说明 | +| -------- | ----------------------------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 每个 vnode（tsdb）中有多少 cache 大小的内存块。因此一个 vnode 的用的内存大小粗略为（cache \* blocks） | +| 缺省值 | 6 | + +### days + +| 属性 | 说明 | +| -------- | -------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 数据文件存储数据的时间跨度 | +| 单位 | 天 | +| 缺省值 | 10 | + +### keep + +| 属性 | 说明 | +| -------- | -------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 数据保留的天数 | +| 单位 | 天 | +| 缺省值 | 3650 | + +### minRows + +| 属性 | 说明 | +| -------- | ---------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 文件块中记录的最小条数 | +| 缺省值 | 100 | + +### maxRows + +| 属性 | 说明 | +| -------- | ---------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 文件块中记录的最大条数 | +| 缺省值 | 4096 | + +### walLevel + +| 属性 | 说明 | +| -------- | --------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | WAL 级别 | +| 取值范围 | 1：写 wal, 但不执行 fsync
2：写 wal, 而且执行 fsync | +| 缺省值 | 1 | + +### fsync + +| 属性 | 说明 | +| -------- | -------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 当 wal 设置为 2 时，执行 fsync 的周期 | +| 单位 | 毫秒 | +| 取值范围 | 最小为 0，表示每次写入，立即执行 fsync
最大为 180000（三分钟） | +| 缺省值 | 3000 | + +### update + +| 属性 | 说明 | +| -------- | ---------------------------------------------------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 允许更新已存在的数据行 | +| 取值范围 | 0：不允许更新
1：允许整行更新
2：允许部分列更新。（2.1.7.0 版本开始此参数支持设为 2，在此之前取值只能是 [0, 1]） | +| 缺省值 | 0 | +| 补充说明 | 2.0.8.0 版本之前，不支持此参数。 | + +### cacheLast + +| 属性 | 说明 | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 是否在内存中缓存子表的最近数据 | +| 取值范围 | 0：关闭
1：缓存子表最近一行数据
2：缓存子表每一列的最近的非 NULL 值
3：同时打开缓存最近行和列功能。（2.1.2.0 版本开始此参数支持 0 ～ 3 的取值范围，在此之前取值只能是 [0, 1]） | +| 缺省值 | 0 | +| 补充说明 | 2.1.2.0 版本之前、2.0.20.7 版本之前在 taos.cfg 文件中不支持此参数。 + + +### minimalLogDirGB + +| 属性 | 说明 | +| -------- | -------------------------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 当日志文件夹的磁盘大小小于该值时，停止写日志 | +| 单位 | GB | +| 缺省值 | 0.1 | + +### minimalTmpDirGB + +| 属性 | 说明 | +| -------- | ------------------------------------------------ | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 当日志文件夹的磁盘大小小于该值时，停止写临时文件 | +| 单位 | GB | +| 缺省值 | 0.1 | + +### minimalDataDirGB + +| 属性 | 说明 | +| -------- | ------------------------------------------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 当日志文件夹的磁盘大小小于该值时，停止写时序数据 | +| 单位 | GB | +| 缺省值 | 0.1 | + +## 集群相关 + +### replica + +| 属性 | 说明 | +| -------- | ------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 副本个数 | +| 取值范围 | 1-3 | +| 缺省值 | 1 | + +### quorum + +| 属性 | 说明 | +| -------- | -------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 多副本环境下指令执行的确认数要求 | +| 取值范围 | 1,2 | +| 缺省值 | 1 | + +### role + +| 属性 | 说明 | +| -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | dnode 的可选角色 | +| 取值范围 | 0：any（既可作为 mnode，也可分配 vnode）
1：mgmt（只能作为 mnode，不能分配 vnode）
2：dnode（不能作为 mnode，只能分配 vnode） | +| 缺省值 | 0 | + +## 时间相关 + +### rpcTimer + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | rpc 重试时长 | +| 单位 | 毫秒 | +| 取值范围 | 100-3000 | +| 缺省值 | 300 | + +### rpcMaxTime + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | rpc 等待应答最大时长 | +| 单位 | 秒 | +| 取值范围 | 100-7200 | +| 缺省值 | 600 | + +### statusInterval + +| 属性 | 说明 | +| -------- | --------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | dnode 向 mnode 报告状态间隔 | +| 单位 | 秒 | +| 取值范围 | 1-10 | +| 缺省值 | 1 | + +### shellActivityTimer + +| 属性 | 说明 | +| -------- | --------------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | shell 客户端向 mnode 发送心跳间隔 | +| 单位 | 秒 | +| 取值范围 | 1-120 | +| 缺省值 | 3 | + +### tableMetaKeepTimer + +| 属性 | 说明 | +| -------- | --------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 表的元数据 cache 时长 | +| 单位 | 秒 | +| 取值范围 | 1-8640000 | +| 缺省值 | 7200 | + +### minSlidingTime + +| 属性 | 说明 | +| -------- | ----------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 最小滑动窗口时长 | +| 单位 | 毫秒 | +| 取值范围 | 10-1000000 | +| 缺省值 | 10 | +| 补充说明 | 支持 us 补值后，这个值就是 1us 了。 | + +### minIntervalTime + +| 属性 | 说明 | +| -------- | -------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 时间窗口最小值 | +| 单位 | 毫秒 | +| 取值范围 | 1-1000000 | +| 缺省值 | 10 | + +### maxTmerCtrl + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 定时器个数 | +| 单位 | 个 | +| 取值范围 | 8-2048 | +| 缺省值 | 512 | + +### monitorInterval + +| 属性 | 说明 | +| -------- | -------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 监控数据库记录系统参数（CPU/内存）的时间间隔 | +| 单位 | 秒 | +| 取值范围 | 1-600 | +| 缺省值 | 30 | + +### offlineThreshold + +| 属性 | 说明 | +| -------- | ------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | dnode 离线阈值，超过该时间将导致 dnode 离线 | +| 单位 | 秒 | +| 取值范围 | 5-7200000 | +| 缺省值 | 86400\*10（10 天） | + +### maxStreamCompDelay + +| 属性 | 说明 | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 连续查询启动最大延迟 | +| 单位 | 毫秒 | +| 取值范围 | 10-1000000000 | +| 缺省值 | 20000 | +| 补充说明 | 为避免多个 stream 同时执行占用太多系统资源，程序中对 stream 的执行时间人为增加了一些随机的延时。
maxFirstStreamCompDelay 是 stream 第一次执行前最少要等待的时间。
streamCompDelayRatio 是延迟时间的计算系数，它乘以查询的 interval 后为延迟时间基准。
maxStreamCompDelay 是延迟时间基准的上限。
实际延迟时间为一个不超过延迟时间基准的随机值。
stream 某次计算失败后需要重试，retryStreamCompDelay 是重试的等待时间基准。
实际重试等待时间为不超过等待时间基准的随机值。 | + +### maxFirstStreamCompDelay + +| 属性 | 说明 | +| -------- | -------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 第一次连续查询启动最大延迟 | +| 单位 | 毫秒 | +| 取值范围 | 10-1000000000 | +| 缺省值 | 10000 | + +### retryStreamCompDelay + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 连续查询重试等待间隔 | +| 单位 | 毫秒 | +| 取值范围 | 10-1000000000 | +| 缺省值 | 10 | + +### streamCompDelayRatio + +| 属性 | 说明 | +| -------- | -------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 连续查询的延迟时间计算系数 | +| 取值范围 | 0.1-0.9 | +| 缺省值 | 0.1 | + +## 数量相关 + +### numOfThreadsPerCore + +| 属性 | 说明 | +| -------- | ----------------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 每个 CPU 核生成的队列消费者线程数量 | +| 缺省值 | 1.0 | + +### ratioOfQueryThreads + +| 属性 | 说明 | +| -------- | ------------------------------------------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 设置查询线程的最大数量 | +| 取值范围 | 0：表示只有 1 个查询线程
1：表示最大和 CPU 核数相等的查询线程
2：表示最大建立 2 倍 CPU 核数的查询线程。 | +| 缺省值 | 1 | +| 补充说明 | 该值可以为小数，即 0.5 表示最大建立 CPU 核数一半的查询线程。 | + +### numOfMnodes + +| 属性 | 说明 | +| -------- | ------------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 系统中管理节点个数 | +| 缺省值 | 3 | + +### maxVgroupsPerDb + +| 属性 | 说明 | +| -------- | ------------------------------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 每个 DB 中 能够使用的最大 vnode 个数 | +| 取值范围 | 0-8192 | +| 缺省值 | | + +### maxTablesPerVnode + +| 属性 | 说明 | +| -------- | --------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 每个 vnode 中能够创建的最大表个数 | +| 缺省值 | 1000000 | + +### maxNumOfOrderedRes + +| 属性 | 说明 | +| -------- | -------------------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 支持超级表时间排序允许的最多记录数限制 | +| 缺省值 | 10 万 | + +### maxShellConns + +| 属性 | 说明 | +| -------- | ----------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 一个 dnode 容许的连接数 | +| 取值范围 | 10-50000000 | +| 缺省值 | 5000 | + +### maxConnections + +| 属性 | 说明 | +| -------- | ------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 一个数据库连接所容许的 dnode 连接数 | +| 取值范围 | 1-100000 | +| 缺省值 | 5000 | +| 补充说明 | 实际测试下来，如果默认没有配，选 50 个 worker thread 会产生 Network unavailable | + +### mnodeEqualVnodeNum + +| 属性 | 说明 | +| -------- | ---------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 一个 mnode 等同于 vnode 消耗的个数 | +| 缺省值 | 4 | + +## 压缩相关 + +### comp + +| 属性 | 说明 | +| -------- | ----------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 文件压缩标志位 | +| 取值范围 | 0：关闭，1:一阶段压缩，2:两阶段压缩 | +| 缺省值 | 2 | + +### compressMsgSize + +| 属性 | 说明 | +| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 客户端与服务器之间进行消息通讯过程中，对通讯的消息进行压缩的阈值。如果要压缩消息，建议设置为 64330 字节，即大于 64330 字节的消息体才进行压缩。 | +| 单位 | bytes | +| 取值范围 | `0 `表示对所有的消息均进行压缩 >0: 超过该值的消息才进行压缩 -1: 不压缩 | +| 缺省值 | -1 | + +### compressColData + +| 属性 | 说明 | +| -------- | --------------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 客户端与服务器之间进行消息通讯过程中，对服务器端查询结果进行列压缩的阈值。 | +| 单位 | bytes | +| 取值范围 | 0: 对所有查询结果均进行压缩 >0: 查询结果中任意列大小超过该值的消息才进行压缩 -1: 不压缩 | +| 缺省值 | -1 | +| 补充说明 | 2.3.0.0 版本新增。 | + +### lossyColumns + +| 属性 | 说明 | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 适用范围 | 服务器端 | +| 含义 | 配置要进行有损压缩的浮点数据类型 | +| 取值范围 | 空字符串：关闭有损压缩
float：只对 float 类型进行有损压缩
double：只对 double 类型进行有损压缩
float \| double：float double 都进行有损压缩 | +| 缺省值 | 128 | +| 补充说明 | 有损压缩默认为关闭状态，只有配置后才生效 | + +### fPrecision + +| 属性 | 说明 | +| -------- | -------------------------------- | +| 适用范围 | 服务器端 | +| 含义 | 设置 float 类型浮点数压缩精度 | +| 取值范围 | 0.1 ~ 0.00000001 | +| 缺省值 | 0.00000001 | +| 补充说明 | 小于此值的浮点数尾数部分将被截取 | + +### dPrecision + +| 属性 | 说明 | +| -------- | -------------------------------- | +| 适用范围 | 服务器端 | +| 含义 | 设置 double 类型浮点数压缩精度 | +| 取值范围 | 0.1 ~ 0.0000000000000001 | +| 缺省值 | 0.0000000000000001 | +| 补充说明 | 小于此值的浮点数尾数部分将被截取 | + +## HTTP 相关 + +### http + +| 属性 | 说明 | +| -------- | --------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 服务器内部的 http 服务开关。 | +| 取值范围 | 0：关闭 http 服务， 1：激活 http 服务。 | +| 缺省值 | 1 | + +### httpEnableRecordSql + +| 属性 | 说明 | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 内部使用，记录通过 RESTFul 接口，产生的 SQL 调用。taosAdapter 配置或有不同，请参考相应[文档](https://www.taosdata.com/cn/documentation/tools/adapter)。 | +| 缺省值 | 0 | +| 补充说明 | 生成的文件（httpnote.0/httpnote.1），与服务端日志所在目录相同。 | + +### httpMaxThreads + +| 属性 | 说明 | +| -------- | --------------------------------------------------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | RESTFul 接口的线程数。taosAdapter 配置或有不同，请参考相应[文档](https://www.taosdata.com/cn/documentation/tools/adapter)。 | +| 缺省值 | 2 | + +### restfulRowLimit + +| 属性 | 说明 | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | RESTFul 接口单次返回的记录条数。taosAdapter 配置或有不同，请参考相应[文档](https://www.taosdata.com/cn/documentation/tools/adapter)。 | +| 缺省值 | 10240 | +| 补充说明 | 最大 10,000,000 | + +### httpDBNameMandatory + +| 属性 | 说明 | +| -------- | ---------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 是否在 URL 中输入 数据库名称 | +| 取值范围 | 0：不开启，1：开启 | +| 缺省值 | 0 | +| 补充说明 | 2.3 版本新增。 | + +## 日志相关 + +### numOfLogLines + +| 属性 | 说明 | +| -------- | ---------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 单个日志文件允许的最大行数。 | +| 缺省值 | 10,000,000 | + +### asyncLog + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 日志写入模式 | +| 取值范围 | 0：同步、1：异步 | +| 缺省值 | 1 | + +### logKeepDays + +| 属性 | 说明 | +| -------- | ----------------------------------------------------------------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 日志文件的最长保存时间 | +| 单位 | 天 | +| 缺省值 | 0 | +| 补充说明 | 大于 0 时，日志文件会被重命名为 taosdlog.xxx，其中 xxx 为日志文件最后修改的时间戳。 | + +### debugFlag + +| 属性 | 说明 | +| -------- | ------------------------------------------------------------------------------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 运行日志开关 | +| 取值范围 | 131（输出错误和警告日志），135（输出错误、警告和调试日志），143（输出错误、警告、调试和跟踪日志） | +| 缺省值 | 131 或 135（不同模块有不同的默认值） | + +### mDebugFlag + +| 属性 | 说明 | +| -------- | ------------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 管理模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | 135 | + +### dDebugFlag + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | dnode 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | 135 | + +### sDebugFlag + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | sync 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | 135 | + +### wDebugFlag + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | wal 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | 135 | + +### sdbDebugFlag + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | sdb 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | 135 | + +### rpcDebugFlag + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | rpc 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### tmrDebugFlag + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 定时器模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### cDebugFlag + +| 属性 | 说明 | +| -------- | --------------------- | +| 适用范围 | 仅客户端适用 | +| 含义 | client 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### jniDebugFlag + +| 属性 | 说明 | +| -------- | ------------------ | +| 适用范围 | 仅客户端适用 | +| 含义 | jni 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### odbcDebugFlag + +| 属性 | 说明 | +| -------- | ------------------- | +| 适用范围 | 仅客户端适用 | +| 含义 | odbc 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### uDebugFlag + +| 属性 | 说明 | +| -------- | ---------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 共用功能模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### httpDebugFlag + +| 属性 | 说明 | +| -------- | ------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | http 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### mqttDebugFlag + +| 属性 | 说明 | +| -------- | ------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | mqtt 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### monitorDebugFlag + +| 属性 | 说明 | +| -------- | ------------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 监控模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### qDebugFlag + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 查询模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### vDebugFlag + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | vnode 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### tsdbDebugFlag + +| 属性 | 说明 | +| -------- | ------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | TSDB 模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +### cqDebugFlag + +| 属性 | 说明 | +| -------- | ---------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 连续查询模块的日志开关 | +| 取值范围 | 同上 | +| 缺省值 | | + +## 内部配置 + +### secondEP + +| 属性 | 说明 | +| -------- | ---------------------------------------------------------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | taosd 启动时，如果 firstEp 连接不上，尝试连接集群中第二个 dnode 的 end point | +| 缺省值 | 无 | + +### scriptDir + +| 属性 | 说明 | +| -------- | ------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | | +| 缺省值 | | + +### balanceInterval + +| 属性 | 说明 | +| -------- | ------------------------------------------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | 管理节点在正常运行状态下，检查负载均衡的时间间隔 | +| 单位 | 秒 | +| 取值范围 | 1-30000 | +| 缺省值 | 300 | + +### minTablesPerVnode + +| 属性 | 说明 | +| -------- | --------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 每个 vnode 中必须创建的最小表个数 | +| 缺省值 | 1000 | + +### tableIncStepPerVnode + +| 属性 | 说明 | +| -------- | ----------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 每个 vnode 中超过最小表数后递增步长 | +| 缺省值 | 1000 | + +### mqttHostName + +| 属性 | 说明 | +| -------- | -------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | mqtt uri | +| 缺省值 | | +| 补充说明 | mqtt://username:password@hostname:1883/taos/ | + +### mqttPort + +| 属性 | 说明 | +| -------- | ---------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | mqtt client name | +| 缺省值 | | +| 补充说明 | 1883 | + +### mqttTopic + +| 属性 | 说明 | +| -------- | ------------ | +| 适用范围 | 仅服务端适用 | +| 含义 | | +| 缺省值 | | +| 补充说明 | /test | + +### mqtt + +| 属性 | 说明 | +| -------- | --------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 服务器内部的 mqtt 服务开关。 | +| 取值范围 | 0：关闭 mqtt 服务， 1：激活 mqtt 服务。 | +| 缺省值 | 0 | + +### telegrafUseFieldNum + +| 属性 | 说明 | +| -------- | ---- | +| 适用范围 | | +| 含义 | | +| 缺省值 | | + +### gitinfo + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | | +| 取值范围 | 1 | +| 缺省值 | | + +### gitinfoofInternal + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | | +| 取值范围 | 2 | +| 缺省值 | | + +### Buildinfo + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | | +| 取值范围 | 3 | +| 缺省值 | | + +### version + +| 属性 | 说明 | +| -------- | -------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | | +| 取值范围 | 4 | +| 缺省值 | | + +### numOfCommitThreads + +| 属性 | 说明 | +| -------- | ---------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 设置写入线程的最大数量 | +| 缺省值 | | + +## 仅客户端适用 + +### maxSQLLength + +| 属性 | 说明 | +| -------- | --------------------------- | +| 适用范围 | 仅客户端适用 | +| 含义 | 单条 SQL 语句允许的最长限制 | +| 单位 | bytes | +| 取值范围 | 65480-1048576 | +| 缺省值 | 1048576 | + +### tscEnableRecordSql + +| 属性 | 说明 | +| -------- | ----------------------------------------------------------------------------------- | +| 含义 | 是否记录客户端 sql 语句到文件 | +| 取值范围 | 0：否，1：是 | +| 缺省值 | 0 | +| 补充说明 | 生成的文件（tscnote-xxxx.0/tscnote-xxx.1，xxxx 是 pid），与客户端日志所在目录相同。 | + +### maxBinaryDisplayWidth + +| 属性 | 说明 | +| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 含义 | Taos shell 中 binary 和 nchar 字段的显示宽度上限，超过此限制的部分将被隐藏 | +| 取值范围 | 5 - | +| 缺省值 | 30 | +| 补充说明 | 实际上限按以下规则计算：如果字段值的长度大于 maxBinaryDisplayWidth，则显示上限为 **字段名长度** 和 **maxBinaryDisplayWidth** 的较大者。
否则，上限为 **字段名长度** 和 **字段值长度** 的较大者。
可在 shell 中通过命令 set max_binary_display_width nn 动态修改此选项 | + +### maxWildCardsLength + +| 属性 | 说明 | +| -------- | ------------------------------------------ | +| 含义 | 设定 LIKE 算子的通配符字符串允许的最大长度 | +| 单位 | bytes | +| 取值范围 | 0-16384 | +| 缺省值 | 100 | +| 补充说明 | 2.1.6.1 版本新增。 | + +### tsdbMetaCompactRatio + +| 属性 | 说明 | +| -------- | -------------------------------------------------------------- | +| 含义 | tsdb meta 文件中冗余数据超过多少阈值，开启 meta 文件的压缩功能 | +| 取值范围 | 0：不开启，[1-100]：冗余数据比例 | +| 缺省值 | 0 | + +### clientMerge + +| 属性 | 说明 | +| -------- | ---------------------------- | +| 含义 | 是否允许客户端对写入数据去重 | +| 取值范围 | 0：不开启，1：开启 | +| 缺省值 | 0 | +| 补充说明 | 2.3 版本新增。 | + +### maxRegexStringLen + +| 属性 | 说明 | +| -------- | -------------------------- | +| 含义 | 正则表达式最大允许长度 | +| 取值范围 | 默认值 128，最大长度 16384 | +| 缺省值 | 128 | +| 补充说明 | 2.3 版本新增。 | + +## 其他 + +### queryBufferSize + +| 属性 | 说明 | +| -------- | ------------------------------------------------------------------------------------------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 为所有并发查询占用保留的内存大小。 | +| 单位 | MB | +| 缺省值 | | +| 补充说明 | 计算规则可以根据实际应用可能的最大并发数和表的数字相乘，再乘 170 。
（2.0.15 以前的版本中，此参数的单位是字节） | + +### ratioOfQueryCores + +| 属性 | 说明 | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | +| 适用范围 | 仅服务端适用 | +| 含义 | 设置查询线程的最大数量。 | +| 缺省值 | | +| 补充说明 | 最小值 0 表示只有 1 个查询线程
最大值 2 表示最大建立 2 倍 CPU 核数的查询线程。
默认为 1，表示最大和 CPU 核数相等的查询线程。
该值可以为小数，即 0.5 表示最大建立 CPU 核数一半的查询线程。 | | + +### rpcForceTcp + +| 属性 | 说明 | +| -------- | --------------------------------------------------- | +| 适用范围 | 服务端和客户端均适用 | +| 含义 | 强制使用 TCP 传输 | +| 取值范围 | 0: 不开启 1: 开启 | +| 缺省值 | 0 | +| 补充说明 | 在网络比较差的环境中，建议开启。
2.0 版本新增。 | + +### maxNumOfDistinctRes + +| 属性 | 说明 | +| -------- | -------------------------------- | +| 适用范围 | 仅服务端适用 | +| 含义 | 允许返回的 distinct 结果最大行数 | +| 取值范围 | 默认值为 10 万，最大值 1 亿 | +| 缺省值 | 10 万 | +| 补充说明 | 2.3 版本新增。 | + diff --git a/docs-cn/14-reference/08-server-config/_category_.yml b/docs-cn/14-reference/08-server-config/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..e05fbeb578ceb525ae80f3d50c3e018df13bfa56 --- /dev/null +++ b/docs-cn/14-reference/08-server-config/_category_.yml @@ -0,0 +1 @@ +label: 服务端配置 \ No newline at end of file diff --git a/docs-cn/14-reference/09-client-config/09-client-config.md b/docs-cn/14-reference/09-client-config/09-client-config.md new file mode 100644 index 0000000000000000000000000000000000000000..15ca79b029d8194c5af0c43ab579aac8727b06d4 --- /dev/null +++ b/docs-cn/14-reference/09-client-config/09-client-config.md @@ -0,0 +1,105 @@ +# 客户端及应用驱动配置 + +TDengine 系统的前台交互客户端应用程序为 taos，以及应用驱动，它与 taosd 共享同一个配置文件 taos.cfg。运行 taos 时，使用参数-c 指定配置文件目录，如 taos -c /home/cfg，表示使用/home/cfg/目录下的 taos.cfg 配置文件中的参数，缺省目录是/etc/taos。更多 taos 的使用方法请见帮助信息 `taos --help`。本节主要说明 taos 客户端应用在配置文件 taos.cfg 文件中使用到的参数。 + +**2.0.10.0 之后版本支持命令行以下参数显示当前客户端参数的配置** + +```bash +taos -C 或 taos --dump-config +``` + +客户端及应用驱动配置参数列表及解释 + +- firstEp: taos 启动时，主动连接的集群中第一个 taosd 实例的 end point, 缺省值为 localhost:6030。 + +- secondEp: taos 启动时，如果 firstEp 连不上，将尝试连接 secondEp。 + +- locale：系统区位信息及编码格式。 + + 默认值：系统中动态获取，如果自动获取失败，需要用户在配置文件设置或通过 API 设置。 + + TDengine 为存储中文、日文、韩文等非 ASCII 编码的宽字符，提供一种专门的字段类型 nchar。写入 nchar 字段的数据将统一采用 UCS4-LE 格式进行编码并发送到服务器。需要注意的是，编码正确性是客户端来保证。因此，如果用户想要正常使用 nchar 字段来存储诸如中文、日文、韩文等非 ASCII 字符，需要正确设置客户端的编码格式。 + + 客户端的输入的字符均采用操作系统当前默认的编码格式，在 Linux 系统上多为 UTF-8，部分中文系统编码则可能是 GB18030 或 GBK 等。在 docker 环境中默认的编码是 POSIX。在中文版 Windows 系统中，编码则是 CP936。客户端需要确保正确设置自己所使用的字符集，即客户端运行的操作系统当前编码字符集，才能保证 nchar 中的数据正确转换为 UCS4-LE 编码格式。 + + 在 Linux 中 locale 的命名规则为: <语言>\_<地区>.<字符集编码> 如：zh_CN.UTF-8，zh 代表中文，CN 代表大陆地区，UTF-8 表示字符集。字符集编码为客户端正确解析本地字符串提供编码转换的说明。Linux 系统与 Mac OSX 系统可以通过设置 locale 来确定系统的字符编码，由于 Windows 使用的 locale 中不是 POSIX 标准的 locale 格式，因此在 Windows 下需要采用另一个配置参数 charset 来指定字符编码。在 Linux 系统中也可以使用 charset 来指定字符编码。 + +- charset：字符集编码。 + + 默认值：系统中动态获取，如果自动获取失败，需要用户在配置文件设置或通过 API 设置。 + + 如果配置文件中不设置 charset，在 Linux 系统中，taos 在启动时候，自动读取系统当前的 locale 信息，并从 locale 信息中解析提取 charset 编码格式。如果自动读取 locale 信息失败，则尝试读取 charset 配置，如果读取 charset 配置也失败，则中断启动过程。 + + 在 Linux 系统中，locale 信息包含了字符编码信息，因此正确设置了 Linux 系统 locale 以后可以不用再单独设置 charset。例如： + + ``` + locale zh_CN.UTF-8 + ``` + + 在 Windows 系统中，无法从 locale 获取系统当前编码。如果无法从配置文件中读取字符串编码信息，taos 默认设置为字符编码为 CP936。其等效在配置文件中添加如下配置： + + ``` + charset CP936 + ``` + + 如果需要调整字符编码，请查阅当前操作系统使用的编码，并在配置文件中正确设置。 + + 在 Linux 系统中，如果用户同时设置了 locale 和字符集编码 charset，并且 locale 和 charset 的不一致，后设置的值将覆盖前面设置的值。 + + ``` + locale zh_CN.UTF-8 + charset GBK + ``` + + 则 charset 的有效值是 GBK。 + + ``` + charset GBK + locale zh_CN.UTF-8 + ``` + + charset 的有效值是 UTF-8。 + + 日志的配置参数，与 server 的配置参数完全一样。 + +- timezone + + 默认值：动态获取当前客户端运行系统所在的时区。 + + 为应对多时区的数据写入和查询问题，TDengine 采用 Unix 时间戳(Unix Timestamp)来记录和存储时间戳。Unix 时间戳的特点决定了任一时刻不论在任何时区，产生的时间戳均一致。需要注意的是，Unix 时间戳是在客户端完成转换和记录。为了确保客户端其他形式的时间转换为正确的 Unix 时间戳，需要设置正确的时区。 + + 在 Linux 系统中，客户端会自动读取系统设置的时区信息。用户也可以采用多种方式在配置文件设置时区。例如： + + ``` + timezone UTC-8 + timezone GMT-8 + timezone Asia/Shanghai + ``` + + 均是合法的设置东八区时区的格式。但需注意，Windows 下并不支持 `timezone Asia/Shanghai` 这样的写法，而必须写成 `timezone UTC-8`。 + + 时区的设置对于查询和写入 SQL 语句中非 Unix 时间戳的内容（时间戳字符串、关键词 now 的解析）产生影响。例如： + + ```sql + SELECT count(*) FROM table_name WHERE TS<'2019-04-11 12:01:08'; + ``` + + 在东八区，SQL 语句等效于 + + ```sql + SELECT count(*) FROM table_name WHERE TS<1554955268000; + ``` + + 在 UTC 时区，SQL 语句等效于 + + ```sql + SELECT count(*) FROM table_name WHERE TS<1554984068000; + ``` + + 为了避免使用字符串时间格式带来的不确定性，也可以直接使用 Unix 时间戳。此外，还可以在 SQL 语句中使用带有时区的时间戳字符串，例如：RFC3339 格式的时间戳字符串，2013-04-12T15:52:01.123+08:00 或者 ISO-8601 格式时间戳字符串 2013-04-12T15:52:01.123+0800。上述两个字符串转化为 Unix 时间戳不受系统所在时区的影响。 + + 启动 taos 时，也可以从命令行指定一个 taosd 实例的 end point，否则就从 taos.cfg 读取。 + +- maxBinaryDisplayWidth + + Shell 中 binary 和 nchar 字段的显示宽度上限，超过此限制的部分将被隐藏。默认值：30。可在 taos shell 中通过命令 set max_binary_display_width nn 动态修改此选项。 diff --git a/docs-cn/14-reference/09-client-config/_category_.yml b/docs-cn/14-reference/09-client-config/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..ad6e70b96dd031cc3d2607565f91d554e19addeb --- /dev/null +++ b/docs-cn/14-reference/09-client-config/_category_.yml @@ -0,0 +1 @@ +label: 客户端配置 diff --git a/docs-cn/14-reference/12-direcotry.md b/docs-cn/14-reference/12-direcotry.md new file mode 100644 index 0000000000000000000000000000000000000000..c2746de1c1dd98f9ffa715680d4a1048cd3e8c02 --- /dev/null +++ b/docs-cn/14-reference/12-direcotry.md @@ -0,0 +1,34 @@ +# 文件目录结构 + +安装 TDengine 后，默认会在操作系统中生成下列目录或文件： + +| 目录/文件 | 说明 | +| ------------------------- | -------------------------------------------------------------------- | +| /usr/local/taos/bin | TDengine 可执行文件目录。其中的执行文件都会软链接到/usr/bin 目录下。 | +| /usr/local/taos/connector | TDengine 各种连接器目录。 | +| /usr/local/taos/driver | TDengine 动态链接库目录。会软链接到/usr/lib 目录下。 | +| /usr/local/taos/examples | TDengine 各种语言应用示例目录。 | +| /usr/local/taos/include | TDengine 对外提供的 C 语言接口的头文件。 | +| /etc/taos/taos.cfg | TDengine 默认[配置文件] | +| /var/lib/taos | TDengine 默认数据文件目录。可通过[配置文件]修改位置。 | +| /var/log/taos | TDengine 默认日志文件目录。可通过[配置文件]修改位置。 | + +## 可执行文件 + +TDengine 的所有可执行文件默认存放在 _/usr/local/taos/bin_ 目录下。其中包括： + +- _taosd_：TDengine 服务端可执行文件 +- _taos_：TDengine Shell 可执行文件 +- _taosdump_：数据导入导出工具 +- _taosBenchmark_：TDengine 测试工具 +- remove.sh：卸载 TDengine 的脚本，请谨慎执行，链接到/usr/bin 目录下的**rmtaos**命令。会删除 TDengine 的安装目录/usr/local/taos，但会保留/etc/taos、/var/lib/taos、/var/log/taos。 + +:::note +2.4.0.0 版本之后的 taosBenchmark 和 taosdump 需要安装独立安装包 taosTools。 + +::: + +:::tip +您可以通过修改系统配置文件 taos.cfg 来配置不同的数据目录和日志目录。 + +::: diff --git a/docs-cn/14-reference/13-schemaless/13-schemaless.md b/docs-cn/14-reference/13-schemaless/13-schemaless.md new file mode 100644 index 0000000000000000000000000000000000000000..1c5fbea726eb5153d4db0ef6d42ef53b478232f5 --- /dev/null +++ b/docs-cn/14-reference/13-schemaless/13-schemaless.md @@ -0,0 +1,164 @@ +# Schemaless 写入 + +## 前言 + +在物联网应用中，常会采集比较多的数据项，用于实现智能控制、业务分析、设备监控等。由于应用逻辑的版本升级，或者设备自身的硬件调整等原因，数据采集项就有可能比较频繁地出现变动。为了在这种情况下方便地完成数据记录工作，TDengine +从 2.2.0.0 版本开始，提供调用 Schemaless 写入方式，可以免于预先创建超级表/子表的步骤，随着数据写入接口能够自动创建与数据对应的存储结构。并且在必要时，Schemaless +将自动增加必要的数据列，保证用户写入的数据可以被正确存储。 + +无模式写入方式建立的超级表及其对应的子表与通过 SQL 直接建立的超级表和子表完全没有区别，你也可以通过，SQL 语句直接向其中写入数据。需要注意的是，通过无模式写入方式建立的表，其表名是基于标签值按照固定的映射规则生成，所以无法明确地进行表意，缺乏可读性。 + +## 无模式写入行协议 + +TDengine 的无模式写入的行协议兼容 InfluxDB 的 行协议（Line Protocol）、OpenTSDB 的 telnet 行协议、OpenTSDB 的 JSON 格式协议。但是使用这三种协议的时候，需要在 API 中指定输入内容使用解析协议的标准。 + +对于 InfluxDB、OpenTSDB 的标准写入协议请参考各自的文档。下面首先以 InfluxDB 的行协议为基础，介绍 TDengine 扩展的协议内容，允许用户采用更加精细的方式控制（超级表）模式。 + +Schemaless 采用一个字符串来表达一个数据行（可以向写入 API 中一次传入多行字符串来实现多个数据行的批量写入），其格式约定如下： + +```json +measurement,tag_set field_set timestamp +``` + +其中: + +- measurement 将作为数据表名。它与 tag_set 之间使用一个英文逗号来分隔。 +- tag_set 将作为标签数据，其格式形如 `
（注：测试数据源自 单节点 Intel(R) Core(TM) i7-10700 CPU@2.90GHz 16 核 64G 硬件设备，channel 和 batchSize 分别为 8 和 1000，每条记录包含 10 个 tag) + +### 2、手动迁移数据 + +如果你需要使用多值模型进行数据写入，就需要自行开发一个将数据从 OpenTSDB 导出的工具，然后确认哪些时间线能够合并导入到同一个时间线，再将可以同时导入的时间通过 SQL 语句的写入到数据库中。 + +手动迁移数据需要注意以下两个问题： + +1）在磁盘中存储导出数据时，磁盘需要有足够的存储空间以便能够充分容纳导出的数据文件。为了避免全量数据导出后导致磁盘文件存储紧张，可以采用部分导入的模式，对于归属于同一个超级表的时间线优先导出，然后将导出部分的数据文件导入到 TDengine 系统中。 + +2）在系统全负载运行下，如果有足够的剩余计算和 IO 资源，可以建立多线程的导入机制，最大限度地提升数据迁移的效率。考虑到数据解析对于 CPU 带来的巨大负载，需要控制最大的并行任务数量，以避免因导入历史数据而触发的系统整体过载。 + +由于 TDegnine 本身操作简易性，所以不需要在整个过程中进行索引维护、数据格式的变化处理等工作，整个过程只需要顺序执行即可。 + +当历史数据完全导入到 TDengine 以后，此时两个系统处于同时运行的状态，之后便可以将查询请求切换到 TDengine 上，从而实现无缝的应用切换。 + +## 附录 1: OpenTSDB 查询函数对应表 + +**Avg** + +等效函数：avg + +示例： + +SELECT avg(val) FROM (SELECT first(val) FROM super_table WHERE ts >= startTime and ts <= endTime INTERVAL(20s) Fill(linear)) INTERVAL(20s) + +备注： + +1. Interval 内的数值与外层查询的 interval 数值需要相同。 +2. 在 TDengine 中插值处理需要使用子查询来协助完成，如上所示，在内层查询中指明插值类型即可，由于 OpenTSDB 中数值的插值使用了线性插值，因此在插值子句中使用 fill(linear) 来声明插值类型。以下有相同插值计算需求的函数，均采用该方法处理。 +3. Interval 中参数 20s 表示将内层查询按照 20 秒一个时间窗口生成结果。在真实的查询中，需要调整为不同的记录之间的时间间隔。这样可确保等效于原始数据生成了插值结果。 +4. 由于 OpenTSDB 特殊的插值策略和机制，聚合查询（Aggregate）中先插值再计算的方式导致其计算结果与 TDengine 不可能完全一致。但是在降采样（Downsample）的情况下，TDengine 和 OpenTSDB 能够获得一致的结果（由于 OpenTSDB 在聚合查询和降采样查询中采用了完全不同的插值策略）。 + +**Count** + +等效函数：count + +示例： + +select count(\*) from super_table_name; + +**Dev** + +等效函数：stddev + +示例： + +Select stddev(val) from table_name + +**Estimated percentiles** + +等效函数：apercentile + +示例： + +Select apercentile(col1, 50, “t-digest”) from table_name + +备注： + +1. 近似查询处理过程中，OpenTSDB 默认采用 t-digest 算法，所以为了获得相同的计算结果，需要在 apercentile 函数中指明使用的算法。TDengine 能够支持两种不同的近似处理算法，分别通过“default”和“t-digest”来声明。 + +**First** + +等效函数：first + +示例： + +Select first(col1) from table_name + +**Last** + +等效函数：last + +示例： + +Select last(col1) from table_name + +**Max** + +等效函数：max + +示例： + +Select max(value) from (select first(val) value from table_name interval(10s) fill(linear)) interval(10s) + +备注：Max 函数需要插值，原因见上。 + +**Min** + +等效函数：min + +示例： + +Select min(value) from (select first(val) value from table_name interval(10s) fill(linear)) interval(10s); + +**MinMax** + +等效函数：max + +Select max(val) from table_name + +备注：该函数无插值需求，因此可用直接计算。 + +**MimMin** + +等效函数：min + +Select min(val) from table_name + +备注：该函数无插值需求，因此可用直接计算。 + +**Percentile** + +等效函数：percentile + +备注： + +**Sum** + +等效函数：sum + +Select max(value) from (select first(val) value from table_name interval(10s) fill(linear)) interval(10s) + +备注：该函数无插值需求，因此可用直接计算。 + +**Zimsum** + +等效函数：sum + +Select sum(val) from table_name + +备注：该函数无插值需求，因此可用直接计算。 + +完整示例： + +```json +// OpenTSDB 查询 JSON +query = { +“start”:1510560000, +“end”: 1515000009, +“queries”:[{ +“aggregator”: “count”, +“metric”:”cpu.usage_user”, +}] +} + +//等效查询 SQL: +SELECT count(*) +FROM `cpu.usage_user` +WHERE ts>=1510560000 AND ts<=1515000009 +``` + +## 附录 2: 资源估算方法 + +### 数据生成环境 + +我们仍然使用第 4 章中的假设环境，3 个测量值。分别是：温度和湿度的数据写入的速率是每 5 秒一条记录，时间线 10 万个。空气质量的写入速率是 10 秒一条记录，时间线 1 万个，查询的请求频率 500 QPS。 + +### 存储资源估算 + +假设产生数据并需要存储的传感器设备数量为 `n`，数据生成的频率为`t`条/秒，每条记录的长度为 `L` bytes，则每天产生的数据规模为 `n×t×L` bytes。假设压缩比为 C，则每日产生数据规模为 `(n×t×L)/C` bytes。存储资源预估为能够容纳 1.5 年的数据规模，生产环境下 TDengine 的压缩比 C 一般在 5 ~ 7 之间，同时为最后结果增加 20% 的冗余，可计算得到需要存储资源： + +```matlab +(n×t×L)×(365×1.5)×(1+20%)/C +``` + +结合以上的计算公式，将参数带入计算公式，在不考虑标签信息的情况下，每年产生的原始数据规模是 11.8TB。需要注意的是，由于标签信息在 TDengine 中关联到每个时间线，并不是每条记录。所以需要记录的数据量规模相对于产生的数据有一定的降低，而这部分标签数据整体上可以忽略不记。假设压缩比为 5，则保留的数据规模最终为 2.56 TB。 + +### 存储设备选型考虑 + +硬盘应该选用具有较好随机读性能的硬盘设备，如果能够有 SSD，尽可能考虑使用 SSD。较好的随机读性能的磁盘对于提升系统查询性能具有极大的帮助，能够整体上提升系统的查询响应性能。为了获得较好的查询性能，硬盘设备的单线程随机读 IOPS 的性能指标不应该低于 1000，能够达到 5000 IOPS 以上为佳。为了获得当前的设备随机读取的 IO 性能的评估，建议使用 fio 软件对其进行运行性能评估（具体的使用方式请参阅附录 1），确认其是否能够满足大文件随机读性能要求。 + +硬盘写性能对于 TDengine 的影响不大。TDengine 写入过程采用了追加写的模式，所以只要有较好的顺序写性能即可，一般意义上的 SAS 硬盘和 SSD 均能够很好地满足 TDengine 对于磁盘写入性能的要求。 + +### 计算资源估算 + +由于物联网数据的特殊性，数据产生的频率固定以后，TDengine 写入的过程对于（计算和存储）资源消耗都保持一个相对固定的量。《[TDengine 的运营与维护](https://www.taosdata.com/cn/documentation/administrator)》上的描述，该系统中每秒 22000 个写入，消耗 CPU 不到 1 个核。 + +在针对查询所需要消耗的 CPU 资源的估算上，假设应用要求数据库提供的 QPS 为 10000，每次查询消耗的 CPU 时间约 1 ms，那么每个核每秒提供的查询为 1000 QPS，满足 10000 QPS 的查询请求，至少需要 10 个核。为了让系统整体上 CPU 负载小于 50%，整个集群需要 10 个核的两倍，即 20 个核。 + +### 内存资源估算 + +数据库默认为每个 Vnode 分配内存 16MB\*3 缓冲区，集群系统包括 22 个 CPU 核，则默认会建立 22 个虚拟节点 Vnode，每个 Vnode 包含 1000 张表，则可以容纳所有的表。则约 1 个半小时写满一个 block，从而触发落盘，可以不做调整。22 个 Vnode 共计需要内存缓存约 1GB。考虑到查询所需要的内存，假设每次查询的内存开销约 50MB，则 500 个查询并发需要的内存约 25GB。 + +综上所述，可使用单台 16 核 32GB 的机器，或者使用 2 台 8 核 16GB 机器构成的集群。 + +## 附录 3: 集群部署及启动 + +TDengine 提供了丰富的帮助文档说明集群安装、部署的诸多方面的内容，这里提供响应的文档索引，供你参考。 + +### 集群部署 + +首先是安装 TDengine，从官网上下载 TDengine 最新稳定版，解压缩后运行 install.sh 进行安装。各种安装包的使用帮助请参见博客[《TDengine 多种安装包的安装和卸载》](https://www.taosdata.com/blog/2019/08/09/566.html)。 + +注意安装完成以后，不要立即启动 taosd 服务，在正确配置完成参数以后才启动 taosd 服务。 + +### 设置运行参数并启动服务 + +为确保系统能够正常获取运行的必要信息。请在服务端正确设置以下关键参数： + +FQDN、firstEp、secondEP、dataDir、logDir、tmpDir、serverPort。各参数的具体含义及设置的要求，可参见文档《[TDengine 集群安装、管理](https://www.taosdata.com/cn/documentation/cluster)》 + +按照相同的步骤，在需要运行的节点上设置参数，并启动 taosd 服务，然后添加 Dnode 到集群中。 + +最后启动 taos，执行命令 show dnodes，如果能看到所有的加入集群的节点，那么集群顺利搭建完成。具体的操作流程及注意事项，请参阅文档《[TDengine 集群安装、管理](https://www.taosdata.com/cn/documentation/cluster)》 + +## 附录 4: 超级表名称 + +由于 OpenTSDB 的 metric 名称中带有点号（“.“），例如“cpu.usage_user”这种名称的 metric。但是点号在 TDengine 中具有特殊含义，是用来分隔数据库和表名称的分隔符。TDengine 也提供转义符，以允许用户在（超级）表名称中使用关键词或特殊分隔符（如：点号）。为了使用特殊字符，需要采用转义字符将表的名称括起来，例如：`cpu.usage_user`这样就是合法的（超级）表名称。 + +## 附录 5：参考文章 + +1. [使用 TDengine + collectd/StatsD + Grafana 快速搭建 IT 运维监控系统](https://www.taosdata.com/cn/documentation20/devops/collectd) +2. [通过 collectd 将采集数据直接写入 TDengine](https://www.taosdata.com/cn/documentation20/insert#collectd) diff --git a/docs-cn/15-application/_category_.yml b/docs-cn/15-application/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..141c9269b50a2155391543ecea1dfe5c918e113c --- /dev/null +++ b/docs-cn/15-application/_category_.yml @@ -0,0 +1,4 @@ +label: 应用实践 +link: + slug: /application/ + type: generated-index diff --git a/docs-cn/16-iot-big-data/_category_.yml b/docs-cn/16-iot-big-data/_category_.yml new file mode 100644 index 0000000000000000000000000000000000000000..0c389d56780a0eab585f4f0cee0311852037bc1f --- /dev/null +++ b/docs-cn/16-iot-big-data/_category_.yml @@ -0,0 +1 @@ +label: 物联网大数据 \ No newline at end of file diff --git a/docs-cn/16-iot-big-data/index.md b/docs-cn/16-iot-big-data/index.md new file mode 100644 index 0000000000000000000000000000000000000000..5687dd3fda161c426108dba298b73fc4db949c28 --- /dev/null +++ b/docs-cn/16-iot-big-data/index.md @@ -0,0 +1,7 @@ +# 物联网大数据 + + +- [物联网、工业互联网大数据的特点](https://www.taosdata.com/blog/2019/07/09/105.html) +- [物联网大数据平台应具备的功能和特点](https://www.taosdata.com/blog/2019/07/29/542.html) +- [通用大数据架构为什么不适合处理物联网数据？](https://www.taosdata.com/blog/2019/07/09/107.html) +- [物联网、车联网、工业互联网大数据平台，为什么推荐使用 TDengine？](https://www.taosdata.com/blog/2019/07/09/109.html) diff --git a/docs-cn/17-train-fqa/01-faq.md b/docs-cn/17-train-fqa/01-faq.md new file mode 100644 index 0000000000000000000000000000000000000000..9f3baccf7f765325129ac72bd4e62ede0c7e8e87 --- /dev/null +++ b/docs-cn/17-train-fqa/01-faq.md @@ -0,0 +1,222 @@ +# 常见问题及反馈 + +## 问题反馈 + +如果 FAQ 中的信息不能够帮到您，需要 TDengine 技术团队的技术支持与协助，请将以下两个目录中内容打包： + +1. /var/log/taos （如果没有修改过默认路径） +2. /etc/taos + +附上必要的问题描述，包括使用的 TDengine 版本信息、平台环境信息、发生该问题的执行操作、出现问题的表征及大概的时间，在 [GitHub](https://github.com/taosdata/TDengine) 提交 issue。 + +为了保证有足够的 debug 信息，如果问题能够重复，请修改/etc/taos/taos.cfg 文件，最后面添加一行“debugFlag 135"(不带引号本身），然后重启 taosd, 重复问题，然后再递交。也可以通过如下 SQL 语句，临时设置 taosd 的日志级别。 + +``` + alter dnode
diff --git a/docs-cn/17-train-fqa/03-docker.md b/docs-cn/17-train-fqa/03-docker.md
new file mode 100644
index 0000000000000000000000000000000000000000..54b94c9abae50d5a6581ed4bce321bc5d5e761f3
--- /dev/null
+++ b/docs-cn/17-train-fqa/03-docker.md
@@ -0,0 +1,328 @@
+# 通过 Docker 快速体验 TDengine
+
+虽然并不推荐在生产环境中通过 Docker 来部署 TDengine 服务，但 Docker 工具能够很好地屏蔽底层操作系统的环境差异，很适合在开发测试或初次体验时用于安装运行 TDengine 的工具集。特别是，借助 Docker，能够比较方便地在 macOS 和 Windows 系统上尝试 TDengine，而无需安装虚拟机或额外租用 Linux 服务器。另外，从 2.0.14.0 版本开始，TDengine 提供的镜像已经可以同时支持 X86-64、X86、arm64、arm32 平台，像 NAS、树莓派、嵌入式开发板之类可以运行 docker 的非主流计算机也可以基于本文档轻松体验 TDengine。
+
+下文通过 Step by Step 风格的介绍，讲解如何通过 Docker 快速建立 TDengine 的单节点运行环境，以支持开发和测试。
+
+## 下载 Docker
+
+Docker 工具自身的下载请参考 [Docker 官网文档](https://docs.docker.com/get-docker/)。
+
+安装完毕后可以在命令行终端查看 Docker 版本。如果版本号正常输出，则说明 Docker 环境已经安装成功。
+
+```bash
+$ docker -v
+Docker version 20.10.3, build 48d30b5
+```
+
+## 使用 Docker 在容器中运行 TDengine
+
+### 在 Docker 容器中运行 TDengine server
+
+```bash
+$ docker run -d -p 6030-6049:6030-6049 -p 6030-6049:6030-6049/udp tdengine/tdengine
+526aa188da767ae94b244226a2b2eec2b5f17dd8eff592893d9ec0cd0f3a1ccd
+```
+
+这条命令，启动一个运行了 TDengine server 的 docker 容器，并且将容器的 6030 到 6049 端口映射到宿主机的 6030 到 6049 端口上。如果宿主机已经运行了 TDengine server 并占用了相同端口，需要映射容器的端口到不同的未使用端口段。（详情参见 [TDengine 2.0 端口说明](https://www.taosdata.com/cn/documentation/faq#port)）。为了支持 TDengine 客户端操作 TDengine server 服务， TCP 和 UDP 端口都需要打开。
+
+- **docker run**：通过 Docker 运行一个容器
+- **-d**：让容器在后台运行
+- **-p**：指定映射端口。注意：如果不是用端口映射，依然可以进入 Docker 容器内部使用 TDengine 服务或进行应用开发，只是不能对容器外部提供服务
+- **tdengine/tdengine**：拉取的 TDengine 官方发布的应用镜像
+- **526aa188da767ae94b244226a2b2eec2b5f17dd8eff592893d9ec0cd0f3a1ccd**：这个返回的长字符是容器 ID，我们也可以通过容器 ID 来查看对应的容器
+
+进一步，还可以使用 docker run 命令启动运行 TDengine server 的 docker 容器，并使用 `--name` 命令行参数将容器命名为 `tdengine`，使用 `--hostname` 指定 hostname 为 `tdengine-server`，通过 `-v` 挂载本地目录到容器，实现宿主机与容器内部的数据同步，防止容器删除后，数据丢失。
+
+```bash
+docker run -d --name tdengine --hostname="tdengine-server" -v ~/work/taos/log:/var/log/taos -v ~/work/taos/data:/var/lib/taos -p 6030-6049:6030-6049 -p 6030-6049:6030-6049/udp tdengine/tdengine
+```
+
+- **--name tdengine**：设置容器名称，我们可以通过容器名称来访问对应的容器
+- **--hostname=tdengine-server**：设置容器内 Linux 系统的 hostname，我们可以通过映射 hostname 和 IP 来解决容器 IP 可能变化的问题。
+- **-v**：设置宿主机文件目录映射到容器内目录，避免容器删除后数据丢失。
+
+### 使用 docker ps 命令确认容器是否已经正确运行
+
+```bash
+docker ps
+```
+
+输出示例如下：
+
+```
+CONTAINER ID IMAGE COMMAND CREATED STATUS ···
+c452519b0f9b tdengine/tdengine "taosd" 14 minutes ago Up 14 minutes ···
+```
+
+- **docker ps**：列出所有正在运行状态的容器信息。
+- **CONTAINER ID**：容器 ID。
+- **IMAGE**：使用的镜像。
+- **COMMAND**：启动容器时运行的命令。
+- **CREATED**：容器创建时间。
+- **STATUS**：容器状态。UP 表示运行中。
+
+### 通过 docker exec 命令，进入到 docker 容器中去做开发
+
+```bash
+$ docker exec -it tdengine /bin/bash
+root@tdengine-server:~/TDengine-server-2.4.0.4#
+```
+
+- **docker exec**：通过 docker exec 命令进入容器，如果退出，容器不会停止。
+- **-i**：进入交互模式。
+- **-t**：指定一个终端。
+- **tdengine**：容器名称，需要根据 docker ps 指令返回的值进行修改。
+- **/bin/bash**：载入容器后运行 bash 来进行交互。
+
+进入容器后，执行 taos shell 客户端程序。
+
+```bash
+root@tdengine-server:~/TDengine-server-2.4.0.4# taos
+
+Welcome to the TDengine shell from Linux, Client Version:2.4.0.4
+Copyright (c) 2020 by TAOS Data, Inc. All rights reserved.
+
+taos>
+```
+
+TDengine 终端成功连接服务端，打印出了欢迎消息和版本信息。如果失败，会有错误信息打印出来。
+
+在 TDengine 终端中，可以通过 SQL 命令来创建/删除数据库、表、超级表等，并可以进行插入和查询操作。具体可以参考 [TAOS SQL 说明文档](https://www.taosdata.com/cn/documentation/taos-sql)。
+
+### 在宿主机访问 Docker 容器中的 TDengine server
+
+在使用了 -p 命令行参数映射了正确的端口启动了 TDengine Docker 容器后，就在宿主机使用 taos shell 命令即可访问运行在 Docker 容器中的 TDengine。
+
+```
+$ taos
+
+Welcome to the TDengine shell from Linux, Client Version:2.4.0.4
+Copyright (c) 2020 by TAOS Data, Inc. All rights reserved.
+
+taos>
+```
+
+也可以在宿主机使用 curl 通过 RESTful 端口访问 Docker 容器内的 TDengine server。
+
+```
+curl -u root:taosdata -d 'show databases' 127.0.0.1:6041/rest/sql
+```
+
+输出示例如下：
+
+```
+{"status":"succ","head":["name","created_time","ntables","vgroups","replica","quorum","days","keep0,keep1,keep(D)","cache(MB)","blocks","minrows","maxrows","wallevel","fsync","comp","cachelast","precision","update","status"],"column_meta":[["name",8,32],["created_time",9,8],["ntables",4,4],["vgroups",4,4],["replica",3,2],["quorum",3,2],["days",3,2],["keep0,keep1,keep(D)",8,24],["cache(MB)",4,4],["blocks",4,4],["minrows",4,4],["maxrows",4,4],["wallevel",2,1],["fsync",4,4],["comp",2,1],["cachelast",2,1],["precision",8,3],["update",2,1],["status",8,10]],"data":[["test","2021-08-18 06:01:11.021",10000,4,1,1,10,"3650,3650,3650",16,6,100,4096,1,3000,2,0,"ms",0,"ready"],["log","2021-08-18 05:51:51.065",4,1,1,1,10,"30,30,30",1,3,100,4096,1,3000,2,0,"us",0,"ready"]],"rows":2}
+```
+
+这条命令，通过 RESTful 接口访问 TDengine server，这时连接的是本机的 6041 端口，可见连接成功。
+
+TDengine RESTful 接口详情请参考[官方文档](https://www.taosdata.com/cn/documentation/connector#restful)。
+
+### 使用 Docker 容器运行 TDengine server 和 taosAdapter
+
+在 TDegnine 2.4.0.0 之后版本的 Docker 容器，开始提供一个独立运行的组件 taosAdapter，代替之前版本 TDengine 中 taosd 进程中内置的 http server。taosAdapter 支持通过 RESTful 接口对 TDengine server 的数据写入和查询能力，并提供和 InfluxDB/OpenTSDB 兼容的数据摄取接口，允许 InfluxDB/OpenTSDB 应用程序无缝移植到 TDengine。在新版本 Docker 镜像中，默认启用了 taosAdapter，也可以使用 docker run 命令中设置 TAOS_DISABLE_ADAPTER=true 来禁用 taosAdapter；也可以在 docker run 命令中单独使用 taosAdapter，而不运行 taosd 。
+
+注意：如果容器中运行 taosAdapter，需要根据需要映射其他端口，具体端口默认配置和修改方法请参考[taosAdapter 文档](https://github.com/taosdata/taosadapter/blob/develop/README-CN.md)。
+
+使用 docker 运行 TDengine 2.4.0.4 版本镜像（taosd + taosAdapter）：
+
+```bash
+docker run -d --name tdengine-all -p 6030-6049:6030-6049 -p 6030-6049:6030-6049/udp tdengine/tdengine:2.4.0.4
+```
+
+使用 docker 运行 TDengine 2.4.0.4 版本镜像（仅 taosAdapter，需要设置 firstEp 配置项 或 TAOS_FIRST_EP 环境变量）：
+
+```bash
+docker run -d --name tdengine-taosa -p 6041-6049:6041-6049 -p 6041-6049:6041-6049/udp -e TAOS_FIRST_EP=tdengine-all tdengine/tdengine:2.4.0.4 taosadapter
+```
+
+使用 docker 运行 TDengine 2.4.0.4 版本镜像（仅 taosd）：
+
+```bash
+docker run -d --name tdengine-taosd -p 6030-6042:6030-6042 -p 6030-6042:6030-6042/udp -e TAOS_DISABLE_ADAPTER=true tdengine/tdengine:2.4.0.4
+```
+
+使用 curl 命令验证 RESTful 接口可以正常工作：
+
+```bash
+curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'show databases;' 127.0.0.1:6041/rest/sql
+```
+
+输出示例如下：
+
+```
+{"status":"succ","head":["name","created_time","ntables","vgroups","replica","quorum","days","keep","cache(MB)","blocks","minrows","maxrows","wallevel","fsync","comp","cachelast","precision","update","status"],"column_meta":[["name",8,32],["created_time",9,8],["ntables",4,4],["vgroups",4,4],["replica",3,2],["quorum",3,2],["days",3,2],["keep",8,24],["cache(MB)",4,4],["blocks",4,4],["minrows",4,4],["maxrows",4,4],["wallevel",2,1],["fsync",4,4],["comp",2,1],["cachelast",2,1],["precision",8,3],["update",2,1],["status",8,10]],"data":[["log","2021-12-28 09:18:55.765",10,1,1,1,10,"30",1,3,100,4096,1,3000,2,0,"us",0,"ready"]],"rows":1}
+```
+
+### 应用示例：在宿主机使用 taosBenchmark 写入数据到 Docker 容器中的 TDengine server
+
+1. 在宿主机命令行界面执行 taosBenchmark （曾命名为 taosdemo）写入数据到 Docker 容器中的 TDengine server
+
+ ```bash
+ $ taosBenchmark
+
+ taosBenchmark is simulating data generated by power equipments monitoring...
+
+ host: 127.0.0.1:6030
+ user: root
+ password: taosdata
+ configDir:
+ resultFile: ./output.txt
+ thread num of insert data: 10
+ thread num of create table: 10
+ top insert interval: 0
+ number of records per req: 30000
+ max sql length: 1048576
+ database count: 1
+ database[0]:
+ database[0] name: test
+ drop: yes
+ replica: 1
+ precision: ms
+ super table count: 1
+ super table[0]:
+ stbName: meters
+ autoCreateTable: no
+ childTblExists: no
+ childTblCount: 10000
+ childTblPrefix: d
+ dataSource: rand
+ iface: taosc
+ insertRows: 10000
+ interlaceRows: 0
+ disorderRange: 1000
+ disorderRatio: 0
+ maxSqlLen: 1048576
+ timeStampStep: 1
+ startTimestamp: 2017-07-14 10:40:00.000
+ sampleFormat:
+ sampleFile:
+ tagsFile:
+ columnCount: 3
+ column[0]:FLOAT column[1]:INT column[2]:FLOAT
+ tagCount: 2
+ tag[0]:INT tag[1]:BINARY(16)
+
+ Press enter key to continue or Ctrl-C to stop
+ ```
+
+ 回车后，该命令将在数据库 test 下面自动创建一张超级表 meters，该超级表下有 1 万张表，表名为 "d0" 到 "d9999"，每张表有 1 万条记录，每条记录有 (ts, current, voltage, phase) 四个字段，时间戳从 "2017-07-14 10:40:00 000" 到 "2017-07-14 10:40:09 999"，每张表带有标签 location 和 groupId，groupId 被设置为 1 到 10， location 被设置为 "beijing" 或者 "shanghai"。
+
+ 最后共插入 1 亿条记录。
+
+2. 进入 TDengine 终端，查看 taosBenchmark 生成的数据。
+
+ - **进入命令行。**
+
+ ```bash
+ $ root@c452519b0f9b:~/TDengine-server-2.4.0.4# taos
+
+ Welcome to the TDengine shell from Linux, Client Version:2.4.0.4
+ Copyright (c) 2020 by TAOS Data, Inc. All rights reserved.
+
+ taos>
+ ```
+
+ - **查看数据库。**
+
+ ```bash
+ $ taos> show databases;
+ name | created_time | ntables | vgroups | ···
+ test | 2021-08-18 06:01:11.021 | 10000 | 6 | ···
+ log | 2021-08-18 05:51:51.065 | 4 | 1 | ···
+
+ ```
+
+ - **查看超级表。**
+
+ ```bash
+ $ taos> use test;
+ Database changed.
+
+ $ taos> show stables;
+ name | created_time | columns | tags | tables |
+ ============================================================================================
+ meters | 2021-08-18 06:01:11.116 | 4 | 2 | 10000 |
+ Query OK, 1 row(s) in set (0.003259s)
+
+ ```
+
+ - **查看表，限制输出十条。**
+
+ ```bash
+ $ taos> select * from test.t0 limit 10;
+
+ DB error: Table does not exist (0.002857s)
+ taos> select * from test.d0 limit 10;
+ ts | current | voltage | phase |
+ ======================================================================================
+ 2017-07-14 10:40:00.000 | 10.12072 | 223 | 0.34167 |
+ 2017-07-14 10:40:00.001 | 10.16103 | 224 | 0.34445 |
+ 2017-07-14 10:40:00.002 | 10.00204 | 220 | 0.33334 |
+ 2017-07-14 10:40:00.003 | 10.00030 | 220 | 0.33333 |
+ 2017-07-14 10:40:00.004 | 9.84029 | 216 | 0.32222 |
+ 2017-07-14 10:40:00.005 | 9.88028 | 217 | 0.32500 |
+ 2017-07-14 10:40:00.006 | 9.88110 | 217 | 0.32500 |
+ 2017-07-14 10:40:00.007 | 10.08137 | 222 | 0.33889 |
+ 2017-07-14 10:40:00.008 | 10.12063 | 223 | 0.34167 |
+ 2017-07-14 10:40:00.009 | 10.16086 | 224 | 0.34445 |
+ Query OK, 10 row(s) in set (0.016791s)
+
+ ```
+
+ - **查看 d0 表的标签值。**
+
+ ```bash
+ $ taos> select groupid, location from test.d0;
+ groupid | location |
+ =================================
+ 0 | shanghai |
+ Query OK, 1 row(s) in set (0.003490s)
+ ```
+
+### 应用示例：使用数据收集代理软件写入 TDengine
+
+taosAdapter 支持多个数据收集代理软件（如 Telegraf、StatsD、collectd 等），这里仅模拟 StasD 写入数据，在宿主机执行命令如下：
+
+```
+echo "foo:1|c" | nc -u -w0 127.0.0.1 6044
+```
+
+然后可以使用 taos shell 查询 taosAdapter 自动创建的数据库 statsd 和 超级表 foo 中的内容：
+
+```
+taos> show databases;
+ name | created_time | ntables | vgroups | replica | quorum | days | keep | cache(MB) | blocks | minrows | maxrows | wallevel | fsync | comp | cachelast | precision | update | status |
+====================================================================================================================================================================================================================================================================================
+ log | 2021-12-28 09:18:55.765 | 12 | 1 | 1 | 1 | 10 | 30 | 1 | 3 | 100 | 4096 | 1 | 3000 | 2 | 0 | us | 0 | ready |
+ statsd | 2021-12-28 09:21:48.841 | 1 | 1 | 1 | 1 | 10 | 3650 | 16 | 6 | 100 | 4096 | 1 | 3000 | 2 | 0 | ns | 2 | ready |
+Query OK, 2 row(s) in set (0.002112s)
+
+taos> use statsd;
+Database changed.
+
+taos> show stables;
+ name | created_time | columns | tags | tables |
+============================================================================================
+ foo | 2021-12-28 09:21:48.894 | 2 | 1 | 1 |
+Query OK, 1 row(s) in set (0.001160s)
+
+taos> select * from foo;
+ ts | value | metric_type |
+=======================================================================================
+ 2021-12-28 09:21:48.840820836 | 1 | counter |
+Query OK, 1 row(s) in set (0.001639s)
+
+taos>
+```
+
+可以看到模拟数据已经被写入到 TDengine 中。
+
+## 停止正在 Docker 中运行的 TDengine 服务
+
+```bash
+docker stop tdengine
+```
+
+- **docker stop**：通过 docker stop 停止指定的正在运行中的 docker 镜像。
diff --git a/docs-cn/17-train-fqa/_category_.yml b/docs-cn/17-train-fqa/_category_.yml
new file mode 100644
index 0000000000000000000000000000000000000000..034d5894b9aea00e43caf4df21cb39487d8baf7b
--- /dev/null
+++ b/docs-cn/17-train-fqa/_category_.yml
@@ -0,0 +1,4 @@
+label: FAQ、教程及其它
+link:
+ slug: /train-faq/
+ type: generated-index
diff --git a/docs-examples/.gitignore b/docs-examples/.gitignore
new file mode 100644
index 0000000000000000000000000000000000000000..7ed6d403bf5f64c0cb230265b4dffee609dea93b
--- /dev/null
+++ b/docs-examples/.gitignore
@@ -0,0 +1,3 @@
+.vscode
+*.lock
+.idea
\ No newline at end of file
diff --git a/docs-examples/.gitignre b/docs-examples/.gitignre
new file mode 100644
index 0000000000000000000000000000000000000000..0853156c65c2c6c1b693290e74c3ee630bcaac19
--- /dev/null
+++ b/docs-examples/.gitignre
@@ -0,0 +1,2 @@
+.vscode
+*.lock
\ No newline at end of file
diff --git a/docs-examples/c/.gitignore b/docs-examples/c/.gitignore
new file mode 100644
index 0000000000000000000000000000000000000000..afe974314989a1e3aa4eee703738a9a960c18577
--- /dev/null
+++ b/docs-examples/c/.gitignore
@@ -0,0 +1,3 @@
+*
+!*.c
+!.gitignore
diff --git a/docs-examples/c/connect_example b/docs-examples/c/connect_example
new file mode 100644
index 0000000000000000000000000000000000000000..1d9451cbf6724d51dbbc9baeba97d779461b2a5d
Binary files /dev/null and b/docs-examples/c/connect_example differ
diff --git a/docs-examples/c/connect_example.c b/docs-examples/c/connect_example.c
new file mode 100644
index 0000000000000000000000000000000000000000..a64bc43361a05ba91b8637a15c7379fc3a2aef12
--- /dev/null
+++ b/docs-examples/c/connect_example.c
@@ -0,0 +1,13 @@
+// compile with
+// gcc connect_example.c -o connect_example -I /usr/local/taos/include -L /usr/local/taos/driver -ltaos
+#include