docs.md 56.6 KB
Newer Older
X
Xiaxin Li 已提交
1 2
# 连接器

3
TDengine提供了丰富的应用程序开发接口,其中包括C/C++、Java、Python、Go、Node.js、C# 、RESTful 等,便于用户快速开发应用。
4

5
![image-connecotr](page://images/connector.png)
6

7
目前TDengine的连接器可支持的平台广泛,包括:X64/X86/ARM64/ARM32/MIPS/Alpha等硬件平台,以及Linux/Win64/Win32等开发环境。对照矩阵如下:
8

9 10 11
| **CPU**     | **X64   64bit** | **X64   64bit** | **X64   64bit** | **X86   32bit** | **ARM64** | **ARM32** | **MIPS   龙芯** | **Alpha   申威** | **X64   海光** |
| ----------- | --------------- | --------------- | --------------- | --------------- | --------- | --------- | --------------- | ---------------- | -------------- |
| **OS**      | **Linux**       | **Win64**       | **Win32**       | **Win32**       | **Linux** | **Linux** | **Linux**       | **Linux**        | **Linux**      |
12 13 14
| **C/C++**   | ●               | ●               | ●               | ○               | ●         | ●         | ○               | ○                | ○              |
| **JDBC**    | ●               | ●               | ●               | ○               | ●         | ●         | ○               | ○                | ○              |
| **Python**  | ●               | ●               | ●               | ○               | ●         | ●         | ○               | --               | ○              |
15 16
| **Go**      | ●               | ●               | ●               | ○               | ●         | ●         | ○               | --               | --             |
| **NodeJs**  | ●               | ●               | ○               | ○               | ●         | ●         | ○               | --               | --             |
17
| **C#**      | ●               | ●               | ○               | ○               | ○         | ○         | ○               | --               | --             |
18
| **RESTful** | ●               | ●               | ●               | ●               | ●         | ●         | ○               | ○                | ○              |
19

20
其中 ● 表示官方测试验证通过,○ 表示非官方测试验证通过,-- 表示未经验证。
X
Xiaxin Li 已提交
21

22 23
注意:

24
* 在没有安装TDengine服务端软件的系统中使用连接器(除RESTful外)访问 TDengine 数据库,需要安装相应版本的客户端安装包来使应用驱动(Linux系统中文件名为libtaos.so,Windows系统中为taos.dll)被安装在系统中,否则会产生无法找到相应库文件的错误。
25
* 所有执行 SQL 语句的 API,例如 C/C++ Connector 中的 `tao_query``taos_query_a``taos_subscribe` 等,以及其它语言中与它们对应的API,每次都只能执行一条 SQL 语句,如果实际参数中包含了多条语句,它们的行为是未定义的。
26
* 升级 TDengine 到 2.0.8.0 版本的用户,必须更新 JDBC。连接 TDengine 必须升级 taos-jdbcdriver 到 2.0.12 及以上。详细的版本依赖关系请参见 [taos-jdbcdriver 文档](https://www.taosdata.com/cn/documentation/connector/java#version)
27
* 无论选用何种编程语言的连接器,2.0 及以上版本的 TDengine 推荐数据库应用的每个线程都建立一个独立的连接,或基于线程建立连接池,以避免连接内的“USE statement”状态量在线程之间相互干扰(但连接的查询和写入操作都是线程安全的)。
X
Xiaxin Li 已提交
28

29
## <a class="anchor" id="driver"></a>安装连接器驱动步骤
30

31
服务器应该已经安装TDengine服务端安装包。连接器驱动安装步骤如下:
32 33 34

**Linux**

35
**1.   从[涛思官网](https://www.taosdata.com/cn/all-downloads/)下载<!-- REPLACE_OPEN_TO_ENTERPRISE__YOU_CAN_GET_CONNECTOR_DRIVER_FROM_TAOS -->:**
36 37 38

* X64硬件环境:TDengine-client-2.x.x.x-Linux-x64.tar.gz

39
* ARM64硬件环境:TDengine-client-2.x.x.x-Linux-aarch64.tar.gz
40

41
* ARM32硬件环境:TDengine-client-2.x.x.x-Linux-aarch32.tar.gz
42 43 44 45 46 47 48

**2.   解压缩软件包**

将软件包放置在当前用户可读写的任意目录下,然后执行下面的命令:

`tar -xzvf TDengine-client-xxxxxxxxx.tar.gz`

49
其中xxxxxxxxx需要替换为实际版本的字符串。
50 51 52 53 54 55 56 57 58

**3.   执行安装脚本**

解压软件包之后,会在解压目录下看到以下文件(目录):

*install_client.sh*:安装脚本,用于应用驱动程序
*taos.tar.gz*:应用驱动安装包
*driver*:TDengine应用驱动driver
*connector*: 各种编程语言连接器(go/grafanaplugin/nodejs/python/JDBC)
59
*examples*: 各种编程语言的示例程序(c/C#/go/JDBC/MATLAB/python/R)
60

61
运行install_client.sh进行安装。
62 63 64 65 66 67 68 69 70

**4.   配置taos.cfg**

编辑taos.cfg文件(默认路径/etc/taos/taos.cfg),将firstEP修改为TDengine服务器的End Point,例如:h1.taos.com:6030

**提示: 如本机没有部署TDengine服务,仅安装了应用驱动,则taos.cfg中仅需配置firstEP,无需配置FQDN。**

**Windows x64/x86**

71
**1.   从[涛思官网](https://www.taosdata.com/cn/all-downloads/)下载<!-- REPLACE_OPEN_TO_ENTERPRISE__YOU_CAN_GET_CONNECTOR_DRIVER_WINDOWS_FROM_TAOS -->:**
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97

* X64硬件环境:TDengine-client-2.X.X.X-Windows-x64.exe

* X86硬件环境:TDengine-client-2.X.X.X-Windows-x86.exe

**2. 执行安装程序,按提示选择默认值,完成安装**

**3. 安装路径**

默认安装路径为:C:\TDengine,其中包括以下文件(目录):

*taos.exe*:taos shell命令行程序

*cfg* : 配置文件目录
*driver*: 应用驱动动态链接库
*examples*: 示例程序 bash/C/C#/go/JDBC/Python/Node.js
*include*: 头文件
*log* : 日志文件
*unins000.exe*: 卸载程序

**4. 配置taos.cfg**

编辑taos.cfg文件(默认路径C:\TDengine\cfg\taos.cfg),将firstEP修改为TDengine服务器的End Point,例如:h1.taos.com:6030

**提示:** 

98 99
1. **如利用FQDN连接服务器,必须确认本机网络环境DNS已配置好,或在hosts文件中添加FQDN寻址记录,如编辑C:\Windows\system32\drivers\etc\hosts,添加如下的记录:`192.168.1.99  h1.taos.com` **
2.**卸载:运行unins000.exe可卸载TDengine应用驱动。**
100

101
### 安装验证
102 103 104 105 106

以上安装和配置完成后,并确认TDengine服务已经正常启动运行,此时可以执行taos客户端进行登录。

**Linux环境:**

107
在Linux shell下直接执行 taos,应该就能正常连接到TDegine服务,进入到taos shell界面,示例如下:
108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138

```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>  
```

**Windows(x64/x86)环境:**

在cmd下进入到c:\TDengine目录下直接执行 taos.exe,应该就能正常链接到tdegine服务,进入到taos shell界面,示例如下:

```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>  
```

139
## <a class="anchor" id="c-cpp"></a>C/C++ Connector
X
Xiaxin Li 已提交
140

141 142
**C/C++连接器支持的系统有**

143
| **CPU类型**  | x64(64bit) |          |          | ARM64    | ARM32      |
144 145 146 147
| ------------ | ------------ | -------- | -------- | -------- | ---------- |
| **OS类型**   | Linux        | Win64    | Win32    | Linux    | Linux      |
| **支持与否** | **支持**     | **支持** | **支持** | **支持** | **开发中** |

148 149 150 151
C/C++的API类似于MySQL的C API。应用程序使用时,需要包含TDengine头文件 *taos.h*,里面列出了提供的API的函数原型。安装后,taos.h位于:

- Linux:`/usr/local/taos/include`
- Windows:`C:\TDengine\include`
X
Xiaxin Li 已提交
152 153 154 155 156

```C
#include <taos.h>
```

157
注意:
X
Xiaxin Li 已提交
158

159 160
* 在编译时需要链接TDengine动态库。Linux 为 *libtaos.so* ,安装后,位于 _/usr/local/taos/driver_。Windows为 taos.dll,安装后位于  *C:\TDengine*
* 如未特别说明,当API的返回值是整数时,_0_ 代表成功,其它是代表失败原因的错误码,当返回值是指针时, _NULL_ 表示失败。
161 162 163
* 在 taoserror.h中有所有的错误码,以及对应的原因描述。

### 示例程序
X
Xiaxin Li 已提交
164

165
使用C/C++连接器的示例代码请参见 https://github.com/taosdata/TDengine/tree/develop/tests/examples/c 。
166

167 168 169 170 171 172 173 174 175 176
示例程序源码也可以在安装目录下的 examples/c 路径下找到:

**apitest.c、asyncdemo.c、demo.c、prepare.c、stream.c、subscribe.c**

该目录下有makefile,在Linux环境下,直接执行make就可以编译得到执行文件。

在一台机器上启动TDengine服务,执行这些示例程序,按照提示输入TDengine服务的FQDN,就可以正常运行,并打印出信息。 

**提示:**在ARM环境下编译时,请将makefile中的-msse4.2打开,这个选项只有在x64/x86硬件平台上才能支持。

X
Xiaxin Li 已提交
177 178 179 180 181 182 183 184 185 186 187 188 189 190
### 基础API

基础API用于完成创建数据库连接等工作,为其它API的执行提供运行时环境。

- `void taos_init()`

  初始化运行环境。如果应用没有主动调用该API,那么应用在调用`taos_connect`时将自动调用,故应用程序一般无需手动调用该API。 

- `void taos_cleanup()`

  清理运行环境,应用退出前应调用此API。

- `int taos_options(TSDB_OPTION option, const void * arg, ...)`

191
   设置客户端选项,目前支持区域设置(`TSDB_OPTION_LOCALE`)、字符集设置(`TSDB_OPTION_CHARSET`)、时区设置(`TSDB_OPTION_TIMEZONE`)、配置文件路径设置(`TSDB_OPTION_CONFIGDIR`)。区域设置、字符集、时区默认为操作系统当前设置。 
X
Xiaxin Li 已提交
192 193 194 195 196

- `char *taos_get_client_info()`

  获取客户端版本信息。

197
- `TAOS *taos_connect(const char *host, const char *user, const char *pass, const char *db, int port)`
X
Xiaxin Li 已提交
198 199 200

  创建数据库连接,初始化连接上下文。其中需要用户提供的参数包含:

201
    - host:TDengine管理主节点的FQDN
X
Xiaowei Su 已提交
202 203 204
    - user:用户名
    - pass:密码
    - db:数据库名字,如果用户没有提供,也可以正常连接,用户可以通过该连接创建新的数据库,如果用户提供了数据库名字,则说明该数据库用户已经创建好,缺省使用该数据库
205
    - port:TDengine管理主节点的端口号
206

X
Xiaxin Li 已提交
207 208 209 210 211 212 213 214 215 216 217 218
  返回值为空表示失败。应用程序需要保存返回的参数,以便后续API调用。

- `char *taos_get_server_info(TAOS *taos)`

  获取服务端版本信息。

- `int taos_select_db(TAOS *taos, const char *db)`

  将当前的缺省数据库设置为`db`

- `void taos_close(TAOS *taos)`

219
  关闭连接,其中`taos``taos_connect`函数返回的指针。
X
Xiaxin Li 已提交
220 221 222 223 224 225 226

### 同步查询API

传统的数据库操作API,都属于同步操作。应用调用API后,一直处于阻塞状态,直到服务器返回结果。TDengine支持如下API:

- `TAOS_RES* taos_query(TAOS *taos, const char *sql)`

227
  该API用来执行SQL语句,可以是DQL、DML或DDL语句。 其中的`taos`参数是通过`taos_connect`获得的指针。不能通过返回值是否是 NULL 来判断执行结果是否失败,而是需要用`taos_errno`函数解析结果集中的错误代码来进行判断。
X
Xiaxin Li 已提交
228 229 230

- `int taos_result_precision(TAOS_RES *res)`

231
  返回结果集时间戳字段的精度,`0` 代表毫秒,`1` 代表微秒,`2` 代表纳秒。
X
Xiaxin Li 已提交
232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254

- `TAOS_ROW taos_fetch_row(TAOS_RES *res)`

  按行获取查询结果集中的数据。

- `int taos_fetch_block(TAOS_RES *res, TAOS_ROW *rows)`

  批量获取查询结果集中的数据,返回值为获取到的数据的行数。

- `int taos_num_fields(TAOS_RES *res)``int taos_field_count(TAOS_RES *res)`

  这两个API等价,用于获取查询结果集中的列数。

- `int* taos_fetch_lengths(TAOS_RES *res)`

  获取结果集中每个字段的长度。 返回值是一个数组,其长度为结果集的列数。

- `int taos_affected_rows(TAOS_RES *res)`

  获取被所执行的 SQL 语句影响的行数。

- `TAOS_FIELD *taos_fetch_fields(TAOS_RES *res)`

255
  获取查询结果集每列数据的属性(列的名称、列的数据类型、列的长度),与taos_num_fileds配合使用,可用来解析`taos_fetch_row`返回的一个元组(一行)的数据。 `TAOS_FIELD` 的结构如下:
X
Xiaxin Li 已提交
256

257 258 259 260
```c
typedef struct taosField {
  char     name[65];  // 列名
  uint8_t  type;      // 数据类型
261
  int16_t  bytes;     // 长度,单位是字节
262 263
} TAOS_FIELD;
```
X
Xiaxin Li 已提交
264 265 266 267 268 269 270

- `void taos_stop_query(TAOS_RES *res)`

  停止一个查询的执行。

- `void taos_free_result(TAOS_RES *res)`

271
  释放查询结果集以及相关的资源。查询完成后,务必调用该API释放资源,否则可能导致应用内存泄露。但也需注意,释放资源后,如果再调用`taos_consume`等获取查询结果的函数,将导致应用Crash。
X
Xiaxin Li 已提交
272 273 274 275 276

- `char *taos_errstr(TAOS_RES *res)`

  获取最近一次API调用失败的原因,返回值为字符串。

277
- `int taos_errno(TAOS_RES *res)`
X
Xiaxin Li 已提交
278 279 280

  获取最近一次API调用失败的原因,返回值为错误代码。

281
**注意**:2.0及以上版本 TDengine 推荐数据库应用的每个线程都建立一个独立的连接,或基于线程建立连接池。而不推荐在应用中将该连接 (TAOS\*) 结构体传递到不同的线程共享使用。基于 TAOS 结构体发出的查询、写入等操作具有多线程安全性,但 “USE statement” 等状态量有可能在线程之间相互干扰。此外,C 语言的连接器可以按照需求动态建立面向数据库的新连接(该过程对用户不可见),同时建议只有在程序最后退出的时候才调用 taos_close 关闭连接。
X
Xiaxin Li 已提交
282 283 284

### 异步查询API

285
同步API之外,TDengine还提供性能更高的异步调用API处理数据插入、查询操作。在软硬件环境相同的情况下,异步API处理数据插入的速度比同步API快2~4倍。异步API采用非阻塞式的调用方式,在系统真正完成某个具体数据库操作前,立即返回。调用的线程可以去处理其他工作,从而可以提升整个应用的性能。异步API在网络延迟严重的情况下,优点尤为突出。
X
Xiaxin Li 已提交
286 287 288

异步API都需要应用提供相应的回调函数,回调函数参数设置如下:前两个参数都是一致的,第三个参数依不同的API而定。第一个参数param是应用调用异步API时提供给系统的,用于回调时,应用能够找回具体操作的上下文,依具体实现而定。第二个参数是SQL操作的结果集,如果为空,比如insert操作,表示没有记录返回,如果不为空,比如select操作,表示有记录返回。

E
Elias Soong 已提交
289
异步API对于使用者的要求相对较高,用户可根据具体应用场景选择性使用。下面是两个重要的异步API: 
X
Xiaxin Li 已提交
290 291 292 293 294

- `void taos_query_a(TAOS *taos, const char *sql, void (*fp)(void *param, TAOS_RES *, int code), void *param);`

  异步执行SQL语句。
  
Y
Yiqing Liu 已提交
295 296 297 298
    * taos:调用taos_connect返回的数据库连接
    * sql:需要执行的SQL语句
    * fp:用户定义的回调函数,其第三个参数`code`用于指示操作是否成功,`0`表示成功,负数表示失败(调用`taos_errstr`获取失败原因)。应用在定义回调函数的时候,主要处理第二个参数`TAOS_RES *`,该参数是查询返回的结果集
    * param:应用提供一个用于回调的参数
X
Xiaxin Li 已提交
299 300 301 302 303

- `void taos_fetch_rows_a(TAOS_RES *res, void (*fp)(void *param, TAOS_RES *, int numOfRows), void *param);`

  批量获取异步查询的结果集,只能与`taos_query_a`配合使用。其中:
  
Y
Yiqing Liu 已提交
304 305
    * res:`taos_query_a`回调时返回的结果集
    * fp:回调函数。其参数`param`是用户可定义的传递给回调函数的参数结构体;`numOfRows`是获取到的数据的行数(不是整个查询结果集的函数)。 在回调函数中,应用可以通过调用`taos_fetch_row`前向迭代获取批量记录中每一行记录。读完一块内的所有记录后,应用需要在回调函数中继续调用`taos_fetch_rows_a`获取下一批记录进行处理,直到返回的记录数(numOfRows)为零(结果返回完成)或记录数为负值(查询出错)。
X
Xiaxin Li 已提交
306 307 308

TDengine的异步API均采用非阻塞调用模式。应用程序可以用多线程同时打开多张表,并可以同时对每张打开的表进行查询或者插入操作。需要指出的是,**客户端应用必须确保对同一张表的操作完全串行化**,即对同一个表的插入或查询操作未完成时(未返回时),不能够执行第二个插入或查询操作。

309 310
<a class="anchor" id="stmt"></a>
### 参数绑定 API
X
Xiaxin Li 已提交
311

312
除了直接调用 `taos_query` 进行查询,TDengine 也提供了支持参数绑定的 Prepare API,与 MySQL 一样,这些 API 目前也仅支持用问号 `?` 来代表待绑定的参数。文档中有时也会把此功能称为“原生接口写入”。
313 314 315 316 317 318

从 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` 来设置表名;
4. 如果 INSERT 语句中既预留了表名又预留了 TAGS(例如 INSERT 语句采取的是自动建表的方式),那么调用 `taos_stmt_set_tbname_tags` 来设置表名和 TAGS 的值;
319
5. 调用 `taos_stmt_bind_param_batch` 以多列的方式设置 VALUES 的值,或者调用 `taos_stmt_bind_param` 以单行的方式设置 VALUES 的值;
320 321 322 323 324
6. 调用 `taos_stmt_add_batch` 把当前绑定的参数加入批处理;
7. 可以重复第 3~6 步,为批处理加入更多的数据行;
8. 调用 `taos_stmt_execute` 执行已经准备好的批处理指令;
9. 执行完毕,调用 `taos_stmt_close` 释放所有资源。

325 326
说明:如果 `taos_stmt_execute` 执行成功,假如不需要改变 SQL 语句的话,那么是可以复用 `taos_stmt_prepare` 的解析结果,直接进行第 3~6 步绑定新数据的。但如果执行出错,那么并不建议继续在当前的环境上下文下继续工作,而是建议释放资源,然后从 `taos_stmt_init` 步骤重新开始。

327 328 329
除 C/C++ 语言外,TDengine 的 Java 语言 JNI Connector 也提供参数绑定接口支持,具体请另外参见:[参数绑定接口的 Java 用法](https://www.taosdata.com/cn/documentation/connector/java#stmt-java)

接口相关的具体函数如下(也可以参考 [apitest.c](https://github.com/taosdata/TDengine/blob/develop/tests/examples/c/apitest.c) 文件中使用对应函数的方式):
X
Xiaxin Li 已提交
330 331 332 333 334 335 336

- `TAOS_STMT* taos_stmt_init(TAOS *taos)`

  创建一个 TAOS_STMT 对象用于后续调用。

- `int taos_stmt_prepare(TAOS_STMT *stmt, const char *sql, unsigned long length)`

337
  解析一条 SQL 语句,将解析结果和参数信息绑定到 stmt 上,如果参数 length 大于 0,将使用此参数作为 SQL 语句的长度,如等于 0,将自动判断 SQL 语句的长度。
X
Xiaxin Li 已提交
338 339 340

- `int taos_stmt_bind_param(TAOS_STMT *stmt, TAOS_BIND *bind)`

341 342
  不如 `taos_stmt_bind_param_batch` 效率高,但可以支持非 INSERT 类型的 SQL 语句。  
  进行参数绑定,bind 指向一个数组(代表所要绑定的一行数据),需保证此数组中的元素数量和顺序与 SQL 语句中的参数完全一致。TAOS_BIND 的使用方法与 MySQL 中的 MYSQL_BIND 一致,具体定义如下:
X
Xiaxin Li 已提交
343

344 345 346 347 348 349 350 351 352 353 354
```c
typedef struct TAOS_BIND {
  int            buffer_type;
  void *         buffer;
  unsigned long  buffer_length;  // 未实际使用
  unsigned long *length;
  int *          is_null;
  int            is_unsigned;    // 未实际使用
  int *          error;          // 未实际使用
} TAOS_BIND;
```
X
Xiaxin Li 已提交
355

356 357
- `int taos_stmt_set_tbname(TAOS_STMT* stmt, const char* name)`

358
  (2.1.1.0 版本新增,仅支持用于替换 INSERT 语句中的参数值)  
359 360 361 362
  当 SQL 语句中的表名使用了 `?` 占位时,可以使用此函数绑定一个具体的表名。

- `int taos_stmt_set_tbname_tags(TAOS_STMT* stmt, const char* name, TAOS_BIND* tags)`

363
  (2.1.2.0 版本新增,仅支持用于替换 INSERT 语句中的参数值)  
364 365 366 367
  当 SQL 语句中的表名和 TAGS 都使用了 `?` 占位时,可以使用此函数绑定具体的表名和具体的 TAGS 取值。最典型的使用场景是使用了自动建表功能的 INSERT 语句(目前版本不支持指定具体的 TAGS 列)。tags 参数中的列数量需要与 SQL 语句中要求的 TAGS 数量完全一致。

- `int taos_stmt_bind_param_batch(TAOS_STMT* stmt, TAOS_MULTI_BIND* bind)`

368
  (2.1.1.0 版本新增,仅支持用于替换 INSERT 语句中的参数值)  
369
  以多列的方式传递待绑定的数据,需要保证这里传递的数据列的顺序、列的数量与 SQL 语句中的 VALUES 参数完全一致。TAOS_MULTI_BIND 的具体定义如下:
370 371 372 373 374 375 376 377 378 379 380 381

```c
typedef struct TAOS_MULTI_BIND {
  int          buffer_type;
  void *       buffer;
  uintptr_t    buffer_length;
  int32_t *    length;
  char *       is_null;
  int          num;             // 列的个数,即 buffer 中的参数个数
} TAOS_MULTI_BIND;
```

X
Xiaxin Li 已提交
382 383
- `int taos_stmt_add_batch(TAOS_STMT *stmt)`

384
  将当前绑定的参数加入批处理中,调用此函数后,可以再次调用 `taos_stmt_bind_param``taos_stmt_bind_param_batch` 绑定新的参数。需要注意,此函数仅支持 INSERT/IMPORT 语句,如果是 SELECT 等其他 SQL 语句,将返回错误。
X
Xiaxin Li 已提交
385 386 387 388 389 390 391

- `int taos_stmt_execute(TAOS_STMT *stmt)`

  执行准备好的语句。目前,一条语句只能执行一次。

- `TAOS_RES* taos_stmt_use_result(TAOS_STMT *stmt)`

392
  获取语句的结果集。结果集的使用方式与非参数化调用时一致,使用完成后,应对此结果集调用 `taos_free_result` 以释放资源。
393

X
Xiaxin Li 已提交
394 395 396 397
- `int taos_stmt_close(TAOS_STMT *stmt)`

  执行完毕,释放所有资源。

398 399 400 401 402
- `char * taos_stmt_errstr(TAOS_STMT *stmt)`

  (2.1.3.0 版本新增)  
  用于在其他 stmt API 返回错误(返回错误码或空指针)时获取错误信息。

X
Xiaxin Li 已提交
403 404 405 406 407 408 409
### 连续查询接口

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用来创建数据流,其中:
410 411
    * taos:已经建立好的数据库连接。
    * sql:SQL查询语句(仅能使用查询语句)。
Y
Yiqing Liu 已提交
412
    * fp:用户定义的回调函数指针,每次流式计算完成后,TDengine将查询的结果(TAOS_ROW)、查询状态(TAOS_RES)、用户定义参数(PARAM)传递给回调函数,在回调函数内,用户可以使用taos_num_fields获取结果集列数,taos_fetch_fields获取结果集每列数据的类型。
413
    * stime:是流式计算开始的时间。如果是“64位整数最小值”,表示从现在开始;如果不为“64位整数最小值”,表示从指定的时间开始计算(UTC时间从1970/1/1算起的毫秒数)。
414
    * param:是应用提供的用于回调的一个参数,回调时,提供给应用。
Y
Yiqing Liu 已提交
415
    * callback: 第二个回调函数,会在连续查询自动停止时被调用。
416

417
  返回值为NULL,表示创建失败;返回值不为空,表示成功。
X
Xiaxin Li 已提交
418 419 420 421 422 423 424 425 426 427 428 429

- `void taos_close_stream (TAOS_STREAM *tstr)`

  关闭数据流,其中提供的参数是taos_open_stream的返回值。用户停止流式计算的时候,务必关闭该数据流。

### 数据订阅接口

订阅API目前支持订阅一张或多张表,并通过定期轮询的方式不断获取写入表中的最新数据。 

* `TAOS_SUB *taos_subscribe(TAOS* taos, int restart, const char* topic, const char *sql, TAOS_SUBSCRIBE_CALLBACK fp, void *param, int interval)`

  该函数负责启动订阅服务,成功时返回订阅对象,失败时返回 `NULL`,其参数为:
Y
Yiqing Liu 已提交
430 431 432 433 434 435 436
    * taos:已经建立好的数据库连接
    * restart:如果订阅已经存在,是重新开始,还是继续之前的订阅
    * topic:订阅的主题(即名称),此参数是订阅的唯一标识
    * sql:订阅的查询语句,此语句只能是 `select` 语句,只应查询原始数据,只能按时间正序查询数据
    * fp:收到查询结果时的回调函数(稍后介绍函数原型),只在异步调用时使用,同步调用时此参数应该传 `NULL`
    * param:调用回调函数时的附加参数,系统API将其原样传递到回调函数,不进行任何处理
    * interval:轮询周期,单位为毫秒。异步调用时,将根据此参数周期性的调用回调函数,为避免对系统性能造成影响,不建议将此参数设置的过小;同步调用时,如两次调用`taos_consume`的间隔小于此周期,API将会阻塞,直到时间间隔超过此周期。
X
Xiaxin Li 已提交
437 438 439 440

* `typedef void (*TAOS_SUBSCRIBE_CALLBACK)(TAOS_SUB* tsub, TAOS_RES *res, void* param, int code)`

  异步模式下,回调函数的原型,其参数为:
Y
Yiqing Liu 已提交
441 442 443 444
    * tsub:订阅对象
    * res:查询结果集,注意结果集中可能没有记录
    * param:调用 `taos_subscribe`时客户程序提供的附加参数
    * code:错误码
445
  
446
  **注意**:在这个回调函数里不可以做耗时过长的处理,尤其是对于返回的结果集中数据较多的情况,否则有可能导致客户端阻塞等异常状态。如果必须进行复杂计算,则建议在另外的线程中进行处理。
X
Xiaxin Li 已提交
447 448 449 450 451

* `TAOS_RES *taos_consume(TAOS_SUB *tsub)`

  同步模式下,该函数用来获取订阅的结果。 用户应用程序将其置于一个循环之中。 如两次调用`taos_consume`的间隔小于订阅的轮询周期,API将会阻塞,直到时间间隔超过此周期。 如果数据库有新记录到达,该API将返回该最新的记录,否则返回一个没有记录的空结果集。 如果返回值为 `NULL`,说明系统出错。 异步模式下,用户程序不应调用此API。

452 453
  **注意**:在调用 `taos_consume()` 之后,用户应用应确保尽快调用 `taos_fetch_row()``taos_fetch_block()` 来处理订阅结果,否则服务端会持续缓存查询结果数据等待客户端读取,极端情况下会导致服务端内存消耗殆尽,影响服务稳定性。

X
Xiaxin Li 已提交
454 455 456 457
* `void taos_unsubscribe(TAOS_SUB *tsub, int keepProgress)`

  取消订阅。 如参数 `keepProgress` 不为0,API会保留订阅的进度信息,后续调用 `taos_subscribe` 时可以基于此进度继续;否则将删除进度信息,后续只能重新开始读取数据。

458 459
<!-- REPLACE_OPEN_TO_ENTERPRISE__JAVA_CONNECTOR_DOC -->

460
## <a class="anchor" id="python"></a>Python Connector
X
Xiaxin Li 已提交
461

462
Python连接器的使用参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1963.html)
463

464 465 466 467 468 469 470 471 472
**安装**:参见下面具体步骤

**示例程序**:位于install_directory/examples/python

### 安装

Python连接器支持的系统有:Linux 64/Windows x64

安装前准备:
X
Xiaxin Li 已提交
473

474 475 476
- 已安装好TDengine应用驱动,请参考[安装连接器驱动步骤](https://www.taosdata.com/cn/documentation/connector#driver)
- 已安装python 2.7 or >= 3.4
- 已安装pip
X
Xiaxin Li 已提交
477

478 479 480
### Python连接器安装

**Linux**
X
Xiaxin Li 已提交
481

482
用户可以在源代码的src/connector/python(或者tar.gz的/connector/python)文件夹下找到connector安装包。用户可以通过pip命令安装: 
X
Xiaxin Li 已提交
483

484
`pip install src/connector/python/`
X
Xiaxin Li 已提交
485 486 487



488
`pip3 install src/connector/python/`
X
Xiaxin Li 已提交
489

490 491 492 493
**Windows**

在已安装Windows TDengine 客户端的情况下, 将文件"C:\TDengine\driver\taos.dll" 拷贝到 "C:\Windows\system32" 目录下, 然后进入Windows *cmd* 命令行界面
```bash
494 495
cd C:\TDengine\connector\python
python -m pip install .
X
Xiaxin Li 已提交
496 497
```

498
* 如果机器上没有pip命令,用户可将src/connector/python下的taos文件夹拷贝到应用程序的目录使用。
X
Xiaxin Li 已提交
499 500
对于windows 客户端,安装TDengine windows 客户端后,将C:\TDengine\driver\taos.dll拷贝到C:\windows\system32目录下即可。

501 502 503 504 505 506 507 508 509 510 511 512 513
### 示例程序

示例程序源码位于install_directory/examples/Python,有:
**read_example.py       Python示例源程序**

用户可以参考read_example.py这个程序来设计用户自己的写入、查询程序。

在安装了对应的应用驱动后,通过import taos引入taos类。主要步骤如下:

- 通过taos.connect获取TDengineConnection对象,这个对象可以一个程序只申请一个,在多线程中共享。

- 通过TDengineConnection对象的 .cursor()方法获取一个新的游标对象,这个游标对象必须保证每个线程独享。

514
- 通过游标对象的execute()方法,执行写入或查询的SQL语句。
515

516
- 如果执行的是写入语句,execute返回的是成功写入的行数信息affected rows。
517 518 519 520 521 522 523 524 525 526 527 528 529 530 531

- 如果执行的是查询语句,则execute执行成功后,需要通过fetchall方法去拉取结果集。 具体方法可以参考示例代码。

### 安装验证

运行如下指令:

```bash
cd {install_directory}/examples/python/PYTHONConnectorChecker/`
python3 PythonChecker.py -host <fqdn>
```

验证通过将打印出成功信息。

### Python连接器的使用
X
Xiaxin Li 已提交
532 533 534 535 536 537

#### 代码示例

* 导入TDengine客户端模块

```python
538
import taos
X
Xiaxin Li 已提交
539 540
```
* 获取连接并获取游标对象
541

X
Xiaxin Li 已提交
542 543 544 545
```python
conn = taos.connect(host="127.0.0.1", user="root", password="taosdata", config="/etc/taos")
c1 = conn.cursor()
```
546
* *host* 是TDengine 服务端所有IP, *config* 为客户端配置文件所在目录
X
Xiaxin Li 已提交
547 548

* 写入数据
549

X
Xiaxin Li 已提交
550 551
```python
import datetime
552

X
Xiaxin Li 已提交
553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570
# 创建数据库
c1.execute('create database db')
c1.execute('use db')
# 建表
c1.execute('create table tb (ts timestamp, temperature int, humidity float)')
# 插入数据
start_time = datetime.datetime(2019, 11, 1)
affected_rows = c1.execute('insert into tb values (\'%s\', 0, 0.0)' %start_time)
# 批量插入数据
time_interval = datetime.timedelta(seconds=60)
sqlcmd = ['insert into tb values']
for irow in range(1,11):
  start_time += time_interval
  sqlcmd.append('(\'%s\', %d, %f)' %(start_time, irow, irow*1.2))
affected_rows = c1.execute(' '.join(sqlcmd))
```

* 查询数据
571

X
Xiaxin Li 已提交
572 573 574 575 576 577 578 579 580
```python
c1.execute('select * from tb')
# 拉取查询结果
data = c1.fetchall()
# 返回的结果是一个列表,每一行构成列表的一个元素
numOfRows = c1.rowcount
numOfCols = len(c1.description)
for irow in range(numOfRows):
  print("Row%d: ts=%s, temperature=%d, humidity=%f" %(irow, data[irow][0], data[irow][1],data[irow][2]))
581

X
Xiaxin Li 已提交
582 583 584 585 586 587 588
# 直接使用cursor 循环拉取查询结果
c1.execute('select * from tb')
for data in c1:
  print("ts=%s, temperature=%d, humidity=%f" %(data[0], data[1],data[2]))
```

* 创建订阅
589

X
Xiaxin Li 已提交
590 591 592 593 594 595 596
```python
# 创建一个主题为 'test' 消费周期为1000毫秒的订阅
# 第一个参数为 True 表示重新开始订阅,如为 False 且之前创建过主题为 'test' 的订阅,则表示继续消费此订阅的数据,而不是重新开始消费所有数据
sub = conn.subscribe(True, "test", "select * from tb;", 1000)
```

* 消费订阅的数据
597

X
Xiaxin Li 已提交
598 599 600 601 602 603 604
```python
data = sub.consume()
for d in data:
    print(d)
```

* 取消订阅
605

X
Xiaxin Li 已提交
606 607 608 609 610
```python
sub.close()
```

* 关闭连接
611

X
Xiaxin Li 已提交
612 613 614 615
```python
c1.close()
conn.close()
```
616

617
#### 关于纳秒 (nanosecond) 在 Python 连接器中的说明
618 619 620 621 622 623

由于目前 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/

X
Xiaxin Li 已提交
624 625 626 627
#### 帮助信息

用户可通过python的帮助信息直接查看模块的使用信息,或者参考tests/examples/python中的示例程序。以下为部分常用类和方法:

628
- _TDengineConnection_ 类
X
Xiaxin Li 已提交
629 630

  参考python中help(taos.TDengineConnection)。
631
  这个类对应客户端和TDengine建立的一个连接。在客户端多线程的场景下,推荐每个线程申请一个独立的连接实例,而不建议多线程共享一个连接。
X
Xiaxin Li 已提交
632

633
- _TDengineCursor_ 类
X
Xiaxin Li 已提交
634 635

  参考python中help(taos.TDengineCursor)。
636
  这个类对应客户端进行的写入、查询操作。在客户端多线程的场景下,这个游标实例必须保持线程独享,不能跨线程共享使用,否则会导致返回结果出现错误。
X
Xiaxin Li 已提交
637

638
- _connect_ 方法
X
Xiaxin Li 已提交
639 640 641 642

  用于生成taos.TDengineConnection的实例。

### Python客户端使用示例代码
643

X
Xiaxin Li 已提交
644 645 646 647
在tests/examples/python中,我们提供了一个示例Python程序read_example.py,可以参考这个程序来设计用户自己的写入、查询程序。在安装了对应的客户端后,通过import taos引入taos类。主要步骤如下

- 通过taos.connect获取TDengineConnection对象,这个对象可以一个程序只申请一个,在多线程中共享。
- 通过TDengineConnection对象的 .cursor()方法获取一个新的游标对象,这个游标对象必须保证每个线程独享。
648 649
- 通过游标对象的execute()方法,执行写入或查询的SQL语句。
- 如果执行的是写入语句,execute返回的是成功写入的行数信息affected rows。
X
Xiaxin Li 已提交
650 651 652
- 如果执行的是查询语句,则execute执行成功后,需要通过fetchall方法去拉取结果集。
具体方法可以参考示例代码。

653
## <a class="anchor" id="restful"></a>RESTful Connector
X
Xiaxin Li 已提交
654

655 656
为支持各种不同类型平台的开发,TDengine 提供符合 REST 设计标准的 API,即 RESTful API。为最大程度降低学习成本,不同于其他数据库 RESTful API 的设计方法,TDengine 直接通过 HTTP POST 请求 BODY 中包含的 SQL 语句来操作数据库,仅需要一个 URL。RESTful 连接器的使用参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1965.html)

657
注意:与标准连接器的一个区别是,RESTful 接口是无状态的,因此 `USE db_name` 指令没有效果,所有对表名、超级表名的引用都需要指定数据库名前缀。(从 2.2.0.0 版本开始,支持在 RESTful url 中指定 db_name,这时如果 SQL 语句中没有指定数据库名前缀的话,会使用 url 中指定的这个 db_name。)
X
Xiaxin Li 已提交
658

659 660
### 安装

661
RESTful 接口不依赖于任何 TDengine 的库,因此客户端不需要安装任何 TDengine 的库,只要客户端的开发语言支持 HTTP 协议即可。
662 663 664

### 验证

665
在已经安装 TDengine 服务器端的情况下,可以按照如下方式进行验证。
666

667
下面以 Ubuntu 环境中使用 curl 工具(确认已经安装)来验证 RESTful 接口的正常。
668

669
下面示例是列出所有的数据库,请把 h1.taosdata.com 和 6041(缺省值)替换为实际运行的 TDengine 服务 fqdn 和端口号:
670 671 672
```html
curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'show databases;' h1.taosdata.com:6041/rest/sql
```
673

674 675 676 677 678 679 680 681 682 683 684 685
返回值结果如下表示验证通过:
```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
}
```

686
### RESTful 连接器的使用
687

688
#### HTTP 请求格式 
X
Xiaxin Li 已提交
689 690

```
691
http://<fqdn>:<port>/rest/sql/[db_name]
X
Xiaxin Li 已提交
692 693 694 695
```

参数说明:

696 697
- fqnd: 集群中的任一台主机 FQDN 或 IP 地址
- port: 配置文件中 httpPort 配置项,缺省为 6041
698
- db_name: 可选参数,指定本次所执行的 SQL 语句的默认数据库库名。(从 2.2.0.0 版本开始支持)
X
Xiaxin Li 已提交
699

700
例如:http://h1.taos.com:6041/rest/sql/test 是指向地址为 h1.taos.com:6041 的 url,并将默认使用的数据库库名设置为 test。
X
Xiaxin Li 已提交
701

702
HTTP 请求的 Header 里需带有身份认证信息,TDengine 支持 Basic 认证与自定义认证两种机制,后续版本将提供标准安全的数字签名机制来做身份验证。
X
Xiaxin Li 已提交
703 704 705 706 707 708 709 710 711 712 713 714 715

- 自定义身份认证信息如下所示(<token>稍后介绍)

```
Authorization: Taosd <TOKEN>
```

- Basic身份认证信息如下所示

```
Authorization: Basic <TOKEN>
```

716
HTTP 请求的 BODY 里就是一个完整的 SQL 语句,SQL 语句中的数据表应提供数据库前缀,例如 \<db_name>.\<tb_name>。如果表名不带数据库前缀,又没有在 url 中指定数据库名的话,系统会返回错误。因为 HTTP 模块只是一个简单的转发,没有当前 DB 的概念。 
X
Xiaxin Li 已提交
717

718
使用 curl 通过自定义身份认证方式来发起一个 HTTP Request,语法如下:
X
Xiaxin Li 已提交
719

720
```bash
721
curl -H 'Authorization: Basic <TOKEN>' -d '<SQL>' <ip>:<PORT>/rest/sql/[db_name]
X
Xiaxin Li 已提交
722 723 724 725
```

或者

726
```bash
727
curl -u username:password -d '<SQL>' <ip>:<PORT>/rest/sql/[db_name]
X
Xiaxin Li 已提交
728 729
```

730
其中,`TOKEN``{username}:{password}` 经过 Base64 编码之后的字符串,例如 `root:taosdata` 编码后为 `cm9vdDp0YW9zZGF0YQ==`
X
Xiaxin Li 已提交
731

732
### HTTP 返回格式
X
Xiaxin Li 已提交
733

734
返回值为 JSON 格式,如下:
X
Xiaxin Li 已提交
735

736
```json
X
Xiaxin Li 已提交
737 738
{
    "status": "succ",
739 740
    "head": ["ts","current", ],
    "column_meta": [["ts",9,8],["current",6,4], ],
X
Xiaxin Li 已提交
741 742 743 744 745 746 747 748 749 750
    "data": [
        ["2018-10-03 14:38:05.000", 10.3, ],
        ["2018-10-03 14:38:15.000", 12.6, ]
    ],
    "rows": 2
} 
```

说明:

751
- status: 告知操作结果是成功还是失败。
752
- head: 表的定义,如果不返回结果集,则仅有一列 “affected_rows”。(从 2.0.17.0 版本开始,建议不要依赖 head 返回值来判断数据列类型,而推荐使用 column_meta。在未来版本中,有可能会从返回值中去掉 head 这一项。)
753
- column_meta: 从 2.0.17.0 版本开始,返回值中增加这一项来说明 data 里每一列的数据类型。具体每个列会用三个值来说明,分别为:列名、列类型、类型长度。例如`["current",6,4]`表示列名为“current”;列类型为 6,也即 float 类型;类型长度为 4,也即对应 4 个字节表示的 float。如果列类型为 binary 或 nchar,则类型长度表示该列最多可以保存的内容长度,而不是本次返回值中的具体数据长度。当列类型是 nchar 的时候,其类型长度表示可以保存的 unicode 字符数量,而不是 bytes。
754
- data: 具体返回的数据,一行一行的呈现,如果不返回结果集,那么就仅有 [[affected_rows]]。data 中每一行的数据列顺序,与 column_meta 中描述数据列的顺序完全一致。
755 756 757 758 759 760 761 762 763 764 765 766 767
- rows: 表明总共多少行数据。

column_meta 中的列类型说明:
* 1:BOOL
* 2:TINYINT
* 3:SMALLINT
* 4:INT
* 5:BIGINT
* 6:FLOAT
* 7:DOUBLE
* 8:BINARY
* 9:TIMESTAMP
* 10:NCHAR
X
Xiaxin Li 已提交
768 769 770

### 自定义授权码

771
HTTP 请求中需要带有授权码 `<TOKEN>`,用于身份识别。授权码通常由管理员提供,可简单的通过发送 `HTTP GET` 请求来获取授权码,操作如下:
X
Xiaxin Li 已提交
772

773
```bash
774
curl http://<fqnd>:<port>/rest/login/<username>/<password>
X
Xiaxin Li 已提交
775 776
```

777
其中,`fqdn` 是 TDengine 数据库的 fqdn 或 ip 地址,port 是 TDengine 服务的端口号,`username` 为数据库用户名,`password` 为数据库密码,返回值为 `JSON` 格式,各字段含义如下:
X
Xiaxin Li 已提交
778 779 780 781 782

- status:请求结果的标志位

- code:返回值代码

783
- desc:授权码
X
Xiaxin Li 已提交
784 785 786

获取授权码示例:

787
```bash
H
Hui Li 已提交
788
curl http://192.168.0.1:6041/rest/login/root/taosdata
X
Xiaxin Li 已提交
789 790 791 792
```

返回值:

793
```json
X
Xiaxin Li 已提交
794 795 796 797 798 799 800 801 802
{
  "status": "succ",
  "code": 0,
  "desc": "/KfeAzX/f9na8qdtNZmtONryp201ma04bEl8LcvLUd7a8qdtNZmtONryp201ma04"
}
```

### 使用示例

803
- 在 demo 库里查询表 d1001 的所有记录: 
X
Xiaxin Li 已提交
804

805
```bash
X
Xiaowei Su 已提交
806
curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001' 192.168.0.1:6041/rest/sql
X
Xiaxin Li 已提交
807 808 809
```
返回值:

810
```json
X
Xiaxin Li 已提交
811 812
{
    "status": "succ",
813 814
    "head": ["ts","current","voltage","phase"],
    "column_meta": [["ts",9,8],["current",6,4],["voltage",4,4],["phase",6,4]],
X
Xiaxin Li 已提交
815 816 817 818 819 820 821 822
    "data": [
        ["2018-10-03 14:38:05.000",10.3,219,0.31],
        ["2018-10-03 14:38:15.000",12.6,218,0.33]
    ],
    "rows": 2
}
```

823
- 创建库 demo:
X
Xiaxin Li 已提交
824

825
```bash
X
Xiaowei Su 已提交
826
curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'create database demo' 192.168.0.1:6041/rest/sql
X
Xiaxin Li 已提交
827 828 829
```

返回值:
830
```json
X
Xiaxin Li 已提交
831 832 833
{
    "status": "succ",
    "head": ["affected_rows"],
834
    "column_meta": [["affected_rows",4,4]],
X
Xiaxin Li 已提交
835
    "data": [[1]],
836
    "rows": 1
X
Xiaxin Li 已提交
837 838 839 840 841
}
```

### 其他用法

842
#### 结果集采用 Unix 时间戳
X
Xiaxin Li 已提交
843

844
HTTP 请求 URL 采用 `sqlt` 时,返回结果集的时间戳将采用 Unix 时间戳格式表示,例如
X
Xiaxin Li 已提交
845

846
```bash
H
Hui Li 已提交
847
curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001' 192.168.0.1:6041/rest/sqlt
X
Xiaxin Li 已提交
848 849 850 851
```

返回值:

852
```json
X
Xiaxin Li 已提交
853 854
{
    "status": "succ",
855 856
    "head": ["ts","current","voltage","phase"],
    "column_meta": [["ts",9,8],["current",6,4],["voltage",4,4],["phase",6,4]],
X
Xiaxin Li 已提交
857 858 859 860 861 862 863 864
    "data": [
        [1538548685000,10.3,219,0.31],
        [1538548695000,12.6,218,0.33]
    ],
    "rows": 2
}
```

865
#### 结果集采用 UTC 时间字符串
X
Xiaxin Li 已提交
866

867
HTTP 请求 URL 采用 `sqlutc` 时,返回结果集的时间戳将采用 UTC 时间字符串表示,例如
868
```bash
H
Hui Li 已提交
869
  curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.t1' 192.168.0.1:6041/rest/sqlutc
X
Xiaxin Li 已提交
870 871 872 873
```

返回值:

874
```json
X
Xiaxin Li 已提交
875 876
{
    "status": "succ",
877 878
    "head": ["ts","current","voltage","phase"],
    "column_meta": [["ts",9,8],["current",6,4],["voltage",4,4],["phase",6,4]],
X
Xiaxin Li 已提交
879 880 881 882 883 884 885 886 887 888
    "data": [
        ["2018-10-03T14:38:05.000+0800",10.3,219,0.31],
        ["2018-10-03T14:38:15.000+0800",12.6,218,0.33]
    ],
    "rows": 2
}
```

### 重要配置项

889
下面仅列出一些与 RESTful 接口有关的配置参数,其他系统参数请看配置文件里的说明。(注意:配置修改后,需要重启 taosd 服务才能生效)
X
Xiaxin Li 已提交
890

891 892 893 894 895 896
- 对外提供 RESTful 服务的端口号,默认绑定到 6041(实际取值是 serverPort + 11,因此可以通过修改 serverPort 参数的设置来修改)。
- httpMaxThreads: 启动的线程数量,默认为 2(2.0.17.0 版本开始,默认值改为 CPU 核数的一半向下取整)。
- restfulRowLimit: 返回结果集(JSON 格式)的最大条数,默认值为 10240。
- httpEnableCompress: 是否支持压缩,默认不支持,目前 TDengine 仅支持 gzip 压缩格式。
- httpDebugFlag: 日志开关,默认 131。131:仅错误和报警信息,135:调试信息,143:非常详细的调试信息,默认 131。
- httpDbNameMandatory: 是否必须在 RESTful url 中指定默认的数据库名。默认为 0,即关闭此检查。如果设置为 1,那么每个 RESTful url 中都必须设置一个默认数据库名,否则无论此时执行的 SQL 语句是否需要指定数据库,都会返回一个执行错误,拒绝执行此 SQL 语句。
X
Xiaxin Li 已提交
897

898
## <a class="anchor" id="csharp"></a>CSharp Connector
L
liuyq-617 已提交
899

900 901 902 903
C#连接器支持的系统有:Linux 64/Windows x64/Windows x86

### 安装准备

904
* 应用驱动安装请参考[安装连接器驱动步骤](https://www.taosdata.com/cn/documentation/connector#driver)
905
* 接口文件TDengineDrivercs.cs和参考程序示例TDengineTest.cs均位于Windows客户端install_directory/examples/C#目录下。
E
Elias Soong 已提交
906
* 在Windows系统上,C#应用程序可以使用TDengine的原生C接口来执行所有数据库操作,后续版本将提供ORM(Dapper)框架驱动。
L
liuyq-617 已提交
907

908 909 910 911 912 913
### 示例程序

示例程序源码位于install_directory/examples/C#,有:

TDengineTest.cs       C#示例源程序

914
### 安装验证
L
liuyq-617 已提交
915

916
运行install_directory/examples/C#/C#Checker/C#Checker.exe
L
liuyq-617 已提交
917

918 919 920 921 922
```cmd
cd {install_directory}/examples/C#/C#Checker
csc /optimize *.cs
C#Checker.exe -h <fqdn>
```
L
liuyq-617 已提交
923

924
### C#连接器的使用
L
liuyq-617 已提交
925

926
在Windows系统上,C#应用程序可以使用TDengine的C#连接器接口来执行所有数据库的操作。使用的具体步骤如下所示:
L
liuyq-617 已提交
927

928
1. 将接口文件TDengineDrivercs.cs加入到应用程序所在的项目空间中。
929
2. 用户可以参考TDengineTest.cs来定义数据库连接参数,以及如何执行数据插入、查询等操作。
L
liuyq-617 已提交
930

931
此接口需要用到taos.dll文件,所以在执行应用程序前,拷贝Windows客户端install_directory/driver目录中的taos.dll文件到项目最后生成.exe可执行文件所在的文件夹。之后运行exe文件,即可访问TDengine数据库并做插入、查询等操作。
L
liuyq-617 已提交
932

933
**注意:**
L
liuyq-617 已提交
934

935 936
1. TDengine V2.0.3.0之后同时支持32位和64位Windows系统,所以C#项目在生成.exe文件时,“解决方案”/“项目”的“平台”请选择对应的“X86” 或“x64”。
2. 此接口目前已经在Visual Studio 2015/2017中验证过,其它VS版本尚待验证。
L
liuyq-617 已提交
937

938
### 第三方驱动
L
liuyq-617 已提交
939 940 941 942 943 944 945 946 947 948

Maikebing.Data.Taos是一个TDengine的ADO.Net提供器,支持linux,windows。该开发包由热心贡献者`麦壳饼@@maikebing`提供,具体请参考

```
//接口下载
https://github.com/maikebing/Maikebing.EntityFrameworkCore.Taos   
//用法说明    
https://www.taosdata.com/blog/2020/11/02/1901.html                    
```

949
## <a class="anchor" id="go"></a>Go Connector
X
Xiaxin Li 已提交
950

951 952
### 安装准备

953 954 955 956 957 958
Go连接器支持的系统有:

| **CPU类型** | x64(64bit) |   |   | aarch64 | aarch32 |
| --------------- | ------------ | -------- | -------- | -------- | ---------- |
| **OS类型**  | Linux        | Win64    | Win32    | Linux    | Linux      |
| **支持与否**    | **支持**     | **支持** | **支持** | **支持** | **开发中** |
959

960 961
安装前准备:

962
- 已安装好TDengine应用驱动,参考[安装连接器驱动步骤](https://www.taosdata.com/cn/documentation/connector#driver)
963 964

### 示例程序
965

966
使用 Go 连接器的示例代码请参考 https://github.com/taosdata/TDengine/tree/develop/tests/examples/go 以及[视频教程](https://www.taosdata.com/blog/2020/11/11/1951.html)
X
Xiaxin Li 已提交
967

968
示例程序源码也位于安装目录下的 examples/go/taosdemo.go 文件中。
969 970 971

**提示:建议Go版本是1.13及以上,并开启模块支持:**
```sh
972 973
go env -w GO111MODULE=on
go env -w GOPROXY=https://goproxy.io,direct
974 975 976
```
在taosdemo.go所在目录下进行编译和执行:
```sh
977 978 979 980 981 982
go mod init taosdemo
go get github.com/taosdata/driver-go/taosSql
# use win branch in Windows platform.
#go get github.com/taosdata/driver-go/taosSql@win
go build
./taosdemo -h fqdn -p serverPort
X
Xiaxin Li 已提交
983
```
984

985 986
### Go连接器的使用

987
TDengine提供了GO驱动程序包`taosSql``taosSql`实现了GO语言的内置接口`database/sql/driver`。用户只需按如下方式引入包就可以在应用程序中访问TDengine。
988 989 990
```go
import (
  "database/sql"
991
  _ "github.com/taosdata/driver-go/v2/taosSql"
992
)
993
```
994

995
**提示**:下划线与双引号之间必须有一个空格。
996

997 998
`taosSql` 的 v2 版本进行了重构,分离出内置数据库操作接口 `database/sql/driver` 到目录 `taosSql`;订阅、stmt等其他功能放到目录 `af`

X
Xiaxin Li 已提交
999
### 常用API
1000

1001
- `sql.Open(DRIVER_NAME string, dataSourceName string) *DB` 
1002

1003
  该API用来打开DB,返回一个类型为\*DB的对象,一般情况下,DRIVER_NAME设置为字符串`taosSql`,dataSourceName设置为字符串`user:password@/tcp(host:port)/dbname`,如果客户想要用多个goroutine并发访问TDengine, 那么需要在各个goroutine中分别创建一个sql.Open对象并用之访问TDengine
1004

1005
  **注意**: 该API成功创建的时候,并没有做权限等检查,只有在真正执行Query或者Exec的时候才能真正的去创建连接,并同时检查user/password/host/port是不是合法。另外,由于整个驱动程序大部分实现都下沉到taosSql所依赖的libtaos动态库中。所以,sql.Open本身特别轻量。
1006 1007

-  `func (db *DB) Exec(query string, args ...interface{}) (Result, error)`
X
Xiaxin Li 已提交
1008 1009

  sql.Open内置的方法,用来执行非查询相关SQL
1010 1011 1012

-  `func (db *DB) Query(query string, args ...interface{}) (*Rows, error)`

X
Xiaxin Li 已提交
1013
  sql.Open内置的方法,用来执行查询语句
1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024

- `func (db *DB) Prepare(query string) (*Stmt, error)`

  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.

- `func (s *Stmt) Query(args ...interface{}) (*Rows, error)`

1025
  sql.Open内置的方法,Query executes a prepared query statement with the given arguments and returns the query results as a \*Rows.
1026 1027 1028 1029 1030

- `func (s *Stmt) Close() error`

  sql.Open内置的方法,Close closes the statement.	

1031 1032 1033 1034
### 其他代码示例

[Consume Messages from Kafka](https://github.com/taosdata/go-demo-kafka) 是一个通过 Go 语言实现消费 Kafka 队列写入 TDengine 的示例程序,也可以作为通过 Go 连接 TDengine 的写法参考。

1035
## <a class="anchor" id="nodejs"></a>Node.js Connector
X
Xiaxin Li 已提交
1036

1037 1038
Node.js连接器支持的系统有:

涛思数据(TDengine)'s avatar
涛思数据(TDengine) 已提交
1039
|**CPU类型**  | x64(64bit) |          |          | aarch64  | aarch32  |
1040 1041 1042
| ------------ | ------------ | -------- | -------- | -------- | -------- |
| **OS类型**   | Linux        | Win64    | Win32    | Linux    | Linux    |
| **支持与否** | **支持**     | **支持** | **支持** | **支持** | **支持** |
1043

1044
Node.js连接器的使用参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1957.html)
1045

1046 1047
### 安装准备

1048
* 应用驱动安装请参考[安装连接器驱动步骤](https://www.taosdata.com/cn/documentation/connector#driver)
1049 1050 1051

### 安装Node.js连接器

1052
用户可以通过[npm](https://www.npmjs.com/)来进行安装,也可以通过源代码*src/connector/nodejs/* 来进行安装。具体安装步骤如下:
X
Xiaxin Li 已提交
1053

1054
首先,通过[npm](https://www.npmjs.com/)安装node.js 连接器。
X
Xiaxin Li 已提交
1055

1056
```bash
X
Xiaxin Li 已提交
1057 1058
npm install td2.0-connector
```
1059
我们建议用户使用npm 安装node.js连接器。如果您没有安装npm,可以将*src/connector/nodejs/*拷贝到您的nodejs 项目目录下。
X
Xiaxin Li 已提交
1060

1061
我们使用[node-gyp](https://github.com/nodejs/node-gyp)和TDengine服务端进行交互。安装node.js连接器之前,还需要根据具体操作系统来安装下文提到的一些依赖工具。
X
Xiaxin Li 已提交
1062 1063 1064 1065

### Linux

- `python` (建议`v2.7` , `v3.x.x` 目前还不支持)
1066
- `node`  2.0.6支持v12.x和v10.x,2.0.5及更早版本支持v10.x版本,其他版本可能存在包兼容性的问题。
X
Xiaxin Li 已提交
1067
- `make`
1068
- c语言编译器比如[GCC](https://gcc.gnu.org)
X
Xiaxin Li 已提交
1069 1070 1071 1072 1073

### Windows

#### 安装方法1

1074
使用微软的[windows-build-tools](https://github.com/felixrieseberg/windows-build-tools)`cmd` 命令行界面执行`npm install --global --production windows-build-tools` 即可安装所有的必备工具。
X
Xiaxin Li 已提交
1075 1076 1077

#### 安装方法2

1078
手动安装以下工具:
X
Xiaxin Li 已提交
1079

1080
- 安装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)
1081 1082
- 安装 [Python](https://www.python.org/downloads/) 2.7(`v3.x.x` 暂不支持) 并执行 `npm config set python python2.7`
- 进入`cmd`命令行界面,`npm config set msvs_version 2017`
X
Xiaxin Li 已提交
1083

1084
如果以上步骤不能成功执行,可以参考微软的node.js用户手册[Microsoft's Node.js Guidelines for Windows](https://github.com/Microsoft/nodejs-guidelines/blob/master/windows-environment.md#compiling-native-addon-modules)
X
Xiaxin Li 已提交
1085

1086
如果在Windows 10 ARM 上使用ARM64 Node.js,还需添加 "Visual C++ compilers and libraries for ARM64" 和 "Visual C++ ATL for ARM64"。
X
Xiaxin Li 已提交
1087

1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100
### 示例程序

示例程序源码位于install_directory/examples/nodejs,有:

Node-example.js       		node.js示例源程序
Node-example-raw.js

### 安装验证

在安装好TDengine客户端后,使用nodejsChecker.js程序能够验证当前环境是否支持nodejs方式访问Tdengine。

验证方法:

1101
1. 新建安装验证目录,例如:`~/tdengine-test`,拷贝github上nodejsChecker.js源程序。下载地址:(https://github.com/taosdata/TDengine/tree/develop/tests/examples/nodejs/nodejsChecker.js)。
1102

1103
2. 在命令行中执行以下命令:
1104

1105
```bash
1106 1107 1108 1109 1110 1111 1112 1113
npm init -y
npm install td2.0-connector
node nodejsChecker.js host=localhost
```

3. 执行以上步骤后,在命令行会输出nodejs连接Tdengine实例,并执行简答插入和查询的结果。

### Node.js连接器的使用
X
Xiaxin Li 已提交
1114

1115
以下是Node.js 连接器的一些基本使用方法,详细的使用方法可参考[TDengine Node.js connector](http://docs.taosdata.com/node)
X
Xiaxin Li 已提交
1116

1117
#### 建立连接
X
Xiaxin Li 已提交
1118

1119
使用node.js连接器时,必须先`require td2.0-connector`,然后使用 `taos.connect` 函数建立到服务端的连接。例如如下代码:
X
Xiaxin Li 已提交
1120 1121 1122

```javascript
const taos = require('td2.0-connector');
1123
var conn = taos.connect({host:"taosdemo.com", user:"root", password:"taosdata", config:"/etc/taos",port:6030})
X
Xiaxin Li 已提交
1124 1125 1126
var cursor = conn.cursor(); // Initializing a new cursor
```

1127
建立了一个到hostname为taosdemo.com,端口为6030(Tdengine的默认端口号)的连接。连接指定了用户名(root)和密码(taosdata)。taos.connect 函数必须提供的参数是`host`,其它参数在没有提供的情况下会使用如下的默认值。taos.connect返回了`cursor` 对象,使用cursor来执行sql语句。
X
Xiaxin Li 已提交
1128

1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148
#### 执行SQL和插入数据

对于DDL语句(例如create database、create table、use等),可以使用cursor的execute方法。代码如下:

```js
cursor.execute('create database if not exists test;')
```

以上代码创建了一个名称为test的数据库。对于DDL语句,一般没有返回值,cursor的execute返回值为0。

对于Insert语句,代码如下:

```js
var affectRows = cursor.execute('insert into test.weather values(now, 22.3, 34);')
```

execute方法的返回值为该语句影响的行数,上面的sql向test库的weather表中,插入了一条数据,则返回值affectRows为1。

TDengine目前还不支持update和delete语句。

X
Xiaxin Li 已提交
1149 1150
#### 查询

1151
可通过 `cursor.query` 函数来查询数据库。
X
Xiaxin Li 已提交
1152 1153 1154 1155 1156

```javascript
var query = cursor.query('show databases;')
```

1157
查询的结果可以通过 `query.execute()` 函数获取并打印出来。
X
Xiaxin Li 已提交
1158 1159 1160 1161 1162 1163 1164

```javascript
var promise = query.execute();
promise.then(function(result) {
  result.pretty(); 
});
```
1165
格式化查询语句还可以使用`query``bind`方法。如下面的示例:`query`会自动将提供的数值填入查询语句的`?`里。
X
Xiaxin Li 已提交
1166 1167 1168 1169 1170 1171 1172

```javascript
var query = cursor.query('select * from meterinfo.meters where ts <= ? and areaid = ?;').bind(new Date(), 5);
query.execute().then(function(result) {
  result.pretty();
})
```
1173
如果在`query`语句里提供第二个参数并设为`true`也可以立即获取查询结果。如下:
X
Xiaxin Li 已提交
1174 1175 1176 1177 1178 1179 1180

```javascript
var promise = cursor.query('select * from meterinfo.meters where v1 = 30;', true)
promise.then(function(result) {
  result.pretty();
})
```
1181 1182 1183 1184 1185 1186 1187 1188

#### 关闭连接

在完成插入、查询等操作后,要关闭连接。代码如下:
```js
conn.close();
```

X
Xiaxin Li 已提交
1189
#### 异步函数
1190

X
Xiaxin Li 已提交
1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204
异步查询数据库的操作和上面类似,只需要在`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();
promise1.then(function(result) {
  result.pretty();
})
promise2.then(function(result) {
  result.pretty();
})
```

### 示例

1205
[node-example.js](https://github.com/taosdata/TDengine/tree/master/tests/examples/nodejs/node-example.js)提供了一个使用NodeJS 连接器建表,插入天气数据并查询插入的数据的代码示例。
1206

1207
[node-example-raw.js](https://github.com/taosdata/TDengine/tree/master/tests/examples/nodejs/node-example-raw.js)同样是一个使用NodeJS 连接器建表,插入天气数据并查询插入的数据的代码示例,但和上面不同的是,该示例只使用`cursor`