Skip to content

T
TDengine

taosdata / TDengine
1 年多 前同步成功

通知 1185
Star 22016
Fork 4786
T
TDengine
未验证 提交 9dfb5717 编写于 作者: sangshuduo's avatar sangshuduo 提交者： GitHub
浏览文件
操作

Test/sangshuduo/td 13408 move example back (#10466) 

* [TD-13408]<test>: move examples back

* [TD-13408]<test>: move examples back

* add examples/c to CMakeLists.txt

* update tests

* [TD-13408]<test>: move rust example back

* fix examples path for Windows

* fix tests/exmaples
上级 009b81fa
隐藏空白更改
内联 并排
Showing with 315 addition and 289 deletion
.gitmodules
浏览文件 @ 9dfb5717
......@@ -23,4 +23,4 @@
branch = develop
[submodule "examples/rust"]
path = examples/rust
url = https://github.com/songtianyi/tdengine-rust-bindings.git
\ No newline at end of file
url = https://github.com/songtianyi/tdengine-rust-bindings.git
cmake/install.inc
浏览文件 @ 9dfb5717
......@@ -9,7 +9,7 @@ ELSEIF (TD_WINDOWS)
INSTALL(DIRECTORY ${TD_COMMUNITY_DIR}/src/connector/nodejs DESTINATION connector)
INSTALL(DIRECTORY ${TD_COMMUNITY_DIR}/src/connector/python DESTINATION connector)
INSTALL(DIRECTORY ${TD_COMMUNITY_DIR}/src/connector/C\# DESTINATION connector)
INSTALL(DIRECTORY ${TD_COMMUNITY_DIR}/tests/examples DESTINATION .)
INSTALL(DIRECTORY ${TD_COMMUNITY_DIR}/examples DESTINATION .)
INSTALL(FILES ${TD_COMMUNITY_DIR}/packaging/cfg/taos.cfg DESTINATION cfg)
INSTALL(FILES ${TD_COMMUNITY_DIR}/src/inc/taos.h DESTINATION include)
INSTALL(FILES ${TD_COMMUNITY_DIR}/src/inc/taoserror.h DESTINATION include)
......
documentation20/cn/07.advanced-features/docs.md
浏览文件 @ 9dfb5717
......@@ -2,19 +2,19 @@
## <a class="anchor" id="continuous-query"></a>连续查询（Continuous Query）
连续查询是TDengine定期自动执行的查询，采用滑动窗口的方式进行计算，是一种简化的时间驱动的流式计算。针对库中的表或超级表，TDengine可提供定期自动执行的连续查询，用户可让TDengine推送查询的结果，也可以将结果再写回到TDengine中。每次执行的查询是一个时间窗口，时间窗口随着时间流动向前滑动。在定义连续查询的时候需要指定时间窗口（time window, 参数interval）大小和每次前向增量时间（forward sliding times, 参数sliding）。
连续查询是 TDengine 定期自动执行的查询，采用滑动窗口的方式进行计算，是一种简化的时间驱动的流式计算。针对库中的表或超级表，TDengine 可提供定期自动执行的连续查询，用户可让 TDengine 推送查询的结果，也可以将结果再写回到 TDengine 中。每次执行的查询是一个时间窗口，时间窗口随着时间流动向前滑动。在定义连续查询的时候需要指定时间窗口（time window, 参数interval）大小和每次前向增量时间（forward sliding times, 参数sliding）。
TDengine的连续查询采用时间驱动模式，可以直接使用TAOS SQL进行定义，不需要额外的操作。使用连续查询，可以方便快捷地按照时间窗口生成结果，从而对原始采集数据进行降采样（down sampling）。用户通过TAOS SQL定义连续查询以后，TDengine自动在最后的一个完整的时间周期末端拉起查询，并将计算获得的结果推送给用户或者写回TDengine。
TDengine 的连续查询采用时间驱动模式，可以直接使用 TAOS SQL 进行定义，不需要额外的操作。使用连续查询，可以方便快捷地按照时间窗口生成结果，从而对原始采集数据进行降采样（down sampling）。用户通过 TAOS SQL 定义连续查询以后，TDengine 自动在最后的一个完整的时间周期末端拉起查询，并将计算获得的结果推送给用户或者写回 TDengine。
TDengine提供的连续查询与普通流计算中的时间窗口计算具有以下区别：
TDengine 提供的连续查询与普通流计算中的时间窗口计算具有以下区别：
- 不同于流计算的实时反馈计算结果，连续查询只在时间窗口关闭以后才开始计算。例如时间周期是1天，那么当天的结果只会在23:59:59以后才会生成。
- 如果有历史记录写入到已经计算完成的时间区间，连续查询并不会重新进行计算，也不会重新将结果推送给用户。对于写回TDengine的模式，也不会更新已经存在的计算结果。
- 使用连续查询推送结果的模式，服务端并不缓存客户端计算状态，也不提供Exactly-Once的语意保证。如果用户的应用端崩溃，再次拉起的连续查询将只会从再次拉起的时间开始重新计算最近的一个完整的时间窗口。如果使用写回模式，TDengine可确保数据写回的有效性和连续性。
- 不同于流计算的实时反馈计算结果，连续查询只在时间窗口关闭以后才开始计算。例如时间周期是 1 天，那么当天的结果只会在 23:59:59 以后才会生成。
- 如果有历史记录写入到已经计算完成的时间区间，连续查询并不会重新进行计算，也不会重新将结果推送给用户。对于写回 TDengine 的模式，也不会更新已经存在的计算结果。
- 使用连续查询推送结果的模式，服务端并不缓存客户端计算状态，也不提供 Exactly-Once 的语意保证。如果用户的应用端崩溃，再次拉起的连续查询将只会从再次拉起的时间开始重新计算最近的一个完整的时间窗口。如果使用写回模式，TDengine 可确保数据写回的有效性和连续性。
### 使用连续查询
下面以智能电表场景为例介绍连续查询的具体使用方法。假设我们通过下列SQL语句创建了超级表和子表：
下面以智能电表场景为例介绍连续查询的具体使用方法。假设我们通过下列 SQL 语句创建了超级表和子表：
```sql
create table meters (ts timestamp, current float, voltage int, phase float) tags (location binary(64), groupId int);
......@@ -23,25 +23,25 @@ create table D1002 using meters tags ("Beijing.Haidian", 2);
...
```
我们已经知道，可以通过下面这条SQL语句以一分钟为时间窗口、30秒为前向增量统计这些电表的平均电压。
我们已经知道，可以通过下面这条 SQL 语句以一分钟为时间窗口、30秒为前向增量统计这些电表的平均电压。
```sql
select avg(voltage) from meters interval(1m) sliding(30s);
```
每次执行这条语句，都会重新计算所有数据。 如果需要每隔30秒执行一次来增量计算最近一分钟的数据，可以把上面的语句改进成下面的样子，每次使用不同的 `startTime` 并定期执行：
每次执行这条语句，都会重新计算所有数据。 如果需要每隔 30 秒执行一次来增量计算最近一分钟的数据，可以把上面的语句改进成下面的样子，每次使用不同的 `startTime` 并定期执行：
```sql
select avg(voltage) from meters where ts > {startTime} interval(1m) sliding(30s);
```
这样做没有问题，但TDengine提供了更简单的方法，只要在最初的查询语句前面加上 `create table {tableName} as ` 就可以了，例如：
这样做没有问题，但 TDengine 提供了更简单的方法，只要在最初的查询语句前面加上 `create table {tableName} as` 就可以了，例如：
```sql
create table avg_vol as select avg(voltage) from meters interval(1m) sliding(30s);
```
会自动创建一个名为 `avg_vol` 的新表，然后每隔30秒，TDengine会增量执行 `as` 后面的 SQL 语句，并将查询结果写入这个表中，用户程序后续只要从 `avg_vol` 中查询数据即可。例如：
会自动创建一个名为 `avg_vol` 的新表，然后每隔 30 秒，TDengine 会增量执行 `as` 后面的 SQL 语句，并将查询结果写入这个表中，用户程序后续只要从 `avg_vol` 中查询数据即可。例如：
```mysql
taos> select * from avg_vol;
......@@ -55,29 +55,27 @@ taos> select * from avg_vol;
需要注意，查询时间窗口的最小值是10毫秒，没有时间窗口范围的上限。
此外，TDengine还支持用户指定连续查询的起止时间。如果不输入开始时间，连续查询将从第一条原始数据所在的时间窗口开始；如果没有输入结束时间，连续查询将永久运行；如果用户指定了结束时间，连续查询在系统时间达到指定的时间以后停止运行。比如使用下面的SQL创建的连续查询将运行一小时，之后会自动停止。
此外，TDengine 还支持用户指定连续查询的起止时间。如果不输入开始时间，连续查询将从第一条原始数据所在的时间窗口开始；如果没有输入结束时间，连续查询将永久运行；如果用户指定了结束时间，连续查询在系统时间达到指定的时间以后停止运行。比如使用下面的SQL创建的连续查询将运行一小时，之后会自动停止。
```mysql
create table avg_vol as select avg(voltage) from meters where ts > now and ts <= now + 1h interval(1m) sliding(30s);
```
需要说明的是，上面例子中的 `now` 是指创建连续查询的时间，而不是查询执行的时间，否则，查询就无法自动停止了。另外，为了尽量避免原始数据延迟写入导致的问题，TDengine中连续查询的计算有一定的延迟。也就是说，一个时间窗口过去后，TDengine并不会立即计算这个窗口的数据，所以要稍等一会（一般不会超过1分钟）才能查到计算结果。
需要说明的是，上面例子中的 `now` 是指创建连续查询的时间，而不是查询执行的时间，否则，查询就无法自动停止了。另外，为了尽量避免原始数据延迟写入导致的问题，TDengine 中连续查询的计算有一定的延迟。也就是说，一个时间窗口过去后，TDengine 并不会立即计算这个窗口的数据，所以要稍等一会（一般不会超过 1 分钟）才能查到计算结果。
### 管理连续查询
用户可在控制台中通过 `show streams` 命令来查看系统中全部运行的连续查询，并可以通过 `kill stream` 命令杀掉对应的连续查询。后续版本会提供更细粒度和便捷的连续查询管理命令。
## <a class="anchor" id="subscribe"></a>数据订阅（Publisher/Subscriber）
基于数据天然的时间序列特性，TDengine的数据写入（insert）与消息系统的数据发布（pub）逻辑上一致，均可视为系统中插入一条带时间戳的新记录。同时，TDengine在内部严格按照数据时间序列单调递增的方式保存数据。本质上来说，TDengine中里每一张表均可视为一个标准的消息队列。
基于数据天然的时间序列特性，TDengine 的数据写入（insert）与消息系统的数据发布（pub）逻辑上一致，均可视为系统中插入一条带时间戳的新记录。同时，TDengine 在内部严格按照数据时间序列单调递增的方式保存数据。本质上来说，TDengine 中里每一张表均可视为一个标准的消息队列。
TDengine内嵌支持轻量级的消息订阅与推送服务。使用系统提供的API，用户可使用普通查询语句订阅数据库中的一张或多张表。订阅的逻辑和操作状态的维护均是由客户端完成，客户端定时轮询服务器是否有新的记录到达，有新的记录到达就会将结果反馈到客户。
TDengine 内嵌支持轻量级的消息订阅与推送服务。使用系统提供的 API，用户可使用普通查询语句订阅数据库中的一张或多张表。订阅的逻辑和操作状态的维护均是由客户端完成，客户端定时轮询服务器是否有新的记录到达，有新的记录到达就会将结果反馈到客户。
TDengine的订阅与推送服务的状态是客户端维持，TDengine服务器并不维持。因此如果应用重启，从哪个时间点开始获取最新数据，由应用决定。
TDengine 的订阅与推送服务的状态是客户端维持，TDengine 服务器并不维持。因此如果应用重启，从哪个时间点开始获取最新数据，由应用决定。
TDengine的API中，与订阅相关的主要有以下三个：
TDengine 的 API 中，与订阅相关的主要有以下三个：
```c
taos_subscribe
......@@ -85,9 +83,9 @@ taos_consume
taos_unsubscribe
```
这些API的文档请见 [C/C++ Connector](https://www.taosdata.com/cn/documentation/connector#c-cpp)，下面仍以智能电表场景为例介绍一下它们的具体用法（超级表和子表结构请参考上一节“连续查询”），完整的示例代码可以在 [这里](https://github.com/taosdata/TDengine/blob/master/tests/examples/c/subscribe.c) 找到。
这些API的文档请见 [C/C++ Connector](https://www.taosdata.com/cn/documentation/connector#c-cpp)，下面仍以智能电表场景为例介绍一下它们的具体用法（超级表和子表结构请参考上一节“连续查询”），完整的示例代码可以在 [这里](https://github.com/taosdata/TDengine/blob/master/examples/c/subscribe.c) 找到。
如果我们希望当某个电表的电流超过一定限制（比如10A）后能得到通知并进行一些处理， 有两种方法：一是分别对每张子表进行查询，每次查询后记录最后一条数据的时间戳，后续只查询这个时间戳之后的数据：
如果我们希望当某个电表的电流超过一定限制（比如 10A）后能得到通知并进行一些处理， 有两种方法：一是分别对每张子表进行查询，每次查询后记录最后一条数据的时间戳，后续只查询这个时间戳之后的数据：
```sql
select * from D1001 where ts > {last_timestamp1} and current > 10;
......@@ -103,11 +101,11 @@ select * from D1002 where ts > {last_timestamp2} and current > 10;
select * from meters where ts > {last_timestamp} and current > 10;
```
但是，如何选择 `last_timestamp` 就成了一个新的问题。因为，一方面数据的产生时间（也就是数据时间戳）和数据入库的时间一般并不相同，有时偏差还很大；另一方面，不同电表的数据到达TDengine的时间也会有差异。所以，如果我们在查询中使用最慢的那台电表的数据的时间戳作为 `last_timestamp`，就可能重复读入其它电表的数据；如果使用最快的电表的时间戳，其它电表的数据就可能被漏掉。
但是，如何选择 `last_timestamp` 就成了一个新的问题。因为，一方面数据的产生时间（也就是数据时间戳）和数据入库的时间一般并不相同，有时偏差还很大；另一方面，不同电表的数据到达 TDengine 的时间也会有差异。所以，如果我们在查询中使用最慢的那台电表的数据的时间戳作为 `last_timestamp`，就可能重复读入其它电表的数据；如果使用最快的电表的时间戳，其它电表的数据就可能被漏掉。
TDengine的订阅功能为上面这个问题提供了一个彻底的解决方案。
TDengine 的订阅功能为上面这个问题提供了一个彻底的解决方案。
首先是使用`taos_subscribe`创建订阅：
首先是使用 `taos_subscribe` 创建订阅：
```c
TAOS_SUB* tsub = NULL;
......@@ -120,11 +118,11 @@ if (async) {
}
```
TDengine中的订阅既可以是同步的，也可以是异步的，上面的代码会根据从命令行获取的参数`async`的值来决定使用哪种方式。这里，同步的意思是用户程序要直接调用`taos_consume`来拉取数据，而异步则由API在内部的另一个线程中调用`taos_consume`，然后把拉取到的数据交给回调函数`subscribe_callback`去处理。（注意，`subscribe_callback` 中不宜做较为耗时的操作，否则有可能导致客户端阻塞等不可控的问题。）
TDengine 中的订阅既可以是同步的，也可以是异步的，上面的代码会根据从命令行获取的参数 `async` 的值来决定使用哪种方式。这里，同步的意思是用户程序要直接调用 `taos_consume` 来拉取数据，而异步则由 API 在内部的另一个线程中调用 `taos_consume`，然后把拉取到的数据交给回调函数 `subscribe_callback`去处理。（注意，`subscribe_callback` 中不宜做较为耗时的操作，否则有可能导致客户端阻塞等不可控的问题。）
参数`taos`是一个已经建立好的数据库连接，在同步模式下无特殊要求。但在异步模式下，需要注意它不会被其它线程使用，否则可能导致不可预计的错误，因为回调函数在API的内部线程中被调用，而TDengine的部分API不是线程安全的。
参数 `taos` 是一个已经建立好的数据库连接，在同步模式下无特殊要求。但在异步模式下，需要注意它不会被其它线程使用，否则可能导致不可预计的错误，因为回调函数在API的内部线程中被调用，而 TDengine 的部分 API 不是线程安全的。
参数`sql`是查询语句，可以在其中使用where子句指定过滤条件。在我们的例子中，如果只想订阅电流超过10A时的数据，可以这样写：
参数 `sql` 是查询语句，可以在其中使用where子句指定过滤条件。在我们的例子中，如果只想订阅电流超过 10A 时的数据，可以这样写：
```sql
select * from meters where current > 10;
......@@ -136,13 +134,13 @@ select * from meters where current > 10;
select * from meters where ts > now - 1d and current > 10;
```
订阅的`topic`实际上是它的名字，因为订阅功能是在客户端API中实现的，所以没必要保证它全局唯一，但需要它在一台客户端机器上唯一。
订阅的 `topic` 实际上是它的名字，因为订阅功能是在客户端API中实现的，所以没必要保证它全局唯一，但需要它在一台客户端机器上唯一。
如果名为`topic`的订阅不存在，参数`restart`没有意义；但如果用户程序创建这个订阅后退出，当它再次启动并重新使用这个`topic`时，`restart`就会被用于决定是从头开始读取数据，还是接续上次的位置进行读取。本例中，如果`restart`是 **true**（非零值），用户程序肯定会读到所有数据。但如果这个订阅之前就存在了，并且已经读取了一部分数据，且`restart`是 **false**（**0**），用户程序就不会读到之前已经读取的数据了。
如果名为 `topic` 的订阅不存在，参数 `restart` 没有意义；但如果用户程序创建这个订阅后退出，当它再次启动并重新使用这个 `topic` 时，`restart` 就会被用于决定是从头开始读取数据，还是接续上次的位置进行读取。本例中，如果 `restart` 是 **true**（非零值），用户程序肯定会读到所有数据。但如果这个订阅之前就存在了，并且已经读取了一部分数据，且 `restart` 是 **false**（**0**），用户程序就不会读到之前已经读取的数据了。
`taos_subscribe`的最后一个参数是以毫秒为单位的轮询周期。在同步模式下，如果前后两次调用`taos_consume`的时间间隔小于此时间，`taos_consume`会阻塞，直到间隔超过此时间。异步模式下，这个时间是两次调用回调函数的最小时间间隔。
`taos_subscribe`的最后一个参数是以毫秒为单位的轮询周期。在同步模式下，如果前后两次调用 `taos_consume` 的时间间隔小于此时间，`taos_consume` 会阻塞，直到间隔超过此时间。异步模式下，这个时间是两次调用回调函数的最小时间间隔。
`taos_subscribe`的倒数第二个参数用于用户程序向回调函数传递附加参数，订阅API不对其做任何处理，只原样传递给回调函数。此参数在同步模式下无意义。
`taos_subscribe` 的倒数第二个参数用于用户程序向回调函数传递附加参数，订阅 API 不对其做任何处理，只原样传递给回调函数。此参数在同步模式下无意义。
订阅创建以后，就可以消费其数据了，同步模式下，示例代码是下面的 else 部分：
......@@ -161,7 +159,7 @@ if (async) {
}
```
这里是一个 **while** 循环，用户每按一次回车键就调用一次`taos_consume`，而`taos_consume`的返回值是查询到的结果集，与`taos_use_result`完全相同，例子中使用这个结果集的代码是函数`print_result`：
这里是一个 **while** 循环，用户每按一次回车键就调用一次 `taos_consume`，而 `taos_consume` 的返回值是查询到的结果集，与 `taos_use_result` 完全相同，例子中使用这个结果集的代码是函数 `print_result`：
```c
void print_result(TAOS_RES* res, int blockFetch) {
......@@ -196,13 +194,13 @@ void subscribe_callback(TAOS_SUB* tsub, TAOS_RES *res, void* param, int code) {
}
```
当要结束一次数据订阅时，需要调用`taos_unsubscribe`：
当要结束一次数据订阅时，需要调用 `taos_unsubscribe`：
```c
taos_unsubscribe(tsub, keep);
```
其第二个参数，用于决定是否在客户端保留订阅的进度信息。如果这个参数是**false**（**0**），那无论下次调用`taos_subscribe`时的`restart`参数是什么，订阅都只能重新开始。另外，进度信息的保存位置是 *{DataDir}/subscribe/* 这个目录下，每个订阅有一个与其`topic`同名的文件，删掉某个文件，同样会导致下次创建其对应的订阅时只能重新开始。
其第二个参数，用于决定是否在客户端保留订阅的进度信息。如果这个参数是**false**（**0**），那无论下次调用 `taos_subscribe` 时的 `restart` 参数是什么，订阅都只能重新开始。另外，进度信息的保存位置是 *{DataDir}/subscribe/* 这个目录下，每个订阅有一个与其 `topic` 同名的文件，删掉某个文件，同样会导致下次创建其对应的订阅时只能重新开始。
代码介绍完毕，我们来看一下实际的运行效果。假设：
......@@ -213,8 +211,8 @@ taos_unsubscribe(tsub, keep);
则可以在示例代码所在目录执行以下命令来编译并启动示例程序：
```bash
$ make
$ ./subscribe -sql='select * from meters where current > 10;'
make
./subscribe -sql='select * from meters where current > 10;'
```
示例程序启动后，打开另一个终端窗口，启动 TDengine 的 shell 向 **D1001** 插入一条电流为 12A 的数据：
......@@ -225,13 +223,13 @@ $ taos
> insert into D1001 values(now, 12, 220, 1);
```
这时，因为电流超过了10A，您应该可以看到示例程序将它输出到了屏幕上。您可以继续插入一些数据观察示例程序的输出。
这时，因为电流超过了 10A，您应该可以看到示例程序将它输出到了屏幕上。您可以继续插入一些数据观察示例程序的输出。
### Java 使用数据订阅功能
订阅功能也提供了 Java 开发接口，相关说明请见 [Java Connector](https://www.taosdata.com/cn/documentation/connector/java#subscribe)。需要注意的是，目前 Java 接口没有提供异步订阅模式，但用户程序可以通过创建 `TimerTask` 等方式达到同样的效果。
下面以一个示例程序介绍其具体使用方法。它所完成的功能与前面介绍的 C 语言示例基本相同，也是订阅数据库中所有电流超过 10A 的记录。
下面以一个示例程序介绍其具体使用方法。它所完成的功能与前面介绍的 C 语言示例基本相同，也是订阅数据库中所有电流超过 10A 的记录。
#### 准备数据
......@@ -302,8 +300,8 @@ public class SubscribeDemo {
try {
if (null != subscribe)
subscribe.close(true); // 关闭订阅
if (connection != null)
connection.close();
if (connection != null)
connection.close();
} catch (SQLException throwables) {
throwables.printStackTrace();
}
......@@ -315,7 +313,7 @@ public class SubscribeDemo {
运行示例程序，首先，它会消费符合查询条件的所有历史数据：
```bash
# java -jar subscribe.jar
# java -jar subscribe.jar
ts: 1597464000000 current: 12.0 voltage: 220 phase: 1 location: Beijing.Chaoyang groupid : 2
ts: 1597464600000 current: 12.3 voltage: 220 phase: 2 location: Beijing.Chaoyang groupid : 2
......@@ -338,21 +336,20 @@ taos> insert into d1001 values("2020-08-15 12:40:00.000", 12.4, 220, 1);
ts: 1597466400000 current: 12.4 voltage: 220 phase: 1 location: Beijing.Chaoyang groupid: 2
```
## <a class="anchor" id="cache"></a>缓存（Cache）
TDengine采用时间驱动缓存管理策略（First-In-First-Out，FIFO），又称为写驱动的缓存管理机制。这种策略有别于读驱动的数据缓存模式（Least-Recent-Used，LRU），直接将最近写入的数据保存在系统的缓存中。当缓存达到临界值的时候，将最早的数据批量写入磁盘。一般意义上来说，对于物联网数据的使用，用户最为关心最近产生的数据，即当前状态。TDengine充分利用了这一特性，将最近到达的（当前状态）数据保存在缓存中。
TDengine 采用时间驱动缓存管理策略（First-In-First-Out，FIFO），又称为写驱动的缓存管理机制。这种策略有别于读驱动的数据缓存模式（Least-Recent-Used，LRU），直接将最近写入的数据保存在系统的缓存中。当缓存达到临界值的时候，将最早的数据批量写入磁盘。一般意义上来说，对于物联网数据的使用，用户最为关心最近产生的数据，即当前状态。TDengine 充分利用了这一特性，将最近到达的（当前状态）数据保存在缓存中。
TDengine通过查询函数向用户提供毫秒级的数据获取能力。直接将最近到达的数据保存在缓存中，可以更加快速地响应用户针对最近一条或一批数据的查询分析，整体上提供更快的数据库查询响应能力。从这个意义上来说，可通过设置合适的配置参数将TDengine作为数据缓存来使用，而不需要再部署额外的缓存系统，可有效地简化系统架构，降低运维的成本。需要注意的是，TDengine重启以后系统的缓存将被清空，之前缓存的数据均会被批量写入磁盘，缓存的数据将不会像专门的key-value缓存系统再将之前缓存的数据重新加载到缓存中。
TDengine 通过查询函数向用户提供毫秒级的数据获取能力。直接将最近到达的数据保存在缓存中，可以更加快速地响应用户针对最近一条或一批数据的查询分析，整体上提供更快的数据库查询响应能力。从这个意义上来说，可通过设置合适的配置参数将 TDengine 作为数据缓存来使用，而不需要再部署额外的缓存系统，可有效地简化系统架构，降低运维的成本。需要注意的是，TDengine 重启以后系统的缓存将被清空，之前缓存的数据均会被批量写入磁盘，缓存的数据将不会像专门的 key-value 缓存系统再将之前缓存的数据重新加载到缓存中。
TDengine分配固定大小的内存空间作为缓存空间，缓存空间可根据应用的需求和硬件资源配置。通过适当的设置缓存空间，TDengine可以提供极高性能的写入和查询的支持。TDengine中每个虚拟节点（virtual node）创建时分配独立的缓存池。每个虚拟节点管理自己的缓存池，不同虚拟节点间不共享缓存池。每个虚拟节点内部所属的全部表共享该虚拟节点的缓存池。
TDengine 分配固定大小的内存空间作为缓存空间，缓存空间可根据应用的需求和硬件资源配置。通过适当的设置缓存空间，TDengine 可以提供极高性能的写入和查询的支持。TDengine 中每个虚拟节点（virtual node）创建时分配独立的缓存池。每个虚拟节点管理自己的缓存池，不同虚拟节点间不共享缓存池。每个虚拟节点内部所属的全部表共享该虚拟节点的缓存池。
TDengine将内存池按块划分进行管理，数据在内存块里是以行（row）的形式存储。一个vnode的内存池是在vnode创建时按块分配好，而且每个内存块按照先进先出的原则进行管理。在创建内存池时，块的大小由系统配置参数cache决定；每个vnode中内存块的数目则由配置参数blocks决定。因此对于一个vnode，总的内存大小为：`cache * blocks`。一个cache block需要保证每张表能存储至少几十条以上记录，才会有效率。
TDengine 将内存池按块划分进行管理，数据在内存块里是以行（row）的形式存储。一个 vnode 的内存池是在 vnode 创建时按块分配好，而且每个内存块按照先进先出的原则进行管理。在创建内存池时，块的大小由系统配置参数 cache 决定；每个 vnode 中内存块的数目则由配置参数blocks决定。因此对于一个 vnode，总的内存大小为：`cache * blocks`。一个 cache block 需要保证每张表能存储至少几十条以上记录，才会有效率。
你可以通过函数last_row快速获取一张表或一张超级表的最后一条记录，这样很便于在大屏显示各设备的实时状态或采集值。例如：
你可以通过函数 last_row() 快速获取一张表或一张超级表的最后一条记录，这样很便于在大屏显示各设备的实时状态或采集值。例如：
```mysql
select last_row(voltage) from meters where location='Beijing.Chaoyang';
```
该SQL语句将获取所有位于北京朝阳区的电表最后记录的电压值。
该 SQL 语句将获取所有位于北京朝阳区的电表最后记录的电压值。
documentation20/cn/08.connector/docs.md
浏览文件 @ 9dfb5717
# 连接器
TDengine提供了丰富的应用程序开发接口，其中包括C/C++、Java、Python、Go、Node.js、C# 、RESTful 等，便于用户快速开发应用。
TDengine 提供了丰富的应用程序开发接口，其中包括 C/C++、Java、Python、Go、Node.js、C# 、RESTful 等，便于用户快速开发应用。
![image-connecotr](../images/connector.png)
目前TDengine的连接器可支持的平台广泛，包括：X64/X86/ARM64/ARM32/MIPS/Alpha等硬件平台，以及Linux/Win64/Win32等开发环境。对照矩阵如下：
目前 TDengine 的连接器可支持的平台广泛，包括：X64/X86/ARM64/ARM32/MIPS/Alpha 等硬件平台，以及 Linux/Win64/Win32 等开发环境。对照矩阵如下：
| **CPU** | **X64 64bit** | **X64 64bit** | **X64 64bit** | **X86 32bit** | **ARM64** | **ARM32** | **MIPS 龙芯** | **Alpha 申威** | **X64 海光** |
| ----------- | --------------- | --------------- | --------------- | --------------- | --------- | --------- | --------------- | ---------------- | -------------- |
......@@ -21,24 +21,24 @@ TDengine提供了丰富的应用程序开发接口，其中包括C/C++、Java、
注意：
* 在没有安装TDengine服务端软件的系统中使用连接器（除RESTful外）访问 TDengine 数据库，需要安装相应版本的客户端安装包来使应用驱动（Linux系统中文件名为libtaos.so，Windows系统中为taos.dll）被安装在系统中，否则会产生无法找到相应库文件的错误。
* 所有执行 SQL 语句的 API，例如 C/C++ Connector 中的 `tao_query`、`taos_query_a`、`taos_subscribe` 等，以及其它语言中与它们对应的API，每次都只能执行一条 SQL 语句，如果实际参数中包含了多条语句，它们的行为是未定义的。
* 在没有安装 TDengine 服务端软件的系统中使用连接器（除 RESTful 外）访问 TDengine 数据库，需要安装相应版本的客户端安装包来使应用驱动（Linux 系统中文件名为 libtaos.so，Windows 系统中为 taos.dll）被安装在系统中，否则会产生无法找到相应库文件的错误。
* 所有执行 SQL 语句的 API，例如 C/C++ Connector 中的 `tao_query`、`taos_query_a`、`taos_subscribe` 等，以及其它语言中与它们对应的 API，每次都只能执行一条 SQL 语句，如果实际参数中包含了多条语句，它们的行为是未定义的。
* 升级 TDengine 到 2.0.8.0 版本的用户，必须更新 JDBC。连接 TDengine 必须升级 taos-jdbcdriver 到 2.0.12 及以上。详细的版本依赖关系请参见 [taos-jdbcdriver 文档](https://www.taosdata.com/cn/documentation/connector/java#version)。
* 无论选用何种编程语言的连接器，2.0 及以上版本的 TDengine 推荐数据库应用的每个线程都建立一个独立的连接，或基于线程建立连接池，以避免连接内的“USE statement”状态量在线程之间相互干扰（但连接的查询和写入操作都是线程安全的）。
## <a class="anchor" id="driver"></a>安装连接器驱动步骤
服务器应该已经安装TDengine服务端安装包。连接器驱动安装步骤如下：
服务器应该已经安装 TDengine 服务端安装包。连接器驱动安装步骤如下：
**Linux**
**1. 从[涛思官网](https://www.taosdata.com/cn/all-downloads/)下载<!-- REPLACE_OPEN_TO_ENTERPRISE__YOU_CAN_GET_CONNECTOR_DRIVER_FROM_TAOS -->：**
* X64硬件环境：TDengine-client-2.x.x.x-Linux-x64.tar.gz
* X64 硬件环境：TDengine-client-2.x.x.x-Linux-x64.tar.gz
* ARM64硬件环境：TDengine-client-2.x.x.x-Linux-aarch64.tar.gz
* ARM64 硬件环境：TDengine-client-2.x.x.x-Linux-aarch64.tar.gz
* ARM32硬件环境：TDengine-client-2.x.x.x-Linux-aarch32.tar.gz
* ARM32 硬件环境：TDengine-client-2.x.x.x-Linux-aarch32.tar.gz
**2. 解压缩软件包**
......@@ -62,11 +62,12 @@ TDengine提供了丰富的应用程序开发接口，其中包括C/C++、Java、
**4. 配置taos.cfg**
编辑taos.cfg文件(默认路径/etc/taos/taos.cfg)，将firstEP修改为TDengine服务器的End Point，例如：h1.taos.com:6030
编辑 taos.cfg 文件(默认路径/etc/taos/taos.cfg)，将 firstEP 修改为 TDengine 服务器的 End Point，例如：h1.taos.com:6030
**提示：**
1. **如本机没有部署TDengine服务，仅安装了应用驱动，则taos.cfg中仅需配置firstEP，无需配置FQDN。**
2. **为防止与服务器端连接时出现“unable to resolve FQDN”错误，建议确认客户端的hosts文件已经配置正确的FQDN值。**
1. **如本机没有部署 TDengine 服务，仅安装了应用驱动，则 taos.cfg 中仅需配置 firstEP，无需配置 FQDN。**
2. **为防止与服务器端连接时出现 “unable to resolve FQDN” 错误，建议确认客户端的 hosts 文件已经配置正确的 FQDN 值。**
**Windows x64/x86**
......@@ -93,20 +94,20 @@ TDengine提供了丰富的应用程序开发接口，其中包括C/C++、Java、
**4. 配置taos.cfg**
编辑taos.cfg文件(默认路径C:\TDengine\cfg\taos.cfg)，将firstEP修改为TDengine服务器的End Point，例如：h1.taos.com:6030
编辑 taos.cfg 文件(默认路径C:\TDengine\cfg\taos.cfg)，将 firstEP 修改为 TDengine 服务器的 End Point，例如：h1.taos.com:6030
**提示：**
1. **如利用FQDN连接服务器，必须确认本机网络环境DNS已配置好，或在hosts文件中添加FQDN寻址记录，如编辑C:\Windows\system32\drivers\etc\hosts，添加如下的记录：`192.168.1.99 h1.taos.com` **
1. **如利用 FQDN 连接服务器，必须确认本机网络环境DNS已配置好，或在 hosts 文件中添加 FQDN 寻址记录，如编辑C:\Windows\system32\drivers\etc\hosts，添加如下的记录：`192.168.1.99 h1.taos.com` **
2. **卸载：运行unins000.exe可卸载TDengine应用驱动。**
### 安装验证
以上安装和配置完成后，并确认TDengine服务已经正常启动运行，此时可以执行taos客户端进行登录。
以上安装和配置完成后，并确认 TDengine 服务已经正常启动运行，此时可以执行 taos 客户端进行登录。
**Linux环境：**
在Linux shell下直接执行 taos，应该就能正常连接到TDegine服务，进入到taos shell界面，示例如下：
在 Linux shell 下直接执行 taos，应该就能正常连接到 TDegine 服务，进入到 taos shell 界面，示例如下：
```mysql
$ taos
......@@ -123,7 +124,7 @@ taos>
**Windows（x64/x86）环境：**
在cmd下进入到c:\TDengine目录下直接执行 taos.exe，应该就能正常链接到tdegine服务，进入到taos shell界面，示例如下：
在 cmd 下进入到 C:\TDengine 目录下直接执行 taos.exe，应该就能正常链接到 TDengine 服务，进入到 taos shell 界面，示例如下：
```mysql
C:\TDengine>taos
......@@ -147,7 +148,7 @@ taos>
| **OS类型** | Linux | Win64 | Win32 | Linux | Linux |
| **支持与否** | **支持** | **支持** | **支持** | **支持** | **支持** |
C/C++的API类似于MySQL的C API。应用程序使用时，需要包含TDengine头文件 *taos.h*，里面列出了提供的API的函数原型。安装后，taos.h位于：
C/C++ 的 API 类似于 MySQL 的 C API。应用程序使用时，需要包含 TDengine 头文件 *taos.h*，里面列出了提供的 API 的函数原型。安装后，taos.h 位于：
- Linux：`/usr/local/taos/include`
- Windows：`C:\TDengine\include`
......@@ -158,35 +159,35 @@ C/C++的API类似于MySQL的C API。应用程序使用时，需要包含TDengine
注意：
* 在编译时需要链接TDengine动态库。Linux 为 *libtaos.so* ，安装后，位于 _/usr/local/taos/driver_。Windows为 taos.dll，安装后位于 *C:\TDengine*。
* 在编译时需要链接 TDengine 动态库。Linux 为 *libtaos.so* ，安装后，位于 _/usr/local/taos/driver_。Windows 为 taos.dll，安装后位于 *C:\TDengine*。
* 如未特别说明，当API的返回值是整数时，_0_ 代表成功，其它是代表失败原因的错误码，当返回值是指针时， _NULL_ 表示失败。
* 在 taoserror.h中有所有的错误码，以及对应的原因描述。`tstrerror(errno)` 可以获取错误码对应的错误信息。
* 在 taoserror.h 中有所有的错误码，以及对应的原因描述。`tstrerror(errno)` 可以获取错误码对应的错误信息。
### 示例程序
使用C/C++连接器的示例代码请参见 https://github.com/taosdata/TDengine/tree/develop/examples/c 。
使用 C/C++ 连接器的示例代码请参见 `https://github.com/taosdata/TDengine/tree/develop/examples/c`。
示例程序源码也可以在安装目录下的 examples/c 路径下找到：
示例程序源码也可以在安装目录下的 `examples/c` 路径下找到：
**apitest.c、asyncdemo.c、demo.c、prepare.c、stream.c、subscribe.c**
该目录下有makefile，在Linux环境下，直接执行make就可以编译得到执行文件。
该目录下有 makefile，在 Linux 环境下，直接执行 `make` 就可以编译得到执行文件。
在一台机器上启动TDengine服务，执行这些示例程序，按照提示输入TDengine服务的FQDN，就可以正常运行，并打印出信息。
在一台机器上启动 TDengine 服务，执行这些示例程序，按照提示输入 TDengine 服务的 FQDN，就可以正常运行，并打印出信息。
**提示：**在ARM环境下编译时，请将makefile中的-msse4.2打开，这个选项只有在x64/x86硬件平台上才能支持。
**提示：**在 ARM 环境下编译时，请将 makefile 中的 `-msse4.2` 打开，这个选项只有在 x64/x86 硬件平台上才能支持。
### 基础API
基础API用于完成创建数据库连接等工作，为其它API的执行提供运行时环境。
基础 API 用于完成创建数据库连接等工作，为其它 API 的执行提供运行时环境。
- `void taos_init()`
初始化运行环境。如果应用没有主动调用该API，那么应用在调用`taos_connect`时将自动调用，故应用程序一般无需手动调用该API。
初始化运行环境。如果应用没有主动调用该 API，那么应用在调用 `taos_connect()` 时将自动调用，故应用程序一般无需手动调用该 API。
- `void taos_cleanup()`
清理运行环境，应用退出前应调用此API。
清理运行环境，应用退出前应调用此 API。
- `int taos_options(TSDB_OPTION option, const void * arg, ...)`
......@@ -202,15 +203,15 @@ C/C++的API类似于MySQL的C API。应用程序使用时，需要包含TDengine
创建数据库连接，初始化连接上下文。其中需要用户提供的参数包含：
- host：TDengine管理主节点的FQDN
- host：TDengine 管理主节点的 FQDN
- user：用户名
- pass：密码
- db：数据库名字，如果用户没有提供，也可以正常连接，用户可以通过该连接创建新的数据库，如果用户提供了数据库名字，则说明该数据库用户已经创建好，缺省使用该数据库
- port：TDengine管理主节点的端口号
- port：TDengine 管理主节点的端口号
返回值为空表示失败。应用程序需要保存返回的参数，以便后续API调用。
返回值为空表示失败。应用程序需要保存返回的参数，以便后续 API 调用。
**提示:** 同一进程可以根据不同的host/port 连接多个taosd 集群
**提示:** 同一进程可以根据不同的 host/port 连接多个 taosd 集群
- `char *taos_get_server_info(TAOS *taos)`
......@@ -228,11 +229,11 @@ C/C++的API类似于MySQL的C API。应用程序使用时，需要包含TDengine
### 同步查询API
传统的数据库操作API，都属于同步操作。应用调用API后，一直处于阻塞状态，直到服务器返回结果。TDengine支持如下API：
传统的数据库操作 API，都属于同步操作。应用调用 API 后，一直处于阻塞状态，直到服务器返回结果。TDengine 支持如下 API：
- `TAOS_RES* taos_query(TAOS *taos, const char *sql)`
该API用来执行SQL语句，可以是DQL、DML或DDL语句。 其中的`taos`参数是通过`taos_connect`获得的指针。不能通过返回值是否是 NULL 来判断执行结果是否失败，而是需要用`taos_errno`函数解析结果集中的错误代码来进行判断。
该API用来执行 SQL 语句，可以是 DQL、DML 或 DDL 语句。 其中的 `taos` 参数是通过 `taos_connect` 获得的指针。不能通过返回值是否是 NULL 来判断执行结果是否失败，而是需要用 `taos_errno` 函数解析结果集中的错误代码来进行判断。
- `int taos_result_precision(TAOS_RES *res)`
......@@ -260,7 +261,7 @@ C/C++的API类似于MySQL的C API。应用程序使用时，需要包含TDengine
- `TAOS_FIELD *taos_fetch_fields(TAOS_RES *res)`
获取查询结果集每列数据的属性（列的名称、列的数据类型、列的长度），与taos_num_fileds配合使用，可用来解析`taos_fetch_row`返回的一个元组(一行)的数据。 `TAOS_FIELD` 的结构如下：
获取查询结果集每列数据的属性（列的名称、列的数据类型、列的长度），与 taos_num_fileds 配合使用，可用来解析 `taos_fetch_row` 返回的一个元组(一行)的数据。 `TAOS_FIELD` 的结构如下：
```c
typedef struct taosField {
......@@ -276,7 +277,7 @@ typedef struct taosField {
- `void taos_free_result(TAOS_RES *res)`
释放查询结果集以及相关的资源。查询完成后，务必调用该API释放资源，否则可能导致应用内存泄露。但也需注意，释放资源后，如果再调用`taos_consume`等获取查询结果的函数，将导致应用Crash。
释放查询结果集以及相关的资源。查询完成后，务必调用该 API 释放资源，否则可能导致应用内存泄露。但也需注意，释放资源后，如果再调用 `taos_consume` 等获取查询结果的函数，将导致应用 Crash。
- `char *taos_errstr(TAOS_RES *res)`
......@@ -290,11 +291,11 @@ typedef struct taosField {
### 异步查询API
同步API之外，TDengine还提供性能更高的异步调用API处理数据插入、查询操作。在软硬件环境相同的情况下，异步API处理数据插入的速度比同步API快2～4倍。异步API采用非阻塞式的调用方式，在系统真正完成某个具体数据库操作前，立即返回。调用的线程可以去处理其他工作，从而可以提升整个应用的性能。异步API在网络延迟严重的情况下，优点尤为突出。
同步 API 之外，TDengine 还提供性能更高的异步调用API处理数据插入、查询操作。在软硬件环境相同的情况下，异步 API 处理数据插入的速度比同步API快2～4倍。异步 API 采用非阻塞式的调用方式，在系统真正完成某个具体数据库操作前，立即返回。调用的线程可以去处理其他工作，从而可以提升整个应用的性能。异步 API 在网络延迟严重的情况下，优点尤为突出。
异步API都需要应用提供相应的回调函数，回调函数参数设置如下：前两个参数都是一致的，第三个参数依不同的API而定。第一个参数param是应用调用异步API时提供给系统的，用于回调时，应用能够找回具体操作的上下文，依具体实现而定。第二个参数是SQL操作的结果集，如果为空，比如insert操作，表示没有记录返回，如果不为空，比如select操作，表示有记录返回。
异步 API 都需要应用提供相应的回调函数，回调函数参数设置如下：前两个参数都是一致的，第三个参数依不同的 API 而定。第一个参数 `param` 是应用调用异步API时提供给系统的，用于回调时，应用能够找回具体操作的上下文，依具体实现而定。第二个参数是 `sql` 操作的结果集，如果为空，比如 insert 操作，表示没有记录返回，如果不为空，比如 select 操作，表示有记录返回。
异步API对于使用者的要求相对较高，用户可根据具体应用场景选择性使用。下面是两个重要的异步API：
异步 API 对于使用者的要求相对较高，用户可根据具体应用场景选择性使用。下面是两个重要的异步 API：
- `void taos_query_a(TAOS *taos, const char *sql, void (*fp)(void *param, TAOS_RES *, int code), void *param);`
......@@ -312,7 +313,7 @@ typedef struct taosField {
* res：`taos_query_a`回调时返回的结果集
* fp：回调函数。其参数`param`是用户可定义的传递给回调函数的参数结构体；`numOfRows`是获取到的数据的行数（不是整个查询结果集的函数）。 在回调函数中，应用可以通过调用`taos_fetch_row`前向迭代获取批量记录中每一行记录。读完一块内的所有记录后，应用需要在回调函数中继续调用`taos_fetch_rows_a`获取下一批记录进行处理，直到返回的记录数（numOfRows）为零（结果返回完成）或记录数为负值（查询出错）。
TDengine的异步API均采用非阻塞调用模式。应用程序可以用多线程同时打开多张表，并可以同时对每张打开的表进行查询或者插入操作。需要指出的是，**客户端应用必须确保对同一张表的操作完全串行化**，即对同一个表的插入或查询操作未完成时（未返回时），不能够执行第二个插入或查询操作。
TDengine 的异步 API 均采用非阻塞调用模式。应用程序可以用多线程同时打开多张表，并可以同时对每张打开的表进行查询或者插入操作。需要指出的是，**客户端应用必须确保对同一张表的操作完全串行化**，即对同一个表的插入或查询操作未完成时（未返回时），不能够执行第二个插入或查询操作。
<a class="anchor" id="stmt"></a>
### 参数绑定 API
......@@ -320,6 +321,7 @@ TDengine的异步API均采用非阻塞调用模式。应用程序可以用多线
除了直接调用 `taos_query` 进行查询，TDengine 也提供了支持参数绑定的 Prepare API，与 MySQL 一样，这些 API 目前也仅支持用问号 `?` 来代表待绑定的参数。文档中有时也会把此功能称为“原生接口写入”。
从 2.1.1.0 和 2.1.2.0 版本开始，TDengine 大幅改进了参数绑定接口对数据写入（INSERT）场景的支持。这样在通过参数绑定接口写入数据时，就避免了 SQL 语法解析的资源消耗，从而在绝大多数情况下显著提升写入性能。此时的典型操作步骤如下：
1. 调用 `taos_stmt_init` 创建参数绑定对象；
2. 调用 `taos_stmt_prepare` 解析 INSERT 语句；
3. 如果 INSERT 语句中预留了表名但没有预留 TAGS，那么调用 `taos_stmt_set_tbname` 来设置表名；
......@@ -416,10 +418,10 @@ typedef struct TAOS_MULTI_BIND {
- `TAOS_RES* taos_schemaless_insert(TAOS* taos, const char* lines[], int numLines, int protocol, int precision)`
**功能说明**
该接口将行协议的文本数据写入到TDengine中。
该接口将行协议的文本数据写入到 TDengine 中。
**参数说明**
taos: 数据库连接，通过taos_connect 函数建立的数据库连接。
taos: 数据库连接，通过 taos_connect 函数建立的数据库连接。
lines：文本数据。满足解析格式要求的无模式文本字符串。
numLines:文本数据的行数，不能为 0 。
protocol: 行协议类型，用于标识文本数据格式。
......@@ -450,7 +452,7 @@ typedef struct TAOS_MULTI_BIND {
**支持版本**
该功能接口从2.3.0.0版本开始支持。
```c
#include <stdlib.h>
#include <stdio.h>
......@@ -486,11 +488,11 @@ int main() {
### 连续查询接口
TDengine提供时间驱动的实时流式计算API。可以每隔一指定的时间段，对一张或多张数据库的表(数据流)进行各种实时聚合计算操作。操作简单，仅有打开、关闭流的API。具体如下：
TDengine 提供时间驱动的实时流式计算 API。可以每隔一指定的时间段，对一张或多张数据库的表(数据流)进行各种实时聚合计算操作。操作简单，仅有打开、关闭流的 API。具体如下：
- `TAOS_STREAM *taos_open_stream(TAOS *taos, const char *sql, void (*fp)(void *param, TAOS_RES *, TAOS_ROW row), int64_t stime, void *param, void (*callback)(void *))`
该API用来创建数据流，其中：
该 API 用来创建数据流，其中：
* taos：已经建立好的数据库连接。
* sql：SQL查询语句（仅能使用查询语句）。
* fp：用户定义的回调函数指针，每次流式计算完成后，TDengine将查询的结果（TAOS_ROW）、查询状态（TAOS_RES）、用户定义参数（PARAM）传递给回调函数，在回调函数内，用户可以使用taos_num_fields获取结果集列数，taos_fetch_fields获取结果集每列数据的类型。
......@@ -498,15 +500,15 @@ TDengine提供时间驱动的实时流式计算API。可以每隔一指定的时
* param：是应用提供的用于回调的一个参数，回调时，提供给应用。
* callback: 第二个回调函数，会在连续查询自动停止时被调用。
返回值为NULL，表示创建失败；返回值不为空，表示成功。
返回值为 NULL，表示创建失败；返回值不为空，表示成功。
- `void taos_close_stream (TAOS_STREAM *tstr)`
关闭数据流，其中提供的参数是taos_open_stream的返回值。用户停止流式计算的时候，务必关闭该数据流。
关闭数据流，其中提供的参数是 taos_open_stream 的返回值。用户停止流式计算的时候，务必关闭该数据流。
### 数据订阅接口
订阅API目前支持订阅一张或多张表，并通过定期轮询的方式不断获取写入表中的最新数据。
订阅 API 目前支持订阅一张或多张表，并通过定期轮询的方式不断获取写入表中的最新数据。
* `TAOS_SUB *taos_subscribe(TAOS* taos, int restart, const char* topic, const char *sql, TAOS_SUBSCRIBE_CALLBACK fp, void *param, int interval)`
......@@ -517,46 +519,46 @@ TDengine提供时间驱动的实时流式计算API。可以每隔一指定的时
* sql：订阅的查询语句，此语句只能是 `select` 语句，只应查询原始数据，只能按时间正序查询数据
* fp：收到查询结果时的回调函数（稍后介绍函数原型），只在异步调用时使用，同步调用时此参数应该传 `NULL`
* param：调用回调函数时的附加参数，系统API将其原样传递到回调函数，不进行任何处理
* interval：轮询周期，单位为毫秒。异步调用时，将根据此参数周期性的调用回调函数，为避免对系统性能造成影响，不建议将此参数设置的过小；同步调用时，如两次调用`taos_consume`的间隔小于此周期，API将会阻塞，直到时间间隔超过此周期。
* interval：轮询周期，单位为毫秒。异步调用时，将根据此参数周期性的调用回调函数，为避免对系统性能造成影响，不建议将此参数设置的过小；同步调用时，如两次调用 `taos_consume` 的间隔小于此周期，API将会阻塞，直到时间间隔超过此周期。
* `typedef void (*TAOS_SUBSCRIBE_CALLBACK)(TAOS_SUB* tsub, TAOS_RES *res, void* param, int code)`
异步模式下，回调函数的原型，其参数为：
* tsub：订阅对象
* res：查询结果集，注意结果集中可能没有记录
* param：调用 `taos_subscribe`时客户程序提供的附加参数
* param：调用 `taos_subscribe` 时客户程序提供的附加参数
* code：错误码
**注意**：在这个回调函数里不可以做耗时过长的处理，尤其是对于返回的结果集中数据较多的情况，否则有可能导致客户端阻塞等异常状态。如果必须进行复杂计算，则建议在另外的线程中进行处理。
* `TAOS_RES *taos_consume(TAOS_SUB *tsub)`
同步模式下，该函数用来获取订阅的结果。 用户应用程序将其置于一个循环之中。 如两次调用`taos_consume`的间隔小于订阅的轮询周期，API将会阻塞，直到时间间隔超过此周期。 如果数据库有新记录到达，该API将返回该最新的记录，否则返回一个没有记录的空结果集。 如果返回值为 `NULL`，说明系统出错。 异步模式下，用户程序不应调用此API。
同步模式下，该函数用来获取订阅的结果。 用户应用程序将其置于一个循环之中。 如两次调用 `taos_consume()` 的间隔小于订阅的轮询周期，API将会阻塞，直到时间间隔超过此周期。 如果数据库有新记录到达，该API将返回该最新的记录，否则返回一个没有记录的空结果集。 如果返回值为 `NULL`，说明系统出错。 异步模式下，用户程序不应调用此 API。
**注意**：在调用 `taos_consume()` 之后，用户应用应确保尽快调用 `taos_fetch_row()` 或 `taos_fetch_block()` 来处理订阅结果，否则服务端会持续缓存查询结果数据等待客户端读取，极端情况下会导致服务端内存消耗殆尽，影响服务稳定性。
* `void taos_unsubscribe(TAOS_SUB *tsub, int keepProgress)`
取消订阅。 如参数 `keepProgress` 不为0，API会保留订阅的进度信息，后续调用 `taos_subscribe` 时可以基于此进度继续；否则将删除进度信息，后续只能重新开始读取数据。
取消订阅。 如参数 `keepProgress` 不为0，API会保留订阅的进度信息，后续调用 `taos_subscribe()` 时可以基于此进度继续；否则将删除进度信息，后续只能重新开始读取数据。
<!-- REPLACE_OPEN_TO_ENTERPRISE__JAVA_CONNECTOR_DOC -->
## <a class="anchor" id="python"></a>Python Connector
Python连接器的使用参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1963.html)
Python 连接器的使用参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1963.html)
* **安装**：参见下面具体步骤
* **示例程序**：位于install_directory/examples/python
* **示例程序**：位于 install_directory/examples/python
### 安装
Python连接器支持的系统有：Linux 64/Windows x64
Python 连接器支持的系统有：Linux 64/Windows x64
安装前准备：
- 已安装好TDengine应用驱动，请参考[安装连接器驱动步骤](https://www.taosdata.com/cn/documentation/connector#driver)
- 已安装python 2.7 or >= 3.4
- 已安装pip
- 已安装好 TDengine 应用驱动，请参考[安装连接器驱动步骤](https://www.taosdata.com/cn/documentation/connector#driver)
- 已安装 Python 2.7 or >= 3.4
- 已安装 pip
### Python连接器安装
......@@ -583,19 +585,19 @@ Python 命令行依赖 taos 动态库 `libtaos.so` 或 `taos.dll`, 对于 Window
* **read_example.py** Python示例源程序
用户可以参考`read_example.py`这个程序来设计用户自己的写入、查询程序。
用户可以参考 `read_example.py` 这个程序来设计用户自己的写入、查询程序。
在安装了对应的应用驱动后，通过`import taos`引入taos类。主要步骤如下：
在安装了对应的应用驱动后，通过 `import taos` 引入 taos 类。主要步骤如下：
- 通过taos.connect获取TaosConnection对象，这个对象可以一个程序只申请一个，在多线程中共享。
- 通过 taos.connect 获取 TaosConnection对象，这个对象可以一个程序只申请一个，在多线程中共享。
- 通过TaosConnection对象的 `.cursor()` 方法获取一个新的游标对象，这个游标对象必须保证每个线程独享。
- 通过 TaosConnection 对象的 `.cursor()` 方法获取一个新的游标对象，这个游标对象必须保证每个线程独享。
- 通过游标对象的execute()方法，执行写入或查询的SQL语句。
- 通过游标对象的 execute()方法，执行写入或查询的 SQL 语句。
- 如果执行的是写入语句，execute返回的是成功写入的行数信息affected rows。
- 如果执行的是写入语句，execute 返回的是成功写入的行数信息 affected rows。
- 如果执行的是查询语句，则execute执行成功后，需要通过fetchall方法去拉取结果集。 具体方法可以参考示例代码。
- 如果执行的是查询语句，则 execute 执行成功后，需要通过 fetchall 方法去拉取结果集。 具体方法可以参考示例代码。
### 安装验证
......@@ -608,11 +610,11 @@ python3 PythonChecker.py -host <fqdn>
验证通过将打印出成功信息。
### Python连接器的使用
### Python 连接器的使用
#### PEP-249 兼容API
#### PEP-249 兼容 API
您可以像其他数据库一样，使用类似 [PEP-249](https://www.python.org/dev/peps/pep-0249/) 数据库API规范风格的API：
您可以像其他数据库一样，使用类似 [PEP-249](https://www.python.org/dev/peps/pep-0249/) 数据库 API 规范风格的 API：
```python
import taos
......@@ -628,7 +630,7 @@ for row in results:
##### 代码示例
1. 导入TDengine客户端模块
1. 导入 TDengine 客户端模块
```python
import taos
......@@ -641,7 +643,7 @@ for row in results:
c1 = conn.cursor()
```
*host* 是TDengine 服务端所在IP, *config* 为客户端配置文件所在目录。
*host* 是 TDengine 服务端所在IP, *config* 为客户端配置文件所在目录。
3. 写入数据
......@@ -685,7 +687,7 @@ for row in results:
#### Query API
从v2.1.0版本开始, 我们提供另外一种方法：`connection.query` 来操作数据库。
从 v2.1.0 版本开始, 我们提供另外一种方法：`connection.query` 来操作数据库。
```python
import taos
......@@ -755,7 +757,7 @@ conn.execute("drop database pytest")
#### JSON 类型
从 `taospy` `v2.2.0` 开始，Python连接器开始支持 JSON 数据类型的标签（TDengine版本要求 Beta 版 2.3.5+， 稳定版 2.4.0+）。
从 `taospy` `v2.2.0` 开始，Python 连接器开始支持 JSON 数据类型的标签（TDengine版本要求 Beta 版 2.3.5+， 稳定版 2.4.0+）。
创建一个使用JSON类型标签的超级表及其子表：
......@@ -794,33 +796,32 @@ k1 = conn.query("select info->'k1' as k1 from s1").fetch_all_into_dict()
"""
```
更多JSON类型的操作方式请参考 [JSON 类型使用说明](https://www.taosdata.com/cn/documentation/taos-sql)。
更多 JSON 类型的操作方式请参考 [JSON 类型使用说明](https://www.taosdata.com/cn/documentation/taos-sql)。
#### 关于纳秒 (nanosecond) 在 Python 连接器中的说明
由于目前 Python 对 nanosecond 支持的不完善(参见链接 1. 2. )，目前的实现方式是在 nanosecond 精度时返回整数，而不是 ms 和 us 返回的 datetime 类型，应用开发者需要自行处理，建议使用 pandas 的 to_datetime()。未来如果 Python 正式完整支持了纳秒，涛思数据可能会修改相关接口。
1. https://stackoverflow.com/questions/10611328/parsing-datetime-strings-containing-nanoseconds
2. https://www.python.org/dev/peps/pep-0564/
1. `https://stackoverflow.com/questions/10611328/parsing-datetime-strings-containing-nanoseconds`
2. `https://www.python.org/dev/peps/pep-0564/`
#### 帮助信息
用户可通过python的帮助信息直接查看模块的使用信息，或者参考tests/examples/python中的示例程序。以下为部分常用类和方法：
用户可通过 Python 的帮助信息直接查看模块的使用信息，或者参考 `examples/python` 目录中的示例程序。以下为部分常用类和方法：
- _TaosConnection_ 类
参考python中help(taos.TaosConnection)。
这个类对应客户端和TDengine建立的一个连接。在客户端多线程的场景下，推荐每个线程申请一个独立的连接实例，而不建议多线程共享一个连接。
参考 Python 中 help(taos.TaosConnection)。
这个类对应客户端和 TDengine 建立的一个连接。在客户端多线程的场景下，推荐每个线程申请一个独立的连接实例，而不建议多线程共享一个连接。
- _TaosCursor_ 类
参考python中help(taos.TaosCursor)。
参考 Python 中 help(taos.TaosCursor)。
这个类对应客户端进行的写入、查询操作。在客户端多线程的场景下，这个游标实例必须保持线程独享，不能跨线程共享使用，否则会导致返回结果出现错误。
- _connect_ 方法
用于生成taos.TaosConnection的实例。
用于生成 taos.TaosConnection 的实例。
## <a class="anchor" id="restful"></a>RESTful Connector
......@@ -839,11 +840,13 @@ RESTful 接口不依赖于任何 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",
......@@ -869,7 +872,7 @@ http://<fqdn>:<port>/rest/sql/[db_name]
- port: 配置文件中 httpPort 配置项，缺省为 6041
- db_name: 可选参数，指定本次所执行的 SQL 语句的默认数据库库名。（从 2.2.0.0 版本开始支持）
例如：http://h1.taos.com:6041/rest/sql/test 是指向地址为 h1.taos.com:6041 的 url，并将默认使用的数据库库名设置为 test。
例如：`http://h1.taos.com:6041/rest/sql/test` 是指向地址为 `h1.taos.com:6041` 的 url，并将默认使用的数据库库名设置为 test。
HTTP 请求的 Header 里需带有身份认证信息，TDengine 支持 Basic 认证与自定义认证两种机制，后续版本将提供标准安全的数字签名机制来做身份验证。
......@@ -927,6 +930,7 @@ curl -u username:password -d '<SQL>' <ip>:<PORT>/rest/sql/[db_name]
- rows: 表明总共多少行数据。
<a class="anchor" id="column_meta"></a>column_meta 中的列类型说明：
* 1：BOOL
* 2：TINYINT
* 3：SMALLINT
......@@ -977,6 +981,7 @@ curl http://192.168.0.1:6041/rest/login/root/taosdata
```bash
curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001' 192.168.0.1:6041/rest/sql
```
返回值：
```json
......@@ -999,6 +1004,7 @@ curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'create database demo' 19
```
返回值：
```json
{
"status": "succ",
......@@ -1037,6 +1043,7 @@ curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001
#### 结果集采用 UTC 时间字符串
HTTP 请求 URL 采用 `sqlutc` 时，返回结果集的时间戳将采用 UTC 时间字符串表示，例如
```bash
curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.t1' 192.168.0.1:6041/rest/sqlutc
```
......@@ -1069,28 +1076,31 @@ HTTP 请求 URL 采用 `sqlutc` 时，返回结果集的时间戳将采用 UTC
## <a class="anchor" id="csharp"></a>CSharp Connector
* C#连接器支持的系统有：Linux 64/Windows x64/Windows x86
* C# 连接器支持的系统有：Linux 64/Windows x64/Windows x86
* C# 连接器现在也支持从[Nuget下载引用](https://www.nuget.org/packages/TDengine.Connector/)
* C#连接器现在也支持从[Nuget下载引用](https://www.nuget.org/packages/TDengine.Connector/)
* 在 Windows 系统上，C# 应用程序可以使用 TDengine 的原生 C 接口来执行所有数据库操作，后续版本将提供 ORM（Dapper）框架驱动。
* 在Windows系统上，C#应用程序可以使用TDengine的原生C接口来执行所有数据库操作，后续版本将提供ORM（Dapper）框架驱动。
### 安装准备
* 应用驱动安装请参考[安装连接器驱动步骤](https://www.taosdata.com/cn/documentation/connector#driver)。
* 接口文件TDengineDrivercs.cs和参考程序示例TDengineTest.cs均位于Windows客户端install_directory/examples/C#目录下。
* 接口文件 TDengineDrivercs.cs 和参考程序示例 TDengineTest.cs 均位于 Windows 客户端 install_directory/examples/C#目录下。
* 安装[.NET SDK](https://dotnet.microsoft.com/download)
### 示例程序
示例程序源码位于
* {client_install_directory}/examples/C#
* [github C# example source code](https://github.com/taosdata/TDengine/tree/develop/examples/C%2523)
**注意:** TDengineTest.cs C#示例源程序,包含了数据库连接参数，以及如何执行数据插入、查询等操作。
**注意:** TDengineTest.cs C# 示例源程序，包含了数据库连接参数，以及如何执行数据插入、查询等操作。
### 安装验证
需要先安装 .Net SDK
```cmd
cd {client_install_directory}/examples/C#/C#Checker
//运行测试
......@@ -1099,36 +1109,39 @@ dotnet run -- -h <FQDN>. // 此步骤会先build，然后再运行。
### C#连接器的使用
在Windows系统上，C#应用程序可以使用TDengine的C#连接器接口来执行所有数据库的操作。使用的具体步骤如下所示：
在 Windows 系统上，C# 应用程序可以使用 TDengine 的 C# 连接器接口来执行所有数据库的操作。使用的具体步骤如下所示：
* 创建一个 C# project（需要 .NET SDK）.
需要 .NET SDK
* 创建一个c# project.
``` cmd
mkdir test
cd test
dotnet new console
```
* 通过Nuget引用TDengineDriver包
* 通过 Nuget 引用 TDengineDriver 包
``` cmd
dotnet add package TDengine.Connector
```
* 在项目中需要用到TDengineConnector的地方引用TDengineDriver namespace。
```c#
* 在项目中需要用到 TDengineConnector 的地方引用 TDengineDriver namespace。
```C#
using TDengineDriver;
```
* 用户可以参考[TDengineTest.cs](https://github.com/taosdata/TDengine/tree/develop/examples/C%2523/TDengineTest)来定义数据库连接参数，以及如何执行数据插入、查询等操作。
* 用户可以参考[TDengineTest.cs](https://github.com/taosdata/TDengine/tree/develop/examples/C%2523/TDengineTest)来定义数据库连接参数，以及如何执行数据插入、查询等操作。
**注意：**
* TDengine V2.0.3.0之后同时支持32位和64位Windows系统，所以C#项目在生成.exe文件时，“解决方案”/“项目”的“平台”请选择对应的“X86” 或“x64”。
* 此接口目前已经在Visual Studio 2015/2017中验证过，其它VS版本尚待验证。
* 此连接器需要用到taos.dll文件，所以在未安装客户端时需要在执行应用程序前，拷贝Windows{client_install_directory}/driver目录中的taos.dll文件到项目最后生成.exe可执行文件所在的文件夹。之后运行exe文件，即可访问TDengine数据库并做插入、查询等操作。
* TDengine V2.0.3.0 之后同时支持 32 位和 64 位 Windows 系统，所以 C# 项目在生成 .exe 文件时，“解决方案”/“项目”的“平台”请选择对应的 x86 或 x64。
* 此接口目前已经在 Visual Studio 2015/2017 中验证过，其它 Visual Studio 版本尚待验证。
* 此连接器需要用到 taos.dll 文件，所以在未安装客户端时需要在执行应用程序前，拷贝 Windows{client_install_directory}/driver 目录中的 taos.dll 文件到项目最后生成 .exe 可执行文件所在的文件夹。之后运行 exe 文件，即可访问 TDengine 数据库并做插入、查询等操作。
### 第三方驱动
Maikebing.Data.Taos是一个TDengine的ADO.Net提供器，支持linux，windows。该开发包由热心贡献者`麦壳饼@@maikebing`提供，具体请参考
Maikebing.Data.Taos 是一个 TDengine 的 ADO.Net 提供器，支持 linux，windows。该开发包由热心贡献者`麦壳饼@@maikebing`提供，具体请参考
```
//接口下载
......@@ -1141,7 +1154,7 @@ https://www.taosdata.com/blog/2020/11/02/1901.html
### 安装准备
Go连接器支持的系统有：
Go 连接器支持的系统有：
| **CPU类型** | x64（64bit） | | | aarch64 | aarch32 |
| --------------- | ------------ | -------- | -------- | -------- | ---------- |
......@@ -1150,20 +1163,23 @@ Go连接器支持的系统有：
安装前准备：
- 已安装好TDengine应用驱动，参考[安装连接器驱动步骤](https://www.taosdata.com/cn/documentation/connector#driver)。
- 已安装好 TDengine 应用驱动，参考[安装连接器驱动步骤](https://www.taosdata.com/cn/documentation/connector#driver)。
### 示例程序
使用 Go 连接器的示例代码请参考 https://github.com/taosdata/TDengine/tree/develop/examples/go 以及[视频教程](https://www.taosdata.com/blog/2020/11/11/1951.html)。
使用 Go 连接器的示例代码请参考 `https://github.com/taosdata/TDengine/tree/develop/examples/go` 以及[视频教程](https://www.taosdata.com/blog/2020/11/11/1951.html)。
示例程序源码也位于安装目录下的 examples/go/taosdemo.go 文件中。
**提示：建议Go版本是1.13及以上，并开启模块支持：**
**提示：建议 Go 版本是 1.13 及以上，并开启模块支持：**
```sh
go env -w GO111MODULE=on
go env -w GOPROXY=https://goproxy.io,direct
```
在taosdemo.go所在目录下进行编译和执行：
在 taosdemo.go 所在目录下进行编译和执行：
```sh
go mod init taosdemo
go get github.com/taosdata/driver-go/taosSql
......@@ -1173,9 +1189,10 @@ go build
./taosdemo -h fqdn -p serverPort
```
### Go连接器的使用
### Go 连接器的使用
TDengine 提供了GO驱动程序包`taosSql`。`taosSql` 实现了 GO 语言的内置接口 `database/sql/driver`。用户只需按如下方式引入包就可以在应用程序中访问 TDengine。
TDengine提供了GO驱动程序包`taosSql`。`taosSql`实现了GO语言的内置接口`database/sql/driver`。用户只需按如下方式引入包就可以在应用程序中访问TDengine。
```go
import (
"database/sql"
......@@ -1185,47 +1202,48 @@ import (
**提示**：下划线与双引号之间必须有一个空格。
`taosSql` 的 v2 版本进行了重构，分离出内置数据库操作接口 `database/sql/driver` 到目录 `taosSql`；订阅、stmt等其他功能放到目录 `af`。
`taosSql` 的 v2 版本进行了重构，分离出内置数据库操作接口 `database/sql/driver` 到目录 `taosSql`；订阅、 stmt 等其他功能放到目录 `af`。
### 常用API
### 常用 API
- `sql.Open(DRIVER_NAME string, dataSourceName string) *DB`
该API用来打开DB，返回一个类型为\*DB的对象，一般情况下，DRIVER_NAME设置为字符串`taosSql`，dataSourceName设置为字符串`user:password@/tcp(host:port)/dbname`，如果客户想要用多个goroutine并发访问TDengine, 那么需要在各个goroutine中分别创建一个sql.Open对象并用之访问TDengine
该 API 用来打开 DB，返回一个类型为\*DB的对象，一般情况下，DRIVER_NAME设置为字符串 `taosSql`，dataSourceName 设置为字符串 `user:password@/tcp(host:port)/dbname`，如果客户想要用多个 goroutine 并发访问 TDengine, 那么需要在各个 goroutine 中分别创建一个 sql.Open 对象并用之访问 TDengine。
**注意**： 该API成功创建的时候，并没有做权限等检查，只有在真正执行Query或者Exec的时候才能真正的去创建连接，并同时检查user/password/host/port是不是合法。另外，由于整个驱动程序大部分实现都下沉到taosSql所依赖的libtaos动态库中。所以，sql.Open本身特别轻量。
**注意**： 该 API 成功创建的时候，并没有做权限等检查，只有在真正执行 Query 或者 Exec 的时候才能真正的去创建连接，并同时检查 user/password/host/port 是不是合法。另外，由于整个驱动程序大部分实现都下沉到 taosSql 所依赖的 libtaos 动态库中。所以，sql.Open 本身特别轻量。
- `func (db *DB) Exec(query string, args ...interface{}) (Result, error)`
sql.Open内置的方法，用来执行非查询相关SQL
sql.Open 内置的方法，用来执行非查询相关 SQL
- `func (db *DB) Query(query string, args ...interface{}) (*Rows, error)`
sql.Open内置的方法，用来执行查询语句
sql.Open 内置的方法，用来执行查询语句
- `func (db *DB) Prepare(query string) (*Stmt, error)`
sql.Open内置的方法，Prepare creates a prepared statement for later queries or executions.
sql.Open 内置的方法，Prepare creates a prepared statement for later queries or executions.
- `func (s *Stmt) Exec(args ...interface{}) (Result, error)`
sql.Open内置的方法，executes a prepared statement with the given arguments and returns a Result summarizing the effect of the statement.
sql.Open 内置的方法，executes a prepared statement with the given arguments and returns a Result summarizing the effect of the statement.
- `func (s *Stmt) Query(args ...interface{}) (*Rows, error)`
sql.Open内置的方法，Query executes a prepared query statement with the given arguments and returns the query results as a \*Rows.
sql.Open 内置的方法，Query executes a prepared query statement with the given arguments and returns the query results as a \*Rows.
- `func (s *Stmt) Close() error`
sql.Open内置的方法，Close closes the statement.
sql.Open 内置的方法，Close closes the statement.
### 其他代码示例
[Consume Messages from Kafka](https://github.com/taosdata/go-demo-kafka) 是一个通过 Go 语言实现消费 Kafka 队列写入 TDengine 的示例程序，也可以作为通过 Go 连接 TDengine 的写法参考。
### Go RESTful的使用
#### 引入
```go restful
import (
"database/sql"
......@@ -1249,16 +1267,16 @@ import (
参数：
`disableCompression`是否接受压缩数据，默认为true不接受压缩数据，如果传输数据使用gzip压缩设置为false。
`disableCompression` 是否接受压缩数据，默认为 true 不接受压缩数据，如果传输数据使用 gzip 压缩设置为 false。
`readBufferSize` 读取数据的缓存区大小默认为 4K(4096)，当查询结果数据量多时可以适当调大该值。
`readBufferSize`读取数据的缓存区大小默认为4K(4096)，当查询结果数据量多时可以适当调大该值。
#### 使用限制
由于restful接口无状态所以`use db`语法不会生效，需要将db名称放到sql语句中，如：`create table if not exists tb1 (ts timestamp, a int)`改为`create table if not exists test.tb1 (ts timestamp, a int)`否则将报错`[0x217] Database not specified or available`。
也可以将db名称放到DSN中，将`root:taosdata@http(localhost:6041)/`改为`root:taosdata@http(localhost:6041)/test`，此方法在TDengine 2.4.0.5版本的taosAdapter开始支持。当指定的 db不存在时执行`create database`语句不会报错，而执行针对该db的其他查询或写入操作会报错。完整示例如下：
由于 RESTful 接口无状态所以 `use db` 语法不会生效，需要将 db 名称放到 SQL 语句中，如：`create table if not exists tb1 (ts timestamp, a int)`改为`create table if not exists test.tb1 (ts timestamp, a int)`否则将报错`[0x217] Database not specified or available`。
也可以将 db 名称放到 DSN 中，将 `root:taosdata@http(localhost:6041)/` 改为 `root:taosdata@http(localhost:6041)/test`，此方法在 TDengine 2.4.0.5 版本的 taosAdapter 开始支持。当指定的 db 不存在时执行 `create database` 语句不会报错，而执行针对该 db 的其他查询或写入操作会报错。完整示例如下：
```go restful demo
package main
......@@ -1306,47 +1324,47 @@ func main() {
}
}
```
#### 常见问题
- 无法找到包`github.com/taosdata/driver-go/v2/taosRestful`
将`go.mod`中require块对`github.com/taosdata/driver-go/v2`的引用改为`github.com/taosdata/driver-go/v2 develop`，之后执行`go mod tidy`。
将 `go.mod` 中 require 块对`github.com/taosdata/driver-go/v2`的引用改为`github.com/taosdata/driver-go/v2 develop`，之后执行 `go mod tidy`。
- stmt相关接口崩溃
- stmt 相关接口崩溃
restful不支持stmt相关接口，建议使用`db.Exec`和`db.Query`。
- 使用`use db`语句后执行其他语句报错`[0x217] Database not specified or available`
RESTful 不支持 stmt 相关接口，建议使用`db.Exec`和`db.Query`。
在restful接口中sql语句的执行无上下文关联，使用`use db`语句不会生效，解决办法见上方使用限制章节。
- 使用 `use db` 语句后执行其他语句报错 `[0x217] Database not specified or available`
- 使用taosSql不报错使用taosRestful报错`[0x217] Database not specified or available`
在 RESTful 接口中 SQL 语句的执行无上下文关联，使用 `use db` 语句不会生效，解决办法见上方使用限制章节。
因为restful 接口无状态，使用`use db`语句不会生效，解决办法见上方使用限制章节。
- 使用 taosSql 不报错使用 taosRestful 报错 `[0x217] Database not specified or available`
- 升级`github.com/taosdata/driver-go/v2/taosRestful`
因为 RESTful 接口无状态，使用 `use db` 语句不会生效，解决办法见上方使用限制章节。
将`go.mod`文件中对`github.com/taosdata/driver-go/v2`的引用改为`github.com/taosdata/driver-go/v2 develop`，之后执行`go mod tidy`。
- 升级 `github.com/taosdata/driver-go/v2/taosRestful`
- readBufferSize参数调大后无明显效果
将 `go.mod` 文件中对 `github.com/taosdata/driver-go/v2` 的引用改为 `github.com/taosdata/driver-go/v2 develop`，之后执行 `go mod tidy`。
readBufferSize调大后会减少获取结果时syscall的调用。如果查询结果的数据量不大，修改该参数不会带来明显提升，如果该参数修改过大，瓶颈会在解析json数据。如果需要优化查询速度，需要根据实际情况调整该值来达到查询效果最优。
- readBufferSize 参数调大后无明显效果
- disableCompression参数设置为false时查询效率降低
readBufferSize 调大后会减少获取结果时 syscall 的调用。如果查询结果的数据量不大，修改该参数不会带来明显提升，如果该参数修改过大，瓶颈会在解析 JSON 数据。如果需要优化查询速度，需要根据实际情况调整该值来达到查询效果最优。
当disableCompression参数设置为false时查询结果会gzip压缩后传输，拿到数据后要先进行gzip解压。
- disableCompression 参数设置为 false 时查询效率降低
当 disableCompression 参数设置为 false 时查询结果会 gzip 压缩后传输，拿到数据后要先进行 gzip 解压。
## <a class="anchor" id="nodejs"></a>Node.js Connector
## <a class="anchor" id="nodejs"></a> Node.js Connector
Node.js连接器支持的系统有：
Node.js 连接器支持的系统有：
|**CPU类型** | x64（64bit） | | | aarch64 | aarch32 |
| ------------ | ------------ | -------- | -------- | -------- | -------- |
| **OS类型** | Linux | Win64 | Win32 | Linux | Linux |
| **支持与否** | **支持** | **支持** | **支持** | **支持** | **支持** |
Node.js连接器的使用参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1957.html)。
Node.js 连接器的使用参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1957.html)。
### 安装准备
......@@ -1354,56 +1372,57 @@ Node.js连接器的使用参见[视频教程](https://www.taosdata.com/blog/2020
### 安装Node.js连接器
用户可以通过[npm](https://www.npmjs.com/)来进行安装，也可以通过源代码*src/connector/nodejs/* 来进行安装。具体安装步骤如下：
用户可以通过 [npm](https://www.npmjs.com/) 来进行安装，也可以通过源代码 *src/connector/nodejs/* 来进行安装。具体安装步骤如下：
首先，通过[npm](https://www.npmjs.com/)安装node.js 连接器。
首先，通过 [npm](https://www.npmjs.com/) 安装 Node.js 连接器。
```bash
npm install td2.0-connector
```
我们建议用户使用npm 安装node.js连接器。如果您没有安装npm，可以将*src/connector/nodejs/*拷贝到您的nodejs 项目目录下。
我们使用[node-gyp](https://github.com/nodejs/node-gyp)和TDengine服务端进行交互。安装node.js连接器之前，还需要根据具体操作系统来安装下文提到的一些依赖工具。
我们建议用户使用 npm 安装 Node.js 连接器。如果您没有安装 npm，可以将 *src/connector/nodejs/* 拷贝到您的 nodejs 项目目录下。
我们使用 [node-gyp](https://github.com/nodejs/node-gyp) 和 TDengine 服务端进行交互。安装 Node.js 连接器之前，还需要根据具体操作系统来安装下文提到的一些依赖工具。
### Linux
- `python` (建议`v2.7` , `v3.x.x` 目前还不支持)
- `node` 2.0.6支持v12.x和v10.x，2.0.5及更早版本支持v10.x版本，其他版本可能存在包兼容性的问题。
- `make`
- c语言编译器比如[GCC](https://gcc.gnu.org)
- C 语言编译器比如 [GCC](https://gcc.gnu.org)
### Windows
#### 安装方法1
使用微软的[windows-build-tools](https://github.com/felixrieseberg/windows-build-tools)在`cmd` 命令行界面执行`npm install --global --production windows-build-tools` 即可安装所有的必备工具。
使用微软的 [windows-build-tools](https://github.com/felixrieseberg/windows-build-tools) 在 `cmd` 命令行界面执行 `npm install --global --production windows-build-tools` 即可安装所有的必备工具。
#### 安装方法2
手动安装以下工具：
- 安装Visual Studio相关：[Visual Studio Build 工具](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools) 或者 [Visual Studio 2017 Community](https://visualstudio.microsoft.com/pl/thank-you-downloading-visual-studio/?sku=Community)
- 安装 Visual Studio 相关：[Visual Studio Build 工具](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools) 或者 [Visual Studio 2017 Community](https://visualstudio.microsoft.com/pl/thank-you-downloading-visual-studio/?sku=Community)
- 安装 [Python](https://www.python.org/downloads/) 2.7(`v3.x.x` 暂不支持) 并执行 `npm config set python python2.7`
- 进入`cmd`命令行界面，`npm config set msvs_version 2017`
如果以上步骤不能成功执行，可以参考微软的node.js用户手册[Microsoft's Node.js Guidelines for Windows](https://github.com/Microsoft/nodejs-guidelines/blob/master/windows-environment.md#compiling-native-addon-modules)。
如果以上步骤不能成功执行，可以参考微软的 Node.js 用户手册 [Microsoft's Node.js Guidelines for Windows](https://github.com/Microsoft/nodejs-guidelines/blob/master/windows-environment.md#compiling-native-addon-modules)。
如果在Windows 10 ARM 上使用ARM64 Node.js，还需添加 "Visual C++ compilers and libraries for ARM64" 和 "Visual C++ ATL for ARM64"。
如果在 Windows 10 ARM 上使用 ARM64 Node.js，还需添加 "Visual C++ compilers and libraries for ARM64" 和 "Visual C++ ATL for ARM64"。
### 示例程序
示例程序源码位于install_directory/examples/nodejs，有：
示例程序源码位于 install_directory/examples/nodejs，有：
Node-example.js node.js示例源程序
Node-example.js Node.js示例源程序
Node-example-raw.js
### 安装验证
在安装好TDengine客户端后，使用nodejsChecker.js程序能够验证当前环境是否支持nodejs方式访问Tdengine。
在安装好 TDengine 客户端后，使用 nodejsChecker.js 程序能够验证当前环境是否支持 nodejs 方式访问 TDengine。
验证方法：
1. 新建安装验证目录，例如：`~/tdengine-test`，拷贝github上nodejsChecker.js源程序。下载地址：（https://github.com/taosdata/TDengine/tree/develop/examples/nodejs/nodejsChecker.js）。
1. 新建安装验证目录，例如：`~/tdengine-test`，拷贝 github 上 nodejsChecker.js 源程序。下载地址：`https://github.com/taosdata/TDengine/tree/develop/examples/nodejs/nodejsChecker.js`。
2. 在命令行中执行以下命令：
......@@ -1413,15 +1432,15 @@ npm install td2.0-connector
node nodejsChecker.js host=localhost
```
3. 执行以上步骤后，在命令行会输出nodejs连接Tdengine实例，并执行简答插入和查询的结果。
3. 执行以上步骤后，在命令行会输出 nodejs 连接 TDengine 实例，并执行简答插入和查询的结果。
### Node.js连接器的使用
以下是Node.js 连接器的一些基本使用方法，详细的使用方法可参考[TDengine Node.js connector](https://github.com/taosdata/TDengine/tree/develop/src/connector/nodejs)。
以下是 Node.js 连接器的一些基本使用方法，详细的使用方法可参考[TDengine Node.js connector](https://github.com/taosdata/TDengine/tree/develop/src/connector/nodejs)。
#### 建立连接
使用node.js连接器时，必须先`require td2.0-connector`，然后使用 `taos.connect` 函数建立到服务端的连接。例如如下代码：
使用 Node.js 连接器时，必须先 `require td2.0-connector`，然后使用 `taos.connect` 函数建立到服务端的连接。例如如下代码：
```javascript
const taos = require('td2.0-connector');
......@@ -1429,25 +1448,25 @@ var conn = taos.connect({host:"taosdemo.com", user:"root", password:"taosdata",
var cursor = conn.cursor(); // Initializing a new cursor
```
建立了一个到hostname为taosdemo.com，端口为6030（Tdengine的默认端口号）的连接。连接指定了用户名（root）和密码（taosdata）。taos.connect 函数必须提供的参数是`host`，其它参数在没有提供的情况下会使用如下的默认值。taos.connect返回了`cursor` 对象，使用cursor来执行sql语句。
建立了一个到 hostname 为 taosdemo.com，端口为 6030（TDengine的默认端口号）的连接。连接指定了用户名（root）和密码（taosdata）。taos.connect 函数必须提供的参数是`host`，其它参数在没有提供的情况下会使用如下的默认值。taos.connect 返回了 `cursor` 对象，使用 cursor 来执行 SQL 语句。
#### 执行SQL和插入数据
#### 执行 SQL 和插入数据
对于DDL语句（例如create database、create table、use等），可以使用cursor的execute方法。代码如下：
对于 DDL 语句（例如create database、create table、use等），可以使用 cursor 的 execute 方法。代码如下：
```js
cursor.execute('create database if not exists test;')
```
以上代码创建了一个名称为test的数据库。对于DDL语句，一般没有返回值，cursor的execute返回值为0。
以上代码创建了一个名称为 `test` 的数据库。对于 DDL 语句，一般没有返回值，cursor 的 execute 返回值为 0。
对于Insert语句，代码如下：
对于 Insert 语句，代码如下：
```js
var affectRows = cursor.execute('insert into test.weather values(now, 22.3, 34);')
```
execute方法的返回值为该语句影响的行数，上面的sql向test库的weather表中，插入了一条数据，则返回值affectRows为1。
execute 方法的返回值为该语句影响的行数，上面的 SQL 向 test 库的 weather 表中，插入了一条数据，则返回值 affectRows 为 1。
TDengine 目前还不支持 delete 语句。但从 2.0.8.0 版本开始，可以通过 `CREATE DATABASE` 时指定的 UPDATE 参数来启用对数据行的 update。
......@@ -1467,6 +1486,7 @@ promise.then(function(result) {
result.pretty();
});
```
格式化查询语句还可以使用`query`的`bind`方法。如下面的示例：`query`会自动将提供的数值填入查询语句的`?`里。
```javascript
......@@ -1475,6 +1495,7 @@ query.execute().then(function(result) {
result.pretty();
})
```
如果在`query`语句里提供第二个参数并设为`true`也可以立即获取查询结果。如下：
```javascript
......@@ -1487,6 +1508,7 @@ promise.then(function(result) {
#### 关闭连接
在完成插入、查询等操作后，要关闭连接。代码如下：
```js
conn.close();
```
......@@ -1494,6 +1516,7 @@ conn.close();
#### 异步函数
异步查询数据库的操作和上面类似，只需要在`cursor.execute`, `TaosQuery.execute`等函数后面加上`_a`。
```javascript
var promise1 = cursor.query('select count(*), avg(v1), avg(v2) from meter1;').execute_a()
var promise2 = cursor.query('select count(*), avg(v1), avg(v2) from meter2;').execute_a();
......@@ -1507,6 +1530,6 @@ promise2.then(function(result) {
### 示例
[node-example.js](https://github.com/taosdata/TDengine/blob/master/examples/nodejs/node-example.js)提供了一个使用NodeJS 连接器建表，插入天气数据并查询插入的数据的代码示例。
[node-example.js](https://github.com/taosdata/TDengine/blob/master/examples/nodejs/node-example.js) 提供了一个使用NodeJS 连接器建表，插入天气数据并查询插入的数据的代码示例。
[node-example-raw.js](https://github.com/taosdata/TDengine/blob/master/examples/nodejs/node-example-raw.js)同样是一个使用NodeJS 连接器建表，插入天气数据并查询插入的数据的代码示例，但和上面不同的是，该示例只使用`cursor`。
[node-example-raw.js](https://github.com/taosdata/TDengine/blob/master/examples/nodejs/node-example-raw.js) 同样是一个使用 NodeJS 连接器建表，插入天气数据并查询插入的数据的代码示例，但和上面不同的是，该示例只使用 `cursor`。
documentation20/en/07.advanced-features/docs.md
浏览文件 @ 9dfb5717
......@@ -9,8 +9,8 @@ Continuous query of TDengine adopts time-driven mode, which can be defined direc
The continuous query provided by TDengine differs from the time window calculation in ordinary stream computing in the following ways:
- Unlike the real-time feedback calculated results of stream computing, continuous query only starts calculation after the time window is closed. For example, if the time period is 1 day, the results of that day will only be generated after 23:59:59.
- If a history record is written to the time interval that has been calculated, the continuous query will not re-calculate and will not push the new results to the user again.
- TDengine server does not cache or save the client's status, nor does it provide Exactly-Once semantic guarantee. If the application crashes, the continuous query will be pull up again and starting time must be provided by the application.
- If a history record is written to the time interval that has been calculated, the continuous query will not re-calculate and will not push the new results to the user again.
- TDengine server does not cache or save the client's status, nor does it provide Exactly-Once semantic guarantee. If the application crashes, the continuous query will be pull up again and starting time must be provided by the application.
### How to use continuous query
......@@ -83,7 +83,7 @@ taos_consume
taos_unsubscribe
```
Please refer to the [C/C++ Connector](https://www.taosdata.com/cn/documentation/connector/) for the documentation of these APIs. The following is still a smart meter scenario as an example to introduce their specific usage (please refer to the previous section "Continuous Query" for the structure of STables and sub-tables). The complete sample code can be found [here](https://github.com/taosdata/TDengine/blob/master/tests/examples/c/subscribe.c).
Please refer to the [C/C++ Connector](https://www.taosdata.com/cn/documentation/connector/) for the documentation of these APIs. The following is still a smart meter scenario as an example to introduce their specific usage (please refer to the previous section "Continuous Query" for the structure of STables and sub-tables). The complete sample code can be found [here](https://github.com/taosdata/TDengine/blob/master/examples/c/subscribe.c).
If we want to be notified and do some process when the current of a smart meter exceeds a certain limit (e.g. 10A), there are two methods: one is to query each sub-table separately, record the timestamp of the last piece of data after each query, and then only query all data after this timestamp:
......@@ -210,8 +210,8 @@ After introducing the code, let's take a look at the actual running effect. For
You can compile and start the sample program by executing the following command in the directory where the sample code is located:
```shell
$ make
$ ./subscribe -sql='select * from meters where current > 10;'
make
./subscribe -sql='select * from meters where current > 10;'
```
After the sample program starts, open another terminal window, and the shell that starts TDengine inserts a data with a current of 12A into **D1001**:
......@@ -299,8 +299,8 @@ public class SubscribeDemo {
try {
if (null != subscribe)
subscribe.close(true); // Close the subscription
if (connection != null)
connection.close();
if (connection != null)
connection.close();
} catch (SQLException throwables) {
throwables.printStackTrace();
}
......@@ -312,7 +312,7 @@ public class SubscribeDemo {
Run the sample program. First, it consumes all the historical data that meets the query conditions:
```shell
# java -jar subscribe.jar
# java -jar subscribe.jar
ts: 1597464000000 current: 12.0 voltage: 220 phase: 1 location: Beijing.Chaoyang groupid : 2
ts: 1597464600000 current: 12.3 voltage: 220 phase: 2 location: Beijing.Chaoyang groupid : 2
......@@ -357,4 +357,4 @@ This SQL statement will obtain the last recorded voltage value of all smart mete
In scenarios of TDengine, alarm monitoring is a common requirement. Conceptually, it requires the program to filter out data that meet certain conditions from the data of the latest period of time, and calculate a result according to a defined formula based on these data. When the result meets certain conditions and lasts for a certain period of time, it will notify the user in some form.
In order to meet the needs of users for alarm monitoring, TDengine provides this function in the form of an independent module. For its installation and use, please refer to the blog [How to Use TDengine for Alarm Monitoring](https://www.taosdata.com/blog/2020/04/14/1438.html).
\ No newline at end of file
In order to meet the needs of users for alarm monitoring, TDengine provides this function in the form of an independent module. For its installation and use, please refer to the blog [How to Use TDengine for Alarm Monitoring](https://www.taosdata.com/blog/2020/04/14/1438.html).
documentation20/en/08.connector/docs.md
浏览文件 @ 9dfb5717
......@@ -17,7 +17,7 @@ At present, TDengine connectors support a wide range of platforms, including har
| **C#** | ○ | ● | ● | ○ | ○ | ○ | ○ | -- | -- |
| **RESTful** | ● | ● | ● | ● | ● | ● | ○ | ○ | ○ |
Note: ● stands for that has been verified by official tests; ○ stands for that has been verified by unofficial tests.
Note: ● stands for that has been verified by official tests; ○ stands for that has been verified by unofficial tests.
Note:
......@@ -30,9 +30,9 @@ Note:
The server should already have the TDengine server package installed. The connector driver installation steps are as follows:
**Linux**
### Linux
**1. Download from TAOS Data website(https://www.taosdata.com/cn/all-downloads/)**
**1. Download from TAOS Data [official website](https://www.taosdata.com/cn/all-downloads/)**
* X64 hardware environment: TDengine-client-2.x.x.x-Linux-x64.tar.gz
* ARM64 hardware environment: TDengine-client-2.x.x.x-Linux-aarch64.tar.gz
......@@ -52,11 +52,11 @@ After extracting the package, you will see the following files (directories) in
*install_client. sh*: Installation script for application driver
*taos.tar.gz*: Application driver installation package
*taos.tar.gz*: Application driver installation package
*driver*: TDengine application driver
*driver*: TDengine application driver
*connector*: Connectors for various programming languages (go/grafanaplugin/nodejs/python/JDBC)
*connector*: Connectors for various programming languages (go/grafanaplugin/nodejs/python/JDBC)
*Examples*: Sample programs for various programming languages (C/C #/go/JDBC/MATLAB/python/R)
......@@ -74,7 +74,7 @@ Edit the taos.cfg file (default path/etc/taos/taos.cfg) and change firstEP to En
**Windows x64/x86**
**1. Download from TAOS Data website(https://www.taosdata.com/cn/all-downloads/)**
**1. Download from TAOS Data [official website](https://www.taosdata.com/cn/all-downloads/)**
* X64 hardware environment: TDengine-client-2.X.X.X-Windows-x64.exe
* X86 hardware environment: TDengine-client-2.X.X.X-Windows-x86.exe
......@@ -87,15 +87,15 @@ Default installation path is: C:\TDengine, with following files(directories):
*taos.exe*: taos shell command line program
*cfg*: configuration file directory
*cfg*: configuration file directory
*driver*: application driver dynamic link library
*driver*: application driver dynamic link library
*examples*: sample program bash/C/C #/go/JDBC/Python/Node.js
*examples*: sample program bash/C/C #/go/JDBC/Python/Node.js
*include*: header file
*include*: header file
*log*: log file
*log*: log file
*unins000. exe*: uninstall program
......@@ -118,16 +118,16 @@ After the above installation and configuration completed, and confirm that the T
If you execute taos directly under Linux shell, you should be able to connect to tdengine service normally and jump to taos shell interface. For Example:
```mysql
$ taos
Welcome to the TDengine shell from Linux, Client Version:2.0.5.0
Copyright (c) 2017 by TAOS Data, Inc. All rights reserved.
taos> show databases;
name | created_time | ntables | vgroups | replica | quorum | days | keep1,keep2,keep(D) | cache(MB)| blocks | minrows | maxrows | wallevel | fsync | comp | precision | status |
=========================================================================================================================================================================================================================
test | 2020-10-14 10:35:48.617 | 10 | 1 | 1 | 1 | 2 | 3650,3650,3650 | 16| 6 | 100 | 4096 | 1 | 3000 | 2 | ms | ready |
log | 2020-10-12 09:08:21.651 | 4 | 1 | 1 | 1 | 10 | 30,30,30 | 1| 3 | 100 | 4096 | 1 | 3000 | 2 | us | ready |
Query OK, 2 row(s) in set (0.001198s)
taos>
$ taos
Welcome to the TDengine shell from Linux, Client Version:2.0.5.0
Copyright (c) 2017 by TAOS Data, Inc. All rights reserved.
taos> show databases;
name | created_time | ntables | vgroups | replica | quorum | days | keep1,keep2,keep(D) | cache(MB)| blocks | minrows | maxrows | wallevel | fsync | comp | precision | status |
=========================================================================================================================================================================================================================
test | 2020-10-14 10:35:48.617 | 10 | 1 | 1 | 1 | 2 | 3650,3650,3650 | 16| 6 | 100 | 4096 | 1 | 3000 | 2 | ms | ready |
log | 2020-10-12 09:08:21.651 | 4 | 1 | 1 | 1 | 10 | 30,30,30 | 1| 3 | 100 | 4096 | 1 | 3000 | 2 | us | ready |
Query OK, 2 row(s) in set (0.001198s)
taos>
```
**Windows (x64/x86) environment:**
......@@ -135,16 +135,16 @@ taos>
Under cmd, enter the c:\TDengine directory and directly execute taos.exe, and you should be able to connect to tdengine service normally and jump to taos shell interface. For example:
```mysql
C:\TDengine>taos
Welcome to the TDengine shell from Linux, Client Version:2.0.5.0
Copyright (c) 2017 by TAOS Data, Inc. All rights reserved.
taos> show databases;
name | created_time | ntables | vgroups | replica | quorum | days | keep1,keep2,keep(D) | cache(MB) | blocks | minrows | maxrows | wallevel | fsync | comp | precision | status |
===================================================================================================================================================================================================================================================================
test | 2020-10-14 10:35:48.617 | 10 | 1 | 1 | 1 | 2 | 3650,3650,3650 | 16 | 6 | 100 | 4096 | 1 | 3000 | 2 | ms | ready |
log | 2020-10-12 09:08:21.651 | 4 | 1 | 1 | 1 | 10 | 30,30,30 | 1 | 3 | 100 | 4096 | 1 | 3000 | 2 | us | ready |
Query OK, 2 row(s) in set (0.045000s)
taos>
C:\TDengine>taos
Welcome to the TDengine shell from Linux, Client Version:2.0.5.0
Copyright (c) 2017 by TAOS Data, Inc. All rights reserved.
taos> show databases;
name | created_time | ntables | vgroups | replica | quorum | days | keep1,keep2,keep(D) | cache(MB) | blocks | minrows | maxrows | wallevel | fsync | comp | precision | status |
===================================================================================================================================================================================================================================================================
test | 2020-10-14 10:35:48.617 | 10 | 1 | 1 | 1 | 2 | 3650,3650,3650 | 16 | 6 | 100 | 4096 | 1 | 3000 | 2 | ms | ready |
log | 2020-10-12 09:08:21.651 | 4 | 1 | 1 | 1 | 10 | 30,30,30 | 1 | 3 | 100 | 4096 | 1 | 3000 | 2 | us | ready |
Query OK, 2 row(s) in set (0.045000s)
taos>
```
## <a class="anchor" id="c-cpp"></a> C/C++ Connector
......@@ -167,7 +167,7 @@ Note:
- The TDengine dynamic library needs to be linked at compiling. The library in Linux is *libtaos.so*, which installed at/usr/local/taos/driver. By Windows, it is taos.dll and installed at C:\ TDengine.
- Unless otherwise specified, when the return value of API is an integer, 0 represents success, others are error codes representing the cause of failure, and when the return value is a pointer, NULL represents failure.
More sample codes for using C/C++ connectors, please visit https://github.com/taosdata/TDengine/tree/develop/examples/c.
More sample codes for using C/C++ connectors, please visit `https://github.com/taosdata/TDengine/tree/develop/examples/c`.
### Basic API
......@@ -204,7 +204,6 @@ Create a database connection and initialize the connection context. The paramete
A null return value indicates a failure. The application needs to save the returned parameters for subsequent API calls.
Note: The same process can connect to multiple taosd processes based on ip/port
- `char *taos_get_server_info(TAOS *taos)`
Get version information of the server-side.
......@@ -290,11 +289,11 @@ Asynchronous APIs all need applications to provide corresponding callback functi
Asynchronous APIs have relatively high requirements for users, who can selectively use them according to specific application scenarios. Here are three important asynchronous APIs:
- `void taos_query_a(TAOS *taos, const char *sql, void (*fp)(void *param, TAOS_RES *, int code), void *param);`
Execute SQL statement asynchronously.
Execute SQL statement asynchronously.
* taos: The database connection returned by calling `taos_connect`
* sql: The SQL statement needed to execute
* fp: User-defined callback function, whose third parameter `code` is used to indicate whether the operation is successful, `0` for success, and negative number for failure (call `taos_errstr` to get the reason for failure). When defining the callback function, it mainly handles the second parameter `TAOS_RES *`, which is the result set returned by the query
* taos: The database connection returned by calling `taos_connect`
* sql: The SQL statement needed to execute
* fp: User-defined callback function, whose third parameter `code` is used to indicate whether the operation is successful, `0` for success, and negative number for failure (call `taos_errstr` to get the reason for failure). When defining the callback function, it mainly handles the second parameter `TAOS_RES *`, which is the result set returned by the query
* param：the parameter for the callback
- `void taos_fetch_rows_a(TAOS_RES *res, void (*fp)(void *param, TAOS_RES *, int numOfRows), void *param);`
......@@ -305,7 +304,6 @@ Asynchronous APIs have relatively high requirements for users, who can selective
The asynchronous APIs of TDengine all use non-blocking calling mode. Applications can use multithreading to open multiple tables at the same time, and can query or insert to each open table at the same time. It should be pointed out that the **application client must ensure that the operation on the same table is completely serialized**, that is, when the insertion or query operation on the same table is not completed (when no result returned), the second insertion or query operation cannot be performed.
<a class="anchor" id="stmt"></a>
### Parameter binding API
......@@ -553,7 +551,7 @@ Create subscription
```python
# Create a subscription with the topic ‘test’ and a consumption cycle of 1000 milliseconds
# If the first parameter is True, it means restarting the subscription.
# If the first parameter is True, it means restarting the subscription.
# If it is False and a subscription with the topic 'test 'has been created before,
# it means continuing to consume the data of this subscription instead of restarting to consume all the data
sub = conn.subscribe(True, "test", "select * from tb;", 1000)
......@@ -626,12 +624,12 @@ Refer to [JSON type instructions](https://www.taosdata.com/en/documentation/taos
So far Python still does not completely support nanosecond type. Please refer to the link 1 and 2. The implementation of the python connector is to return an integer number for nanosecond value rather than datatime type as what ms and us do. The developer needs to handle it themselves. We recommend using pandas to_datetime() function. If Python officially support nanosecond in the future, TAOS Data might be possible to change the interface accordingly, which mean the application need change too.
1. https://stackoverflow.com/questions/10611328/parsing-datetime-strings-containing-nanoseconds
2. https://www.python.org/dev/peps/pep-0564/
1. `https://stackoverflow.com/questions/10611328/parsing-datetime-strings-containing-nanoseconds`
2. `https://www.python.org/dev/peps/pep-0564/`
#### Helper
Users can directly view the usage information of the module through Python's helper, or refer to the sample program in tests/examples/Python. The following are some common classes and methods:
Users can directly view the usage information of the module through Python's helper, or refer to the sample program in the `examples/Python` directory. The following are some common classes and methods:
- *TDengineConnection* class
......@@ -647,7 +645,7 @@ Used to generate an instance of taos.TDengineConnection.
### Python connector code sample
In tests/examples/python, we provide a sample Python program read_example. py to guide you to design your own write and query program. After installing the corresponding client, introduce the taos class through `import taos`. The steps are as follows:
In the `examples/python` directory, we provide a sample Python program read_example. py to guide you to design your own write and query program. After installing the corresponding client, introduce the taos class through `import taos`. The steps are as follows:
- Get the `TDengineConnection` object through `taos.connect`, which can be applied for only one by a program and shared among multiple threads.
......@@ -657,7 +655,7 @@ In tests/examples/python, we provide a sample Python program read_example. py to
- If a write statement is executed, `execute` returns the number of rows successfully written affected rows.
- If the query statement is executed, the result set needs to be pulled through the fetchall method after the execution is successful.
- If the query statement is executed, the result set needs to be pulled through the fetchall method after the execution is successful.
You can refer to the sample code for specific methods.
......@@ -667,7 +665,7 @@ To support the development of various types of platforms, TDengine provides an A
Note: One difference from the native connector is that the RESTful interface is stateless, so the `USE db_name` command has no effect and all references to table names and super table names require the database name to be specified. (Starting from version 2.2.0.0, we support specifying db_name in the RESTful url, in which case if the database name prefix is not specified in the SQL statement. Since version 2.4.0.0, RESTful service is provided by taosAdapter by default, which requires that db_name must be specified in the url.)
### HTTP request format
### HTTP request format
```
http://<ip>:<PORT>/rest/sql
......@@ -678,7 +676,7 @@ Parameter description:
- IP: Any host in the cluster
- PORT: httpPort configuration item in the configuration file, defaulting to 6041
For example: http://192.168.0.1:6041/rest/sql is a URL that points to an IP address of 192.168.0.1.
For example: `http://192.168.0.1:6041/rest/sql` is a URL that points to an IP address of 192.168.0.1.
The header of HTTP request needs to carry identity authentication information. TDengine supports Basic authentication and custom authentication. Subsequent versions will provide standard and secure digital signature mechanism for identity authentication.
......@@ -724,7 +722,7 @@ The return value is in JSON format, as follows:
["2018-10-03 14:38:15.000", 12.6, ...]
],
"rows": 2
}
}
```
Description:
......@@ -877,32 +875,33 @@ Only some configuration parameters related to RESTful interface are listed below
- httpEnableCompress: Compression is not supported by default. Currently, TDengine only supports gzip compression format
- httpdebugflag: Logging switch, 131: error and alarm information only, 135: debugging information, 143: very detailed debugging information, default 131
## <a class="anchor" id="csharp"></a> CSharp Connector
* The C # connector supports: Linux 64/Windows x64/Windows x86.
* C# connector can be download and include as normal table form [Nuget.org](https://www.nuget.org/packages/TDengine.Connector/).
* On Windows, C # applications can use the native C interface of TDengine to perform all database operations, and future versions will provide the ORM (Dapper) framework driver.
### Installation preparation
* For application driver installation, please refer to the[ steps of installing connector driver](https://www.taosdata.com/en/documentation/connector#driver).
* For application driver installation, please refer to the [steps of installing connector driver](https://www.taosdata.com/en/documentation/connector#driver).
* .NET interface file TDengineDrivercs.cs and reference sample TDengineTest.cs are both located in the Windows client install_directory/examples/C# directory.
* Install [.NET SDK](https://dotnet.microsoft.com/download)
### Example Source Code
you can find sample code under follow directions:
* {client_install_directory}/examples/C#
* [github C# example source code](https://github.com/taosdata/TDengine/tree/develop/examples/C%2523)
**Tips:** TDengineTest.cs One of C# connector's sample code that include basic examples like connection,sql executions and so on.
### Installation verification
Run {client_install_directory}/examples/C#/C#Checker/C#Checker.cs
Need install .Net SDK first
```cmd
cd {client_install_directory}/examples/C#/C#Checker
//run c#checker.cs
......@@ -910,24 +909,31 @@ dotnet run -- -h <FQDN> //dotnet run will build project first by default.
```
### How to use C# connector
On Windows system, .NET applications can use the .NET interface of TDengine to perform all database operations. The steps to use it are as follows:
need to install .NET SDK first
* create a c# project.
* create a c# project.
``` cmd
mkdir test
cd test
cd test
dotnet new console
```
* add TDengineDriver as an package through Nuget
``` cmd
dotnet add package TDengine.Connector
```
* include the TDnengineDriver in you application's namespace
* include the TDnengineDriver in you application's namespace
```C#
using TDengineDriver;
```
* user can reference from[TDengineTest.cs](https://github.com/taosdata/TDengine/tree/develop/examples/C%2523/TDengineTest) and learn how to define database connection,query,insert and other basic data manipulations.
**Note:**
......@@ -942,9 +948,9 @@ Maikebing.Data.Taos is an ADO.Net provider for TDengine that supports Linux, Win
```
// Download
https://github.com/maikebing/Maikebing.EntityFrameworkCore.Taos
// How to use
https://www.taosdata.com/blog/2020/11/02/1901.html
https://github.com/maikebing/Maikebing.EntityFrameworkCore.Taos
// How to use
https://www.taosdata.com/blog/2020/11/02/1901.html
```
## <a class="anchor" id="go"></a> Go Connector
......@@ -953,9 +959,9 @@ https://www.taosdata.com/blog/2020/11/02/1901.html
- For application driver installation, please refer to the [steps of installing connector driver](https://www.taosdata.com/en/documentation/connector#driver).
The TDengine provides the GO driver taosSql. taosSql implements the GO language's built-in interface database/sql/driver. Users can access TDengine in the application by simply importing the package as follows, see https://github.com/taosdata/driver-go/blob/develop/taosSql/driver_test.go for details.
The TDengine provides the GO driver taosSql. taosSql implements the GO language's built-in interface database/sql/driver. Users can access TDengine in the application by simply importing the package as follows, see `https://github.com/taosdata/driver-go/blob/develop/taosSql/driver_test.go` for details.
Sample code for using the Go connector can be found in https://github.com/taosdata/TDengine/tree/develop/examples/go .
Sample code for using the Go connector can be found in `https://github.com/taosdata/TDengine/tree/develop/examples/go`.
```Go
import (
......@@ -967,8 +973,8 @@ import (
**It is recommended to use Go version 1.13 or above and turn on module support:**
```bash
go env -w GO111MODULE=on
go env -w GOPROXY=https://goproxy.io,direct
go env -w GO111MODULE=on
go env -w GOPROXY=https://goproxy.io,direct
```
`taosSql` v2 completed refactoring of the v1 version and separated the built-in database operation interface `database/sql/driver` to the directory `taosSql`, and put other advanced functions such as subscription and stmt into the directory `af`.
......@@ -1071,7 +1077,7 @@ After installing the TDengine client, the nodejsChecker.js program can verify wh
Steps:
1. Create a new installation verification directory, for example: `~/tdengine-test`, copy the nodejsChecker.js source program on github. Download address: （https://github.com/taosdata/TDengine/tree/develop/examples/nodejs/nodejsChecker.js）.
1. Create a new installation verification directory, for example: `~/tdengine-test`, copy the nodejsChecker.js source program on github. Download address: `https://github.com/taosdata/TDengine/tree/develop/examples/nodejs/nodejsChecker.js`.
2. Execute the following command:
......@@ -1136,7 +1142,7 @@ The results of the query can be obtained and printed through `query.execute()` f
```javascript
var promise = query.execute();
promise.then(function(result) {
result.pretty();
result.pretty();
});
```
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或