diff --git a/docs/examples/c/CCreateDBDemo.c b/docs/examples/c/CCreateDBDemo.c new file mode 100644 index 0000000000..cb655eb18d --- /dev/null +++ b/docs/examples/c/CCreateDBDemo.c @@ -0,0 +1,76 @@ +/* + * Copyright (c) 2019 TAOS Data, Inc. + * + * This program is free software: you can use, redistribute, and/or modify + * it under the terms of the GNU Affero General Public License, version 3 + * or later ("AGPL"), as published by the Free Software Foundation. + * + * This program is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see . + */ + +// TAOS standard API example. The same syntax as MySQL, but only a subset +// to compile: gcc -o CCreateDBDemo CCreateDBDemo.c -ltaos + +#include +#include +#include +#include +#include "taos.h" + + +static int DemoCreateDB() { +// ANCHOR: create_db_and_table + int ret_code = -1; + const char *ip = "localhost"; + const char *user = "root"; + const char *password = "taosdata"; + + // connect + TAOS *taos = taos_connect(ip, user, password, NULL, 0); + if (taos == NULL) { + printf("failed to connect to server, reason: %s\n", taos_errstr(NULL)); + goto end; + } + + // create database + TAOS_RES *result = taos_query(taos, "CREATE DATABASE IF NOT EXISTS power"); + int code = taos_errno(result); + if (code != 0) { + printf("failed to create database, reason: %s\n", taos_errstr(result)); + goto end; + } + taos_free_result(result); + printf("success to create database\n"); + + // use database + result = taos_query(taos, "USE power"); + taos_free_result(result); + + // create table + const char* sql = "CREATE STABLE IF NOT EXISTS meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (groupId INT, location BINARY(24))"; + result = taos_query(taos, sql); + code = taos_errno(result); + if (code != 0) { + printf("failed to create table, reason: %s\n", taos_errstr(result)); + goto end; + } + taos_free_result(result); + printf("success to create table\n"); + ret_code = 0; + +end: + // close & clean + taos_close(taos); + taos_cleanup(); + return ret_code; +// ANCHOR_END: create_db_and_table +} + +int main(int argc, char *argv[]) { + return DemoCreateDB(); +} diff --git a/docs/examples/c/CInsertDataDemo.c b/docs/examples/c/CInsertDataDemo.c new file mode 100644 index 0000000000..4ec228a6d5 --- /dev/null +++ b/docs/examples/c/CInsertDataDemo.c @@ -0,0 +1,76 @@ +/* + * Copyright (c) 2019 TAOS Data, Inc. + * + * This program is free software: you can use, redistribute, and/or modify + * it under the terms of the GNU Affero General Public License, version 3 + * or later ("AGPL"), as published by the Free Software Foundation. + * + * This program is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see . + */ + +// TAOS standard API example. The same syntax as MySQL, but only a subset +// to compile: gcc -o CInsertDataDemo CInsertDataDemo.c -ltaos + +#include +#include +#include +#include +#include "taos.h" + +static int DemoInsertData() { +// ANCHOR: insert_data + int ret_code = -1; + const char *ip = "localhost"; + const char *user = "root"; + const char *password = "taosdata"; + + // connect + TAOS *taos = taos_connect(ip, user, password, NULL, 0); + if (taos == NULL) { + printf("failed to connect to server, reason: %s\n", taos_errstr(NULL)); + goto end; + } + + // use database + TAOS_RES *result = taos_query(taos, "USE power"); + taos_free_result(result); + + // insert data, please make sure the database and table are already created + const char* sql = "INSERT INTO " \ + "power.d1001 USING power.meters TAGS(2,'California.SanFrancisco') " \ + "VALUES " \ + "(NOW + 1a, 10.30000, 219, 0.31000) " \ + "(NOW + 2a, 12.60000, 218, 0.33000) " \ + "(NOW + 3a, 12.30000, 221, 0.31000) " \ + "power.d1002 USING power.meters TAGS(3, 'California.SanFrancisco') " \ + "VALUES " \ + "(NOW + 1a, 10.30000, 218, 0.25000) "; + result = taos_query(taos, sql); + int code = taos_errno(result); + if (code != 0) { + printf("failed to insert rows, reason: %s\n", taos_errstr(result)); + goto end; + } + taos_free_result(result); + + // you can check affectedRows here + int rows = taos_affected_rows(result); + printf("success to insert %d rows\n", rows); + ret_code = 0; + +end: + // close & clean + taos_close(taos); + taos_cleanup(); + return ret_code; +// ANCHOR_END: insert_data +} + +int main(int argc, char *argv[]) { + return DemoInsertData(); +} diff --git a/docs/examples/c/CQueryDataDemo.c b/docs/examples/c/CQueryDataDemo.c new file mode 100644 index 0000000000..3b994dfae8 --- /dev/null +++ b/docs/examples/c/CQueryDataDemo.c @@ -0,0 +1,82 @@ +/* + * Copyright (c) 2019 TAOS Data, Inc. + * + * This program is free software: you can use, redistribute, and/or modify + * it under the terms of the GNU Affero General Public License, version 3 + * or later ("AGPL"), as published by the Free Software Foundation. + * + * This program is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see . + */ + +// TAOS standard API example. The same syntax as MySQL, but only a subset +// to compile: gcc -o CQueryDataDemo CQueryDataDemo.c -ltaos + +#include +#include +#include +#include +#include "taos.h" + + +static int DemoQueryData() { +// ANCHOR: query_data + int ret_code = -1; + const char *ip = "localhost"; + const char *user = "root"; + const char *password = "taosdata"; + + // connect + TAOS *taos = taos_connect(ip, user, password, NULL, 0); + if (taos == NULL) { + printf("failed to connect to server, reason: %s\n", taos_errstr(NULL)); + goto end; + } + + // use database + TAOS_RES *result = taos_query(taos, "USE power"); + taos_free_result(result); + + // query data, please make sure the database and table are already created + const char* sql = "SELECT * FROM power.meters"; + result = taos_query(taos, sql); + int code = taos_errno(result); + if (code != 0) { + printf("failed to select, reason: %s\n", taos_errstr(result)); + goto end; + } + + TAOS_ROW row = NULL; + int rows = 0; + int num_fields = taos_field_count(result); + TAOS_FIELD *fields = taos_fetch_fields(result); + + printf("fields: %d\n", num_fields); + printf("sql: %s, result:\n", sql); + + // fetch the records row by row + while ((row = taos_fetch_row(result))) { + char temp[1024] = {0}; + rows++; + taos_print_row(temp, row, fields, num_fields); + printf("%s\n", temp); + } + printf("total rows: %d\n", rows); + taos_free_result(result); + ret_code = 0; + +end: + // close & clean + taos_close(taos); + taos_cleanup(); + return ret_code; +// ANCHOR_END: query_data +} + +int main(int argc, char *argv[]) { + return DemoQueryData(); +} diff --git a/docs/examples/c/CWithReqIdDemo.c b/docs/examples/c/CWithReqIdDemo.c new file mode 100644 index 0000000000..a2055d733b --- /dev/null +++ b/docs/examples/c/CWithReqIdDemo.c @@ -0,0 +1,93 @@ +/* + * Copyright (c) 2019 TAOS Data, Inc. + * + * This program is free software: you can use, redistribute, and/or modify + * it under the terms of the GNU Affero General Public License, version 3 + * or later ("AGPL"), as published by the Free Software Foundation. + * + * This program is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see . + */ + +// TAOS standard API example. The same syntax as MySQL, but only a subset +// to compile: gcc -o CWithReqIdDemo CWithReqIdDemo.c -ltaos + +#include +#include +#include +#include +#include "taos.h" + + +static int DemoWithReqId() { +// ANCHOR: with_reqid + int ret_code = -1; + const char *ip = "localhost"; + const char *user = "root"; + const char *password = "taosdata"; + + // connect + TAOS *taos = taos_connect(ip, user, password, NULL, 0); + if (taos == NULL) { + printf("failed to connect to server, reason: %s\n", taos_errstr(NULL)); + goto end; + } + + // create database + TAOS_RES *result = taos_query_with_reqid(taos, "CREATE DATABASE IF NOT EXISTS power", 1L); + int code = taos_errno(result); + if (code != 0) { + printf("failed to create database, reason: %s\n", taos_errstr(result)); + taos_free_result(result); + goto end; + } + taos_free_result(result); + printf("success to create database\n"); + + // use database + result = taos_query_with_reqid(taos, "USE power", 2L); + taos_free_result(result); + + // query data + const char* sql = "SELECT * FROM power.meters"; + result = taos_query_with_reqid(taos, sql, 3L); + code = taos_errno(result); + if (code != 0) { + printf("failed to select, reason: %s\n", taos_errstr(result)); + goto end; + } + + TAOS_ROW row = NULL; + int rows = 0; + int num_fields = taos_field_count(result); + TAOS_FIELD *fields = taos_fetch_fields(result); + + printf("fields: %d\n", num_fields); + printf("sql: %s, result:\n", sql); + + // fetch the records row by row + while ((row = taos_fetch_row(result))) { + char temp[1024] = {0}; + rows++; + taos_print_row(temp, row, fields, num_fields); + printf("%s\n", temp); + } + printf("total rows: %d\n", rows); + taos_free_result(result); + ret_code = 0; + +end: + // close & clean + taos_close(taos); + taos_cleanup(); + return ret_code; +// ANCHOR_END: with_reqid +} + +int main(int argc, char *argv[]) { + return DemoWithReqId(); +} diff --git a/docs/zh/08-develop/01-connect/index.md b/docs/zh/08-develop/01-connect/index.md index bd738209f9..48af1f7a63 100644 --- a/docs/zh/08-develop/01-connect/index.md +++ b/docs/zh/08-develop/01-connect/index.md @@ -345,6 +345,34 @@ DSN 的详细说明和如何使用详见 [连接功能](../../reference/connecto +使用客户端驱动访问 TDengine 集群的基本过程为：建立连接、查询和写入、关闭连接、清除资源。 + +下面为建立连接的示例代码，其中省略了查询和写入部分，展示了如何建立连接、关闭连接以及清除资源。 + +```c + TAOS *taos = taos_connect("localhost:6030", "root", "taosdata", NULL, 0); + if (taos == NULL) { + printf("failed to connect to server, reason:%s\n", "null taos" /*taos_errstr(taos)*/); + exit(1); + } + + /* put your code here for read and write */ + + taos_close(taos); + taos_cleanup(); +``` + +在上面的示例代码中， `taos_connect()` 建立到客户端程序所在主机的 6030 端口的连接，`taos_close()`关闭当前连接，`taos_cleanup()`清除客户端驱动所申请和使用的资源。 + +:::note + +- 如未特别说明，当 API 的返回值是整数时，_0_ 代表成功，其它是代表失败原因的错误码，当返回值是指针时， _NULL_ 表示失败。 +- 所有的错误码以及对应的原因描述在 `taoserror.h` 文件中。 + +::: + + + diff --git a/docs/zh/08-develop/02-sql.md b/docs/zh/08-develop/02-sql.md index d4ee344c11..f24a35eb75 100644 --- a/docs/zh/08-develop/02-sql.md +++ b/docs/zh/08-develop/02-sql.md @@ -41,6 +41,10 @@ TDengine 对 SQL 语言提供了全面的支持，允许用户以熟悉的 SQL +```c +{{#include docs/examples/c/CCreateDBDemo.c:create_db_and_table}} +``` +> **注意**：如果不使用 `USE power` 指定数据库，则后续对表的操作都需要增加数据库名称作为前缀，如 power.meters。 @@ -77,6 +81,12 @@ NOW 为系统内部函数，默认为客户端所在计算机当前时间。 NOW +```c +{{#include docs/examples/c/CInsertDataDemo.c:insert_data}} +``` + +**Note** +NOW 为系统内部函数，默认为客户端所在计算机当前时间。 NOW + 1s 代表客户端当前时间往后加 1 秒，数字后面代表时间单位：a（毫秒），s（秒），m（分），h（小时），d（天），w（周），n（月），y（年）。 @@ -111,6 +121,9 @@ NOW 为系统内部函数，默认为客户端所在计算机当前时间。 NOW +```c +{{#include docs/examples/c/CQueryDataDemo.c:query_data}} +``` @@ -153,6 +166,9 @@ reqId 可用于请求链路追踪，reqId 就像分布式系统中的 traceId +```c +{{#include docs/examples/c/CWithReqIdDemo.c:with_reqid}} +``` diff --git a/docs/zh/14-reference/05-connector/10-cpp.mdx b/docs/zh/14-reference/05-connector/10-cpp.mdx index d4761ee5c4..2e7a53a464 100644 --- a/docs/zh/14-reference/05-connector/10-cpp.mdx +++ b/docs/zh/14-reference/05-connector/10-cpp.mdx @@ -224,131 +224,161 @@ int taos_print_row(char *str, TAOS_ROW row, TAOS_FIELD *fields, int num_fields) 基础 API 用于完成创建数据库连接等工作，为其它 API 的执行提供运行时环境。 - `int taos_init()` - - 初始化运行环境。如果没有主动调用该 API，那么调用 `taos_connect()` 时驱动将自动调用该 API，故程序一般无需手动调用。 + - **接口说明**：初始化运行环境。如果没有主动调用该 API，那么调用 `taos_connect()` 时驱动将自动调用该 API，故程序一般无需手动调用。 + - **返回值**：待补充，未找到相关资料。 - `void taos_cleanup()` - - 清理运行环境，应用退出前应调用。 + - **接口说明**：清理运行环境，应用退出前应调用。 - `int taos_options(TSDB_OPTION option, const void * arg, ...)` - - 设置客户端选项，目前支持区域设置（`TSDB_OPTION_LOCALE`）、字符集设置（`TSDB_OPTION_CHARSET`）、时区设置（`TSDB_OPTION_TIMEZONE`）、配置文件路径设置（`TSDB_OPTION_CONFIGDIR`）。区域设置、字符集、时区默认为操作系统当前设置。 + - **接口说明**：设置客户端选项，目前支持区域设置（`TSDB_OPTION_LOCALE`）、字符集设置（`TSDB_OPTION_CHARSET`）、时区设置（`TSDB_OPTION_TIMEZONE`）、配置文件路径设置（`TSDB_OPTION_CONFIGDIR`）。区域设置、字符集、时区默认为操作系统当前设置。 + - **参数说明**： + - `option`：[入参] 设置项类型。 + - `arg`：[入参] 设置项值。 + - **返回值**：`0`：成功，`-1`：失败。 - `char *taos_get_client_info()` + - **接口说明**：获取客户端版本信息。 + - **返回值**：返回客户端版本信息。 - 获取客户端版本信息。 - -- `TAOS *taos_connect(const char *host, const char *user, const char *pass, const char *db, int port)` - - 创建数据库连接，初始化连接上下文。其中需要用户提供的参数包含： - - - host：TDengine 集群中任一节点的 FQDN - - user：用户名 - - pass：密码 - - db： 数据库名字，如果用户没有提供，也可以正常连接，用户可以通过该连接创建新的数据库，如果用户提供了数据库名字，则说明该数据库用户已经创建好，缺省使用该数据库 - - port：taosd 程序监听的端口 - - 返回值为空表示失败。应用程序需要保存返回的参数，以便后续使用。 - +- `TAOS *taos_connect(const char *ip, const char *user, const char *pass, const char *db, uint16_t port);` + - **接口说明**：创建数据库连接，初始化连接上下文。 + - **参数说明**： + - ip：[入参] TDengine 集群中任一节点的 FQDN。 + - user：[入参] 用户名。 + - pass：[入参] 密码。 + - db：[入参] 数据库名字，如果用户没有提供，也可以正常连接，用户可以通过该连接创建新的数据库，如果用户提供了数据库名字，则说明该数据库用户已经创建好，缺省使用该数据库。 + - port：[入参] taosd 程序监听的端口。 + - **返回值**：返回数据库连接，返回值为空表示失败。应用程序需要保存返回的参数，以便后续使用。 :::info 同一进程可以根据不同的 host/port 连接多个 TDengine 集群 - ::: - `TAOS *taos_connect_auth(const char *host, const char *user, const char *auth, const char *db, uint16_t port)` - - 功能同 taos_connect。除 pass 参数替换为 auth 外，其他参数同 taos_connect。 - - - auth: 原始密码取 32 位小写 md5 + - **接口说明**：功能同 taos_connect。除 pass 参数替换为 auth 外，其他参数同 taos_connect。 + - **参数说明**： + - ip：[入参] TDengine 集群中任一节点的 FQDN。 + - user：[入参] 用户名。 + - auth: [入参] 原始密码取 32 位小写 md5。 + - db：[入参] 数据库名称，如果用户没有提供，也可以正常连接，用户可以通过该连接创建新的数据库，如果用户提供了数据库名字，则说明该数据库用户已经创建好，缺省使用该数据库。 + - port：[入参] taosd 程序监听的端口。 + - **返回值**：返回数据库连接，返回值为空表示失败。应用程序需要保存返回的参数，以便后续使用。 - `char *taos_get_server_info(TAOS *taos)` - - 获取服务端版本信息。 + - **接口说明**：获取服务端版本信息。 + - **参数说明**： + - taos：[入参] 数据库连接。 + - **返回值**：返回获取服务端版本信息。 - `int taos_select_db(TAOS *taos, const char *db)` + - **接口说明**：将当前的缺省数据库设置为 `db`。 + - **参数说明**： + - taos：[入参] 数据库连接。 + - db：[入参] 数据库名称。 + - **返回值**：`0`：成功，`非0`：失败，详情请参考错误码。待补充。 - 将当前的缺省数据库设置为 `db`。 - - `int taos_get_current_db(TAOS *taos, char *database, int len, int *required)` - - - database，len为用户在外面申请的空间，内部会把当前db赋值到database里。 - - 只要是没有正常把db名赋值到database中（包括截断），返回错误，返回值为-1，然后用户可以通过 taos_errstr(NULL) 来获取错误提示。 - - 如果，database == NULL 或者 len\<=0 返回错误，required里保存存储db需要的空间（包含最后的'\0'） - - 如果，len 小于 存储db需要的空间（包含最后的'\0'），返回错误，database里赋值截断的数据，以'\0'结尾。 - - 如果，len 大于等于 存储db需要的空间（包含最后的'\0'），返回正常0，database里赋值以'\0‘结尾的db名。 + - **接口说明**：获取当前数据库名称。 + - **参数说明**： + - taos：[入参] 数据库连接。 + - database：[出参] 存储当前数据库名称。 + - len：[入参] database 的空间大小。 + - required：[出参] 存储当前数据库名称所需的空间（包含最后的'\0'）。 + - **返回值**：`0`：成功，`-1`：失败，详情请调用 taos_errstr(NULL) 函数来获取错误提示。 + - 如果，database == NULL 或者 len\<=0 返回失败。 + - 如果，len 小于 存储数据库名称所需的空间（包含最后的'\0'），返回失败，database 里赋值截断的数据，以'\0'结尾。 + - 如果，len 大于等于 存储数据库名称所需的空间（包含最后的'\0'），返回成功，database 里赋值以'\0‘结尾数据库名称。 - `int taos_set_notify_cb(TAOS *taos, __taos_notify_fn_t fp, void *param, int type)` - - 设置事件回调函数。 - - - fp 事件回调函数指针。函数声明：typedef void (*__taos_notify_fn_t)(void *param, void *ext, int type)；其中， param 为用户自定义参数，ext 为扩展参数(依赖事件类型，针对 TAOS_NOTIFY_PASSVER 返回用户密码版本)，type 为事件类型 - - param 用户自定义参数 - - type 事件类型。取值范围：1）TAOS_NOTIFY_PASSVER： 用户密码改变 + - **接口说明**：设置事件回调函数。 + - **参数说明**： + - taos：[入参] 数据库连接。 + - fp：[入参] 事件回调函数指针。函数声明：typedef void (*__taos_notify_fn_t)(void *param, void *ext, int type)；其中， param 为用户自定义参数，ext 为扩展参数(依赖事件类型，针对 TAOS_NOTIFY_PASSVER 返回用户密码版本)，type 为事件类型。 + - param：[入参] 用户自定义参数。 + - type：[入参] 事件类型。取值范围：1）TAOS_NOTIFY_PASSVER： 用户密码改变。 + - **返回值**：`0`：成功，`-1`：失败，详情请调用 taos_errstr(NULL) 函数来获取错误提示。 - `void taos_close(TAOS *taos)` - - 关闭连接，其中`taos`是 `taos_connect()` 返回的句柄。 + - **接口说明**：关闭连接。 + - **参数说明**： + - taos：[入参] 数据库连接。 ### 同步查询 API 本小节介绍 API 均属于同步接口。应用调用后，会阻塞等待响应，直到获得返回结果或错误信息。 - `TAOS_RES* taos_query(TAOS *taos, const char *sql)` - - 执行 SQL 语句，可以是 DQL、DML 或 DDL 语句。 其中的 `taos` 参数是通过 `taos_connect()` 获得的句柄。不能通过返回值是否是 `NULL` 来判断执行结果是否失败，而是需要用 `taos_errno()` 函数解析结果集中的错误代码来进行判断。 + - **接口说明**：执行 SQL 语句，可以是 DQL、DML 或 DDL 语句。 + - **参数说明**： + - taos：[入参] 数据库连接。 + - sql：[入参] 需要执行 SQL 语句。 + - **返回值**：不能通过返回值是否是 `NULL` 来判断执行结果是否失败，而是需要调用 `taos_errno()` 函数解析结果集中的错误代码来进行判断。 + - taos_errno 返回值：`0`：成功，`-1`：失败，详情请调用 taos_errstr 函数来获取错误提示。 - `int taos_result_precision(TAOS_RES *res)` - - 返回结果集时间戳字段的精度，`0` 代表毫秒，`1` 代表微秒，`2` 代表纳秒。 + - **接口说明**：返回结果集时间戳字段的精度类别。 + - **参数说明**： + - res：[入参] 结果集。 + - **返回值**：`0`：毫秒，`1`：微秒，`2`：纳秒。 - `TAOS_ROW taos_fetch_row(TAOS_RES *res)` - - 按行获取查询结果集中的数据。 + - **接口说明**：按行获取查询结果集中的数据。 + - **参数说明**： + - res：[入参] 查询结果集。 + - **返回值**：`非NULL`：成功，`NULL`：失败，详情请调用 taos_errstr(NULL) 函数来获取错误提示。 - `int taos_fetch_block(TAOS_RES *res, TAOS_ROW *rows)` - - 批量获取查询结果集中的数据，返回值为获取到的数据的行数。 + - **接口说明**：批量获取查询结果集中的数据。 + - **参数说明**： + - res：[入参] 查询结果集。 + - rows：[出参] 用于存储从结果集中获取的行。 + - **返回值**：返回值为获取到的数据的行数，如果没有更多的行则返回 0。 - `int taos_num_fields(TAOS_RES *res)` 和 `int taos_field_count(TAOS_RES *res)` - - 这两个 API 等价，用于获取查询结果集中的列数。 + - **接口说明**：这两个 API 等价，用于获取查询结果集中的列数。 + - **参数说明**： + - res：[入参] 查询结果集。 + - **返回值**：返回值为结果集中列的数量。 - `int* taos_fetch_lengths(TAOS_RES *res)` - - 获取结果集中每个字段的长度。返回值是一个数组，其长度为结果集的列数。 + - **接口说明**：获取结果集中每个字段的长度。 + - **参数说明**： + - res：[入参] 结果集。 + - **返回值**：返回值是一个数组，其长度为结果集的列数。 - `int taos_affected_rows(TAOS_RES *res)` - - 获取被所执行的 SQL 语句影响的行数。 + - **接口说明**：获取被所执行的 SQL 语句影响的行数。 + - **参数说明**： + - res：[入参] 结果集。 + - **返回值**：返回值表示受影响的行数。 - `TAOS_FIELD *taos_fetch_fields(TAOS_RES *res)` - - 获取查询结果集每列数据的属性（列的名称、列的数据类型、列的长度），与 `taos_num_fields()` 配合使用，可用来解析 `taos_fetch_row()` 返回的一个元组(一行)的数据。 `TAOS_FIELD` 的结构如下： - -```c -typedef struct taosField { - char name[65]; // column name - uint8_t type; // data type - int16_t bytes; // length, in bytes -} TAOS_FIELD; -``` + - **接口说明**：获取查询结果集每列数据的属性（列的名称、列的数据类型、列的长度），与 `taos_num_fields()` 配合使用，可用来解析 `taos_fetch_row()` 返回的一个元组(一行)的数据。 + - **参数说明**： + - res：[入参] 查询结果集。 + - **返回值**：`非NULL`：成功，返回一个指向 TAOS_FIELD 结构体的指针，每个元素代表一列的元数据。`NULL`：失败。 - `void taos_stop_query(TAOS_RES *res)` - - 停止当前查询的执行。 + - **接口说明**：停止当前查询的执行。 + - **参数说明**： + - res：[入参] 查询结果集。 - `void taos_free_result(TAOS_RES *res)` - - 释放查询结果集以及相关的资源。查询完成后，务必调用该 API 释放资源，否则可能导致应用内存泄露。但也需注意，释放资源后，如果再调用 `taos_consume()` 等获取查询结果的函数，将导致应用崩溃。 + - **接口说明**：释放查询结果集以及相关的资源。查询完成后，务必调用该 API 释放资源，否则可能导致应用内存泄露。但也需注意，释放资源后，如果再调用 `taos_consume()` 等获取查询结果的函数，将导致应用崩溃。 + - **参数说明**： + - res：[入参] 查询结果集。 - `char *taos_errstr(TAOS_RES *res)` - - 获取最近一次 API 调用失败的原因,返回值为字符串标识的错误提示信息。 + - **接口说明**：获取最近一次 API 调用失败的原因，返回值为字符串标识的错误提示信息。 + - **参数说明**： + - res：[入参] 结果集。 + - **返回值**：字符串标识的错误提示信息。 - `int taos_errno(TAOS_RES *res)` - - 获取最近一次 API 调用失败的原因，返回值为错误代码。 + - **接口说明**：获取最近一次 API 调用失败的原因，返回值为错误代码。 + - **参数说明**： + - res：[入参] 结果集。 + - **返回值**：字符串标识的错误提示信息。 :::note 2.0 及以上版本 TDengine 推荐数据库应用的每个线程都建立一个独立的连接，或基于线程建立连接池。而不推荐在应用中将该连接 (TAOS\*) 结构体传递到不同的线程共享使用。基于 TAOS 结构体发出的查询、写入等操作具有多线程安全性，但 “USE statement” 等状态量有可能在线程之间相互干扰。此外，C 语言的连接器可以按照需求动态建立面向数据库的新连接（该过程对用户不可见），同时建议只有在程序最后退出的时候才调用 `taos_close()` 关闭连接。 @@ -365,20 +395,18 @@ TDengine 还提供性能更高的异步 API 处理数据插入、查询操作。 异步 API 对于使用者的要求相对较高，用户可根据具体应用场景选择性使用。下面是两个重要的异步 API： - `void taos_query_a(TAOS *taos, const char *sql, void (*fp)(void *param, TAOS_RES *, int code), void *param);` - - 异步执行 SQL 语句。 - - - taos：调用 `taos_connect()` 返回的数据库连接 - - sql：需要执行的 SQL 语句 - - fp：用户定义的回调函数，其第三个参数 `code` 用于指示操作是否成功，`0` 表示成功，负数表示失败（调用 `taos_errstr()` 可获取失败原因）。应用在定义回调函数的时候，主要处理第二个参数 `TAOS_RES *`，该参数是查询返回的结果集 - - param：应用提供一个用于回调的参数 + - **接口说明**：异步执行 SQL 语句。 + - **参数说明**： + - taos：[入参] 数据库连接。 + - sql: [入参] 需要执行的 SQL 语句。 + - 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()` 配合使用。其中： - - - res：`taos_query_a()` 回调时返回的结果集 - - fp：回调函数。其参数 `param` 是用户可定义的传递给回调函数的参数结构体；`numOfRows` 是获取到的数据的行数（不是整个查询结果集的函数）。 在回调函数中，应用可以通过调用 `taos_fetch_row()` 前向迭代获取批量记录中每一行记录。读完一块内的所有记录后，应用需要在回调函数中继续调用 `taos_fetch_rows_a()` 获取下一批记录进行处理，直到返回的记录数 `numOfRows` 为零（结果返回完成）或记录数为负值（查询出错）。 + - **接口说明**： 批量获取异步查询的结果集，只能与 `taos_query_a()` 配合使用。 + - **参数说明**： + - res：`taos_query_a()` 回调时返回的结果集。 + - fp：回调函数。其参数 `param` 是用户可定义的传递给回调函数的参数结构体；`numOfRows` 是获取到的数据的行数（不是整个查询结果集的函数）。 在回调函数中，应用可以通过调用 `taos_fetch_row()` 前向迭代获取批量记录中每一行记录。读完一块内的所有记录后，应用需要在回调函数中继续调用 `taos_fetch_rows_a()` 获取下一批记录进行处理，直到返回的记录数 `numOfRows` 为零（结果返回完成）或记录数为负值（查询出错）。 TDengine 的异步 API 均采用非阻塞调用模式。应用程序可以用多线程同时打开多张表，并可以同时对每张打开的表进行查询或者插入操作。需要指出的是，**客户端应用必须确保对同一张表的操作完全串行化**，即对同一个表的插入或查询操作未完成时（未返回时），不能够执行第二个插入或查询操作。