Skip to content

TDengine
TDengine

taosdata / TDengine
1 年多 前同步成功

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

docs: refine cpp connector (#11862) 

* docs: refine connector doc

[TD-14839]

* docs: use TDengine CLI

[TD-14839]

* docs: replace JNI with navtive connection

[TD-14839]

* docs: make connectors doc use same preparition

[TD-14839]

* docs: refine connectors doc

[TD-14839]

* docs: refine connectors doc

[TD-14839]

* docs: refine connector docs

* docs: refine connector doc

[TD-14839]

* docs: refine connector doc

[TD-14839]

* docs: refine connector

[TD-14839]

* docs: fix faq path

* docs: refine cpp connector doc

* docs: refine cpp docs

* docs: fix java preparition

* docs: refine connector docs

* docs: refine connector docs

[TD-14839]

* docs: refine connector doc

[TD-14839]

* docs: refine connector docs

[TD-14839]

* docs: fix node.mdx

[TD-14839]

* docs: refine connector

[TD-14839]

* docs: refine cpp connector

[TD-14839]
上级 53dd6499
隐藏空白更改
内联 并排
Showing with 38 addition and 60 deletion
docs-cn/14-reference/03-connector/03-connector.mdx
浏览文件 @ b80282ba
......@@ -2,7 +2,7 @@
title: 连接器
---
TDengine 提供了丰富的应用程序开发接口，为了便于用户快速开发自己的应用，TDengine 支持了多种编程语言的连接器，其中官方连接器包括支持 C/C++、Java、Python、Go、Node.js、C# 和 Rust 的连接器。这些连接器支持使用原生接口（taosc）和 REST 接口（部分语言暂不支持）连接 TDengine 集群。社区开发者也贡献了多个非官方连接器，例如 Lua 连接器和 PHP 连接器。
TDengine 提供了丰富的应用程序开发接口，为了便于用户快速开发自己的应用，TDengine 支持了多种编程语言的连接器，其中官方连接器包括支持 C/C++、Java、Python、Go、Node.js、C# 和 Rust 的连接器。这些连接器支持使用原生接口（taosc）和 REST 接口（部分语言暂不支持）连接 TDengine 集群。社区开发者也贡献了多个非官方连接器，例如 ADO.NET 连接器、Lua 连接器和 PHP 连接器。
![image-connector](/img/connector.png)
......
docs-cn/14-reference/03-connector/_linux_install.mdx
浏览文件 @ b80282ba
......@@ -12,7 +12,6 @@
- _ install_client.sh_：安装脚本，用于应用驱动程序
- _ taos.tar.gz_：应用驱动安装包
- _ driver_：TDengine 应用驱动 driver
- _connector_: 各种编程语言连接器（go/nodejs/python/JDBC）
- _examples_: 各种编程语言的示例程序(c/C#/go/JDBC/MATLAB/python/R)
运行 install_client.sh 进行安装。
4. 配置 taos.cfg
......
docs-cn/14-reference/03-connector/cpp.mdx
浏览文件 @ b80282ba
......@@ -24,13 +24,13 @@ TDengine 服务端或客户端安装后，taos.h 位于：
注意：
- 在编译时需要链接 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 中有所有的错误码，以及对应的原因描述。
- 所有的错误码以及对应的原因描述在 taoserror.h 文件中。
## 示例程序
使用 C/C++连接器的示例代码请参见 https://github.com/taosdata/TDengine/tree/develop/examples/c 。
使用 C/C++ 连接器的示例代码请参见 https://github.com/taosdata/TDengine/tree/develop/examples/c。
示例程序源码也可以在安装目录下的 examples/c 路径下找到：
......@@ -40,7 +40,7 @@ TDengine 服务端或客户端安装后，taos.h 位于：
在一台机器上启动 TDengine 服务，执行这些示例程序，按照提示输入 TDengine 服务的 FQDN，就可以正常运行，并打印出信息。
**提示：**在 ARM 环境下编译时，请将 makefile 中的-msse4.2 去掉，这个选项只有在 x64/x86 硬件平台上才能支持。
**提示：**在 ARM 环境下编译时，请将 makefile 中的 `-msse4.2` 去掉，这个选项只有在 x64/x86 硬件平台上才能支持。
## 基础 API
......@@ -48,7 +48,7 @@ TDengine 服务端或客户端安装后，taos.h 位于：
- `void taos_init()`
初始化运行环境。如果应用没有主动调用该 API，那么应用在调用`taos_connect`时将自动调用，故应用程序一般无需手动调用该 API。
初始化运行环境。如果应用没有主动调用该 API，那么应用在调用`taos_connect()`时将自动调用，故应用程序一般无需手动调用该 API。
- `void taos_cleanup()`
......@@ -85,7 +85,7 @@ TDengine 服务端或客户端安装后，taos.h 位于：
- `int taos_select_db(TAOS *taos, const char *db)`
将当前的缺省数据库设置为`db`。
将当前的缺省数据库设置为 `db`。
- `void taos_close(TAOS *taos)`
......@@ -97,7 +97,7 @@ TDengine 服务端或客户端安装后，taos.h 位于：
- `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)`
......@@ -117,7 +117,7 @@ TDengine 服务端或客户端安装后，taos.h 位于：
- `int* taos_fetch_lengths(TAOS_RES *res)`
获取结果集中每个字段的长度。 返回值是一个数组，其长度为结果集的列数。
获取结果集中每个字段的长度。返回值是一个数组，其长度为结果集的列数。
- `int taos_affected_rows(TAOS_RES *res)`
......@@ -125,7 +125,7 @@ TDengine 服务端或客户端安装后，taos.h 位于：
- `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 {
......@@ -141,7 +141,7 @@ typedef struct taosField {
- `void taos_free_result(TAOS_RES *res)`
释放查询结果集以及相关的资源。查询完成后，务必调用该 API 释放资源，否则可能导致应用内存泄露。但也需注意，释放资源后，如果再调用`taos_consume`等获取查询结果的函数，将导致应用 Crash。
释放查询结果集以及相关的资源。查询完成后，务必调用该 API 释放资源，否则可能导致应用内存泄露。但也需注意，释放资源后，如果再调用 `taos_consume()` 等获取查询结果的函数，将导致应用崩溃。
- `char *taos_errstr(TAOS_RES *res)`
......@@ -152,7 +152,7 @@ typedef struct taosField {
获取最近一次 API 调用失败的原因，返回值为错误代码。
:::note
2.0 及以上版本 TDengine 推荐数据库应用的每个线程都建立一个独立的连接，或基于线程建立连接池。而不推荐在应用中将该连接 (TAOS\*) 结构体传递到不同的线程共享使用。基于 TAOS 结构体发出的查询、写入等操作具有多线程安全性，但 “USE statement” 等状态量有可能在线程之间相互干扰。此外，C 语言的连接器可以按照需求动态建立面向数据库的新连接（该过程对用户不可见），同时建议只有在程序最后退出的时候才调用 taos_close 关闭连接。
2.0 及以上版本 TDengine 推荐数据库应用的每个线程都建立一个独立的连接，或基于线程建立连接池。而不推荐在应用中将该连接 (TAOS\*) 结构体传递到不同的线程共享使用。基于 TAOS 结构体发出的查询、写入等操作具有多线程安全性，但 “USE statement” 等状态量有可能在线程之间相互干扰。此外，C 语言的连接器可以按照需求动态建立面向数据库的新连接（该过程对用户不可见），同时建议只有在程序最后退出的时候才调用 `taos_close()` 关闭连接。
:::
......@@ -168,37 +168,37 @@ typedef struct taosField {
异步执行 SQL 语句。
- taos：调用 taos_connect 返回的数据库连接
- taos：调用 `taos_connect()` 返回的数据库连接
- sql：需要执行的 SQL 语句
- fp：用户定义的回调函数，其第三个参数`code`用于指示操作是否成功，`0`表示成功，负数表示失败(调用`taos_errstr`获取失败原因)。应用在定义回调函数的时候，主要处理第二个参数`TAOS_RES *`，该参数是查询返回的结果集
- fp：用户定义的回调函数，其第三个参数 `code` 用于指示操作是否成功，`0` 表示成功，负数表示失败(调用 `taos_errstr()` 获取失败原因)。应用在定义回调函数的时候，主要处理第二个参数 `TAOS_RES *`，该参数是查询返回的结果集
- param：应用提供一个用于回调的参数
- `void taos_fetch_rows_a(TAOS_RES *res, void (*fp)(void *param, TAOS_RES *, int numOfRows), void *param);`
批量获取异步查询的结果集，只能与`taos_query_a`配合使用。其中：
批量获取异步查询的结果集，只能与 `taos_query_a()` 配合使用。其中：
- res：`taos_query_a`回调时返回的结果集
- fp：回调函数。其参数`param`是用户可定义的传递给回调函数的参数结构体；`numOfRows`是获取到的数据的行数（不是整个查询结果集的函数）。 在回调函数中，应用可以通过调用`taos_fetch_row`前向迭代获取批量记录中每一行记录。读完一块内的所有记录后，应用需要在回调函数中继续调用`taos_fetch_rows_a`获取下一批记录进行处理，直到返回的记录数（numOfRows）为零（结果返回完成）或记录数为负值（查询出错）。
- res：`taos_query_a()` 回调时返回的结果集
- fp：回调函数。其参数`param`是用户可定义的传递给回调函数的参数结构体；`numOfRows`是获取到的数据的行数（不是整个查询结果集的函数）。 在回调函数中，应用可以通过调用 `taos_fetch_row()` 前向迭代获取批量记录中每一行记录。读完一块内的所有记录后，应用需要在回调函数中继续调用`taos_fetch_rows_a`获取下一批记录进行处理，直到返回的记录数（numOfRows）为零（结果返回完成）或记录数为负值（查询出错）。
TDengine 的异步 API 均采用非阻塞调用模式。应用程序可以用多线程同时打开多张表，并可以同时对每张打开的表进行查询或者插入操作。需要指出的是，**客户端应用必须确保对同一张表的操作完全串行化**，即对同一个表的插入或查询操作未完成时（未返回时），不能够执行第二个插入或查询操作。
## 参数绑定 API
除了直接调用 `taos_query` 进行查询，TDengine 也提供了支持参数绑定的 Prepare API，与 MySQL 一样，这些 API 目前也仅支持用问号 `?` 来代表待绑定的参数。文档中有时也会把此功能称为“原生接口写入”。
除了直接调用 `taos_query()` 进行查询，TDengine 也提供了支持参数绑定的 Prepare API，风格与 MySQL 类似，目前也仅支持用问号 `?` 来代表待绑定的参数。文档中有时也会把此功能称为“原生接口写入”。
从 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 的值；
5. 调用 `taos_stmt_bind_param_batch` 以多列的方式设置 VALUES 的值，或者调用 `taos_stmt_bind_param` 以单行的方式设置 VALUES 的值；
6. 调用 `taos_stmt_add_batch` 把当前绑定的参数加入批处理；
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 的值；
5. 调用 `taos_stmt_bind_param_batch()` 以多列的方式设置 VALUES 的值，或者调用 `taos_stmt_bind_param()` 以单行的方式设置 VALUES 的值；
6. 调用 `taos_stmt_add_batch()` 把当前绑定的参数加入批处理；
7. 可以重复第 3 ～ 6 步，为批处理加入更多的数据行；
8. 调用 `taos_stmt_execute` 执行已经准备好的批处理指令；
9. 执行完毕，调用 `taos_stmt_close` 释放所有资源。
8. 调用 `taos_stmt_execute()` 执行已经准备好的批处理指令；
9. 执行完毕，调用 `taos_stmt_close()` 释放所有资源。
说明：如果 `taos_stmt_execute` 执行成功，假如不需要改变 SQL 语句的话，那么是可以复用 `taos_stmt_prepare` 的解析结果，直接进行第 3 ～ 6 步绑定新数据的。但如果执行出错，那么并不建议继续在当前的环境上下文下继续工作，而是建议释放资源，然后从 `taos_stmt_init` 步骤重新开始。
说明：如果 `taos_stmt_execute()` 执行成功，假如不需要改变 SQL 语句的话，那么是可以复用 `taos_stmt_prepare()` 的解析结果，直接进行第 3 ～ 6 步绑定新数据的。但如果执行出错，那么并不建议继续在当前的环境上下文下继续工作，而是建议释放资源，然后从 `taos_stmt_init()` 步骤重新开始。
接口相关的具体函数如下（也可以参考 [prepare.c](https://github.com/taosdata/TDengine/blob/develop/examples/c/prepare.c) 文件中使用对应函数的方式）：
......@@ -212,15 +212,15 @@ TDengine 的异步 API 均采用非阻塞调用模式。应用程序可以用多
- `int taos_stmt_bind_param(TAOS_STMT *stmt, TAOS_BIND *bind)`
不如 `taos_stmt_bind_param_batch` 效率高，但可以支持非 INSERT 类型的 SQL 语句。
进行参数绑定，bind 指向一个数组（代表所要绑定的一行数据），需保证此数组中的元素数量和顺序与 SQL 语句中的参数完全一致。TAOS_BIND 的使用方法与 MySQL 中的 MYSQL_BIND 一致，具体定义如下：
不如 `taos_stmt_bind_param_batch()` 效率高，但可以支持非 INSERT 类型的 SQL 语句。
进行参数绑定，bind 指向一个数组（代表所要绑定的一行数据），需保证此数组中的元素数量和顺序与 SQL 语句中的参数完全一致。TAOS_BIND 的使用方法与 MySQL 中的 MYSQL_BIND 类似，具体定义如下：
```c
typedef struct TAOS_BIND {
int buffer_type;
void * buffer;
unsigned long buffer_length; // 未实际使用
unsigned long *length;
uintptr_t buffer_length; // 未实际使用
uintptr_t * length;
int * is_null;
int is_unsigned; // 未实际使用
int * error; // 未实际使用
......@@ -247,7 +247,7 @@ TDengine 的异步 API 均采用非阻塞调用模式。应用程序可以用多
int buffer_type;
void * buffer;
uintptr_t buffer_length;
int32_t * length;
uintptr_t * length;
char * is_null;
int num; // 列的个数，即 buffer 中的参数个数
} TAOS_MULTI_BIND;
......@@ -255,7 +255,7 @@ TDengine 的异步 API 均采用非阻塞调用模式。应用程序可以用多
- `int taos_stmt_add_batch(TAOS_STMT *stmt)`
将当前绑定的参数加入批处理中，调用此函数后，可以再次调用 `taos_stmt_bind_param` 或 `taos_stmt_bind_param_batch` 绑定新的参数。需要注意，此函数仅支持 INSERT/IMPORT 语句，如果是 SELECT 等其他 SQL 语句，将返回错误。
将当前绑定的参数加入批处理中，调用此函数后，可以再次调用 `taos_stmt_bind_param()` 或 `taos_stmt_bind_param_batch()` 绑定新的参数。需要注意，此函数仅支持 INSERT/IMPORT 语句，如果是 SELECT 等其他 SQL 语句，将返回错误。
- `int taos_stmt_execute(TAOS_STMT *stmt)`
......@@ -263,7 +263,7 @@ TDengine 的异步 API 均采用非阻塞调用模式。应用程序可以用多
- `TAOS_RES* taos_stmt_use_result(TAOS_STMT *stmt)`
获取语句的结果集。结果集的使用方式与非参数化调用时一致，使用完成后，应对此结果集调用 `taos_free_result` 以释放资源。
获取语句的结果集。结果集的使用方式与非参数化调用时一致，使用完成后，应对此结果集调用 `taos_free_result()` 以释放资源。
- `int taos_stmt_close(TAOS_STMT *stmt)`
......@@ -291,8 +291,8 @@ TDengine 的异步 API 均采用非阻塞调用模式。应用程序可以用多
precision：文本数据中的时间戳精度字符串。
**返回值**
TAOS_RES 结构体，应用可以通过使用 taos_errstr 获得错误信息，也可以使用 taos_errno 获得错误码。
在某些情况下，返回的 TAOS_RES 为 NULL，此时仍然可以调用 taos_errno 来安全地获得错误码信息。
TAOS_RES 结构体，应用可以通过使用 `taos_errstr()` 获得错误信息，也可以使用 `taos_errno()` 获得错误码。
在某些情况下，返回的 TAOS_RES 为 NULL，此时仍然可以调用 `taos_errno()` 来安全地获得错误码信息。
返回的 TAOS_RES 需要调用方来负责释放，否则会出现内存泄漏。
**说明**
......@@ -349,27 +349,6 @@ TDengine 的异步 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 用来创建数据流，其中：
- taos：已经建立好的数据库连接。
- sql：SQL 查询语句（仅能使用查询语句）。
- fp：用户定义的回调函数指针，每次流式计算完成后，TDengine 将查询的结果（TAOS_ROW）、查询状态（TAOS_RES）、用户定义参数（PARAM）传递给回调函数，在回调函数内，用户可以使用 taos_num_fields 获取结果集列数，taos_fetch_fields 获取结果集每列数据的类型。
- stime：是流式计算开始的时间。如果是“64 位整数最小值”，表示从现在开始；如果不为“64 位整数最小值”，表示从指定的时间开始计算（UTC 时间从 1970/1/1 算起的毫秒数）。
- param：是应用提供的用于回调的一个参数，回调时，提供给应用。
- callback: 第二个回调函数，会在连续查询自动停止时被调用。
返回值为 NULL，表示创建失败；返回值不为空，表示成功。
- `void taos_close_stream (TAOS_STREAM *tstr)`
关闭数据流，其中提供的参数是 taos_open_stream 的返回值。用户停止流式计算的时候，务必关闭该数据流。
## 数据订阅接口
订阅 API 目前支持订阅一张或多张表，并通过定期轮询的方式不断获取写入表中的最新数据。
......@@ -402,7 +381,7 @@ TDengine 提供时间驱动的实时流式计算 API。可以每隔一指定的
- `TAOS_RES *taos_consume(TAOS_SUB *tsub)`
同步模式下，该函数用来获取订阅的结果。 用户应用程序将其置于一个循环之中。 如两次调用`taos_consume`的间隔小于订阅的轮询周期，API 将会阻塞，直到时间间隔超过此周期。 如果数据库有新记录到达，该 API 将返回该最新的记录，否则返回一个没有记录的空结果集。 如果返回值为 `NULL`，说明系统出错。 异步模式下，用户程序不应调用此 API。
同步模式下，该函数用来获取订阅的结果。 用户应用程序将其置于一个循环之中。 如两次调用 `taos_consume()` 的间隔小于订阅的轮询周期，API 将会阻塞，直到时间间隔超过此周期。如果数据库有新记录到达，该 API 将返回该最新的记录，否则返回一个没有记录的空结果集。 如果返回值为 `NULL`，说明系统出错。 异步模式下，用户程序不应调用此 API。
:::note
在调用 `taos_consume()` 之后，用户应用应确保尽快调用 `taos_fetch_row()` 或 `taos_fetch_block()` 来处理订阅结果，否则服务端会持续缓存查询结果数据等待客户端读取，极端情况下会导致服务端内存消耗殆尽，影响服务稳定性。
......@@ -411,4 +390,4 @@ TDengine 提供时间驱动的实时流式计算 API。可以每隔一指定的
- `void taos_unsubscribe(TAOS_SUB *tsub, int keepProgress)`
取消订阅。 如参数 `keepProgress` 不为 0，API 会保留订阅的进度信息，后续调用 `taos_subscribe` 时可以基于此进度继续；否则将删除进度信息，后续只能重新开始读取数据。
取消订阅。 如参数 `keepProgress` 不为 0，API 会保留订阅的进度信息，后续调用 `taos_subscribe()` 时可以基于此进度继续；否则将删除进度信息，后续只能重新开始读取数据。
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或