C/C++ Connector

C/C++ 开发人员可以使用 TDengine TSDB 客户端驱动（即 C/C++ 连接器）开发自己的应用来连接 TDengine TSDB 集群，完成数据存储、查询以及其他功能。TDengine TSDB 客户端驱动的 API 类似于 MySQL 的 C API。应用程序使用时，需要包含 TDengine TSDB 头文件，里面列出了提供的 API 的函数原型；应用程序还要链接到所在平台上对应的动态库。

连接方式

TDengine TSDB 客户端驱动提供了 taos 动态库，支持两种连接方式：WebSocket 连接和原生连接。两种连接方式的区别在于：WebSocket 连接不要求客户端和服务端版本完全匹配，而原生连接要求版本匹配；在性能上，WebSocket 连接方式接近于原生连接。一般推荐使用 WebSocket 连接方式。

头文件和动态库

无论使用哪种连接方式，都需要引入 taos.h 头文件和链接 taos 动态库：

#include "taos.h"

安装 TDengine TSDB 客户端或服务端后，taos.h 头文件位于：

• Linux：/usr/local/taos/include
• Windows：C:\TDengine\include
• macOS：/usr/local/include

TDengine TSDB 客户端驱动的动态库位于：

• Linux：/usr/local/taos/driver/libtaos.so
• Windows：C:\TDengine\driver\taos.dll
• macOS：/usr/local/lib/libtaos.dylib

连接方式示例

TDengine TSDB 客户端驱动支持两种连接方式，开发者可以根据需求灵活选择。

原生连接是 TDengine TSDB 的默认连接方式，直接调用 taos_connect() 即可建立连接：

// 原生连接示例
TAOS *taos = taos_connect(ip, user, password, database, port);

WebSocket 连接需要先设置驱动类型，然后调用 taos_connect()：

// WebSocket 连接示例
taos_options(TSDB_OPTION_DRIVER, "websocket");
TAOS *taos = taos_connect(ip, user, password, database, port);

重要说明

taos_options(TSDB_OPTION_DRIVER, arg) 设置驱动类型必须在程序开始时调用，且只能调用一次。一旦设置后，该配置对整个程序生命周期有效，不可更改。

支持的平台

TDengine TSDB 客户端驱动支持多种平台，具体支持的平台列表请参考：支持的平台列表

版本说明

WebSocket 连接

TDengine TSDB 客户端版本	主要变化	TDengine TSDB 版本
3.3.6.0	提供了 SQL 执行、参数绑定、无模式写入和数据订阅等全面功能支持。	3.3.2.0 及更高版本

原生连接

TDengine TSDB 客户端驱动的版本号与 TDengine TSDB 服务端的版本号严格对应，强烈建议使用与 TDengine TSDB 服务端完全相同版本的客户端驱动。虽然低版本的客户端驱动在前三段版本号一致（即仅第四段版本号不同）的情况下也能与高版本的服务端兼容，但这并非推荐用法。强烈不建议使用高版本的客户端驱动访问低版本的服务端。

错误码

请参考 错误码

示例程序

本节展示了使用客户端驱动访问 TDengine TSDB 集群的常见访问方式的示例代码。

WebSocket 连接示例

• 同步查询示例：同步查询

• 异步查询示例：异步查询

• 参数绑定示例：参数绑定

• 无模式写入示例：无模式写入

• 订阅和消费示例：订阅和消费

信息

更多示例代码及下载请见 GitHub。

原生连接示例

• 同步查询示例：同步查询

• 异步查询示例：异步查询

• 参数绑定示例：参数绑定

• 无模式写入示例：无模式写入

• 订阅和消费示例：订阅和消费

信息

更多示例代码及下载请见 GitHub。

API 参考

以下分别介绍 TDengine TSDB 客户端驱动的基础 API、同步查询 API、异步查询 API、参数绑定 API、无模式写入 API 和数据订阅 API。

连接方式兼容性说明

TDengine TSDB 客户端驱动支持 WebSocket 连接和原生连接两种方式。大部分 API 在两种连接方式下功能完全一致，但有少数 API 存在功能差异：

原生连接：所有 API 都提供完整功能支持。

WebSocket 连接：大部分 API 功能完整，少数 API 暂时只返回成功状态但不执行实际操作。

使用方式：

• 原生连接：无需额外配置，直接调用 API 即可，这是默认的连接方式。
• WebSocket 连接：需要先调用 taos_options(TSDB_OPTION_DRIVER, "websocket") 设置驱动类型，然后再调用其他 API。

WebSocket 连接功能差异说明：

API	支持状态	接口说明	使用限制
taos_connect_auth	不支持	MD5 加密密码连接	只返回成功状态，不执行实际操作
taos_set_notify_cb	不支持	设置事件回调函数	只返回成功状态，不执行实际操作
tmq_get_connect	不支持	获取 TMQ 连接句柄	只返回成功状态，不执行实际操作
taos_options_connection	部分支持	设置客户端连接选项	不支持字符集设置，固定使用 UTF-8 字符集

这些 API 在原生连接方式下功能完整。如需使用上述功能，建议选择原生连接方式。未来版本将逐步完善 WebSocket 连接的功能支持。

注意：WebSocket 连接需要在程序开始时调用 taos_options(TSDB_OPTION_DRIVER, "websocket") 设置驱动类型，且只能调用一次。一旦设置后，该配置对整个程序生命周期有效，不可更改。

基础 API

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

• int taos_init()

  • 接口说明：初始化运行环境。如果没有主动调用该 API，那么调用 taos_connect() 时驱动将自动调用该 API，故程序一般无需手动调用。
  • 返回值：0：成功，非 0：失败，可调用函数 taos_errstr(NULL) 获取更详细的错误信息。

• 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_DRIVER）。区域设置、字符集、时区默认为操作系统当前设置。驱动类型可选内部原生接口（native）和 WebSocket 接口（websocket），默认为 websocket。
  • 注意事项：驱动类型设置（TSDB_OPTION_DRIVER）必须在程序开始时调用，且只能调用一次。
  • 参数说明：
    • option：[入参] 设置项类型。
    • arg：[入参] 设置项值。
  • 返回值：0：成功，-1：失败。

• int taos_options_connection(TAOS *taos, TSDB_OPTION_CONNECTION option, const void *arg, ...)

  • 接口说明：设置客户端连接选项，目前支持字符集设置（TSDB_OPTION_CONNECTION_CHARSET）、时区设置（TSDB_OPTION_CONNECTION_TIMEZONE）、用户 IP 设置（TSDB_OPTION_CONNECTION_USER_IP）、用户 APP 设置（TSDB_OPTION_CONNECTION_USER_APP）、连接器信息设置（TSDB_OPTION_CONNECTION_CONNECTOR_INFO）。
  • 参数说明：
    • taos：[入参] taos_connect 返回的连接句柄。
    • option：[入参] 设置项类型。
    • arg：[入参] 设置项值。
  • 返回值：0：成功，非0：失败。
  • 说明：
    • 字符集、时区默认为操作系统当前设置，windows 不支持连接级别的时区设置。
    • arg 为 NULL 时表示重置该选项。
    • 该接口只对当前连接有效，不会影响其他连接。
    • 同样参数多次调用该接口，以后面的为准，可以作为修改的方法。
    • TSDB_OPTION_CONNECTION_CLEAR 选项用于重置所有连接选项。
    • 时区和字符集重置后，使用系统的设置，user ip 和 user app 重置后为空。
    • 连接选项的值都是 string 类型，user app 参数值最大长度为 23，connector info 最大长度为 255，超过该长度会被截断；其他参数非法时报错。
    • 时区配置找不到时区文件或者不能按照规范解释时，默认为 UTC，和操作系统时区规则相同，详见 tzset 函数说明。可通过 select timezone() 查看当前连接的时区。
    • 时区和字符集只在 client 侧起作用，对于在服务端的相关行为不起作用。
    • 时区文件使用操作系统时区文件，可以自行更新操作系统时区文件。如果设置时区报错，请检查是否有时区文件或路径（mac:/var/db/timezone/zoneinfo, linux:/usr/share/zoneinfo）是否正确。

• char *taos_get_client_info()

  • 接口说明：获取客户端版本信息。
  • 返回值：返回客户端版本信息。

• TAOS *taos_connect(const char *ip, const char *user, const char *pass, const char *db, uint16_t port);

  • 接口说明：创建数据库连接，初始化连接上下文。
  • 参数说明：
    • ip：[入参] TDengine TSDB 集群中任一节点的 FQDN。
    • user：[入参] 用户名。
    • pass：[入参] 密码。
    • db：[入参] 数据库名字，如果用户没有提供，也可以正常连接，用户可以通过该连接创建新的数据库，如果用户提供了数据库名字，则说明该数据库用户已经创建好，缺省使用该数据库。
    • port：[入参] taosd 程序监听的端口。
  • 返回值：返回数据库连接，返回值为空表示失败。应用程序需要保存返回的参数，以便后续使用。
    信息

    同一进程可以根据不同的 host/port 连接多个 TDengine TSDB 集群

• 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。
  • 参数说明：
    • ip：[入参] TDengine TSDB 集群中任一节点的 FQDN。
    • user：[入参] 用户名。
    • auth：[入参] 原始密码取 32 位小写 md5。
    • db：[入参] 数据库名称，如果用户没有提供，也可以正常连接，用户可以通过该连接创建新的数据库，如果用户提供了数据库名字，则说明该数据库用户已经创建好，缺省使用该数据库。
    • port：[入参] taosd 程序监听的端口。
  • 返回值：返回数据库连接，返回值为空表示失败。应用程序需要保存返回的参数，以便后续使用。

• char *taos_get_server_info(TAOS *taos)

  • 接口说明：获取服务端版本信息。
  • 参数说明：
    • taos：[入参] 指向数据库连接的指针，数据库连接是通过 taos_connect() 函数建立。
  • 返回值：返回获取服务端版本信息。

• int taos_select_db(TAOS *taos, const char *db)

  • 接口说明：将当前的缺省数据库设置为 db。
  • 参数说明：
    • taos：[入参] 指向数据库连接的指针，数据库连接是通过 taos_connect() 函数建立。
    • db：[入参] 数据库名称。
  • 返回值：0：成功，非 0：失败，详情请参考错误码页面。

• int taos_get_current_db(TAOS *taos, char *database, int len, int *required)

  • 接口说明：获取当前数据库名称。
  • 参数说明：
    • taos：[入参] 指向数据库连接的指针，数据库连接是通过 taos_connect() 函数建立。
    • 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)

  • 接口说明：设置事件回调函数。
  • 参数说明：
    • taos：[入参] 指向数据库连接的指针，数据库连接是通过 taos_connect() 函数建立。
    • fp：[入参] 事件回调函数指针。函数声明：typedef void (__taos_notify_fn_t)(voidparam, 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() 函数建立。

同步查询

本小节介绍 API 均属于同步接口。应用调用后，会阻塞等待响应，直到获得返回结果或错误信息。

• TAOS_RES* taos_query(TAOS *taos, const char *sql)

  • 接口说明：执行 SQL 语句，可以是 DQL、DML 或 DDL 语句。
  • 参数说明：
    • taos：[入参] 指向数据库连接的指针，数据库连接是通过 taos_connect() 函数建立。
    • sql：[入参] 需要执行 SQL 语句。
  • 返回值：不能通过返回值是否是 NULL 来判断执行结果是否失败，而是需要调用 taos_errno() 函数解析结果集中的错误代码来进行判断。
    • taos_errno 返回值：0：成功，-1：失败，详情请调用 taos_errstr 函数来获取错误提示。

• int taos_result_precision(TAOS_RES *res)

  • 接口说明：返回结果集时间戳字段的精度类别。
  • 参数说明：
    • 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 等价，用于获取查询结果集中的列数。
  • 参数说明：
    • res：[入参] 结果集。
  • 返回值：返回值为结果集中列的数量。

• int* taos_fetch_lengths(TAOS_RES *res)

  • 接口说明：获取结果集中每个字段的长度。
  • 参数说明：
    • res：[入参] 结果集。
  • 返回值：返回值是一个数组，其长度为结果集的列数。

• int taos_affected_rows(TAOS_RES *res)

  • 接口说明：获取被所执行的 SQL 语句影响的行数。
  • 参数说明：
    • res：[入参] 结果集。
  • 返回值：返回值表示受影响的行数。

• TAOS_FIELD *taos_fetch_fields(TAOS_RES *res)

  • 接口说明：获取查询结果集每列数据的属性（列的名称、列的数据类型、列的长度），与 taos_num_fields() 配合使用，可用来解析 taos_fetch_row() 返回的一个元组 (一行) 的数据。
  • 参数说明：
    • res：[入参] 结果集。
  • 返回值：非 NULL：成功，返回一个指向 TAOS_FIELD 结构体的指针，每个元素代表一列的元数据。NULL：失败。

• TAOS_FIELD_E *taos_fetch_fields_e(TAOS_RES *res)

  • 接口说明：获取查询结果集每列数据的属性（列的名称、列的数据类型、列的长度），与 taos_num_fields() 配合使用，可用来解析 taos_fetch_row() 返回的一个元组 (一行) 的数据。TAOS_FIELD_E 中 除了 TAOS_FIELD 的基本信息外，还包括了类型的 precision 和 scale 信息。
  • 参数说明：
    • res：[入参] 结果集。
  • 返回值：非 NULL：成功，返回一个指向 TAOS_FIELD_E 结构体的指针，每个元素代表一列的元数据。NULL：失败。

• int taos_print_row(char *str, TAOS_ROW row, TAOS_FIELD *fields, int num_fields)

  • 接口说明：将一行查询结果按列类型格式化为文本，写入到 str 缓冲区，用于日志打印或调试输出。
  • 参数说明：
    • str：[出参] 用户提供的字符缓冲区，用于接收格式化后的整行文本。需保证容量满足输出需求，若结果长度超过缓冲区大小，将进行截断（输出可能不完整）。
    • row：[入参] 一行数据，来自 taos_fetch_row() 的返回值。
    • fields：[入参] 列元数据数组，来自 taos_fetch_fields() 的返回值，用于按列类型格式化各列。
    • num_fields：[入参] 列数量，通常为 taos_num_fields() 的返回值。
  • 返回值：>=0 表示实际写入到 str 的字符数（不包含末尾 '\0'）；<0 表示失败的错误码。

• void taos_stop_query(TAOS_RES *res)

  • 接口说明：停止当前查询的执行。
  • 参数说明：
    • res：[入参] 结果集。

• void taos_free_result(TAOS_RES *res)

  • 接口说明：释放查询结果集以及相关的资源。查询完成后，务必调用该 API 释放资源，否则可能导致应用内存泄露。但也需注意，释放资源后，如果再调用 taos_consume() 等获取查询结果的函数，将导致应用崩溃。
  • 参数说明：
    • res：[入参] 结果集。

• char *taos_errstr(TAOS_RES *res)

  • 接口说明：获取最近一次 API 调用失败的原因，返回值为字符串标识的错误提示信息。
  • 参数说明：
    • res：[入参] 结果集。
  • 返回值：字符串标识的错误提示信息。

• int taos_errno(TAOS_RES *res)

  • 接口说明：获取最近一次 API 调用失败的原因，返回值为错误代码。
  • 参数说明：
    • res：[入参] 结果集。
  • 返回值：字符串标识的错误提示信息。

备注

2.0 及以上版本 TDengine TSDB 推荐数据库应用的每个线程都建立一个独立的连接，或基于线程建立连接池。而不推荐在应用中将该连接 (TAOS*) 结构体传递到不同的线程共享使用。基于 TAOS 结构体发出的查询、写入等操作具有多线程安全性，但“USE statement”等状态量有可能在线程之间相互干扰。此外，C 语言的连接器可以按照需求动态建立面向数据库的新连接（该过程对用户不可见），同时建议只有在程序最后退出的时候才调用 taos_close() 关闭连接。 另一个需要注意的是，在上述同步 API 执行过程中，不能调用类似 pthread_cancel 之类的 API 来强制结束线程，因为涉及一些模块的同步操作，如果强制结束线程有可能造成包括但不限于死锁等异常状况。

异步查询

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

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

异步 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：应用提供的用于回调的参数。

• 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 为零（结果返回完成）或记录数为负值（查询出错）。

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

参数绑定

除了直接调用 taos_query() 进行查询，TDengine TSDB 也提供了支持参数绑定的 Prepare API，风格与 MySQL 类似，目前也仅支持用问号 ? 来代表待绑定的参数。

从 3.3.5.0 版本开始，TDengine TSDB 大幅简化了旧版参数绑定的使用接口。这样在通过参数绑定接口写入数据时，可以避免了 SQL 语法解析的资源消耗，通过批量绑定的方式，在绝大多数情况下显著提升写入性能。此时的典型操作步骤如下：

1. 调用 taos_stmt2_init() 创建参数绑定对象；
2. 调用 taos_stmt2_prepare() 解析 INSERT 或者 SELECT 语句；
3. 调用 taos_stmt2_bind_param() 可以向单个超级表绑定多个子表，每个子表可以绑定多行数据；
4. 调用 taos_stmt2_exec() 执行已经准备好的批处理指令；、
5. 可以重复第 3 ～ 4 步，为写入更多的数据行，而无需再次解析 SQL；
6. 执行完毕，调用 taos_stmt2_close() 释放所有资源。

• char *taos_stmt2_error(TAOS_STMT2 *stmt) 说明：如果 taos_stmt2_exec() 执行成功，假如不需要改变 SQL 语句的话，那么是可以复用 taos_stmt2_prepare() 的解析结果，直接进行第 3 ～ 4 步绑定新数据的。但如果执行出错，那么并不建议继续在当前的环境上下文下继续工作，而是建议释放资源，然后从 taos_stmt2_init() 步骤重新开始，可以通过 taos_stmt2_error 查看具体错误原因。

stmt2 和 stmt 的区别在于：

• stmt2 支持多表批量绑定数据，stmt 只支持单表绑定数据。
• stmt2 支持异步执行，stmt 只支持同步执行。
• stmt2 支持高效写入模式以及自动建表，stmt 不支持。
• stmt2 支持 insert into stb(...tbname,...)values(?,?,?) 语法，stmt 不支持。
• stmt2 支持部分标签/列为固定值，stmt 必须所有列为 ? 。

stmt 升级到 stmt2 的改动：

1. 将 taos_stmt_init() 改为 taos_stmt2_init()，并增加了 TAOS_STMT2_OPTION 结构体参数。
2. 将 taos_stmt_prepare() 改为 taos_stmt2_prepare() 。
3. 将 taos_stmt_set_tbname_tags ， taos_stmt_bind_param() 和 taos_stmt_add_batch 合并改为 taos_stmt2_bind_param()，将 TAOS_MULTI_BIND 改为 TAOS_STMT2_BINDV 结构体作为参数。
4. 将 taos_stmt_execute() 改为 taos_stmt2_exec()，增加了 affected_rows 参数。
5. 将 taos_stmt_close() 改为 taos_stmt2_close() 。

接口相关的具体函数如下（也可以参考 stmt2_insert_demo.c 文件中使用对应函数的方式）：

• TAOS_STMT2 *taos_stmt2_init(TAOS *taos, TAOS_STMT2_OPTION *option)

  • 接口说明：初始化一个预编译的 SQL 语句对象。
  • 参数说明：
    • taos：[入参] 指向数据库连接的指针，数据库连接是通过 taos_connect() 函数建立。
    • option：[入参] 创建配置，当选择高效写入模式需要将 singleStbInsert 和 singleTableBindOnce 设置为 true；当选择异步执行是，需要设置回调函数 asyncExecFn 和参数 userdata。
  • 返回值：非 NULL：成功，返回 TAOS_STMT2 的一个结构体的指针，该结构体表示预编译的 SQL 语句对象。NULL：失败，详情请调用 taos_stmt_errstr() 函数来获取错误提示。

• int taos_stmt2_prepare(TAOS_STMT2 *stmt, const char *sql, unsigned long length)

  • 接口说明：解析一条预编译的 SQL 语句，将解析结果和参数信息绑定到 stmt 上。
  • 参数说明：
    • stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
    • sql：[入参] 需要解析的 SQL 语句。
    • length：[入参] 参数 sql 的长度。如果参数 length 大于 0，将使用此参数作为 SQL 语句的长度，如等于 0，将自动判断 SQL 语句的长度。
  • 返回值：0：成功。非 0：失败，详情请参考错误码页面。

• int taos_stmt2_bind_param(TAOS_STMT2 *stmt, TAOS_STMT2_BINDV *bindv, int32_t col_idx)

  • 接口说明：绑定一批参数到一个预编译的 SQL 语句。
  • 参数说明：
    • stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
    • bindv：[入参] 指向一个有效的 TAOS_STMT2_BINDV 结构体指针，该结构体中包含要绑定的表名、标签、数据，count表示要绑定的表数量，一个tbnames可以对应一组tags以及多组bind_cols；如果是 SELECT 的语句，则只需要绑定 bind_cols。
    • col_idx：[入参] 表示要绑定的指定列的位置， -1表示全列绑定。
  • 返回值：0：成功。非 0：失败，详情请参考错误码页面。

• int taos_stmt2_exec(TAOS_STMT2 *stmt, int *affected_rows)

  • 接口说明：执行绑定完成数据的 SQL，可同步或异步，由 option 决定。
  • 参数说明：
    • stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
    • affected_rows：[出参] 若为同步执行，表示本次执行影响到的的行数。
  • 返回值：0：成功。非 0：失败，详情请参考错误码页面。

• int taos_stmt2_close(TAOS_STMT2 *stmt)

  • 接口说明：执行完毕，释放所有资源。
  • 参数说明：
    • stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
  • 返回值：0：成功。非 0：失败，详情请参考错误码页面。

• int taos_stmt2_get_fields(TAOS_STMT2 *stmt, int *count, TAOS_FIELD_ALL **fields)

  • 接口说明：获取 ? 顺序对应的列数据的属性（列的名称、列的数据类型、列的长度、列的 schema 类型）的数组。
  • 参数说明：
    • stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
    • count：[出参] 返回绑定 SQL 中 ? 的数量。
    • fields：[出参] 返回 ? 顺序对应的列数据的属性，如果是 SELECT 的语句，该结构体返回 NULL。
  • 返回值：0：成功。非 0：失败，详情请参考错误码页面。

• void taos_stmt2_free_fields(TAOS_STMT2 *stmt, TAOS_FIELD_ALL *fields)

  • 接口说明：释放 TAOS_FIELD_ALL 返回值的内存，一般用于 taos_stmt2_get_fields 之后。
  • 参数说明：
    • stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
    • fields：[入参] 要释放资源的指针。
  • 返回值：无。

• TAOS_RES *taos_stmt2_result(TAOS_STMT2 *stmt)

  • 接口说明：获取执行 SQL 后返回的结果。
  • 参数说明：
    • stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
  • 返回值：返回一个指向 TAOS_RES 结构体的指针，该结构体包含了插入操作的结果。返回的 TAOS_RES 需要调用方来负责释放，否则会出现内存泄漏。

• char *taos_stmt2_error(TAOS_STMT2 *stmt)

  • 接口说明：用于在其他 STMT2 API 返回错误（返回错误码或空指针）时获取错误信息。
  • 参数说明：
    • stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
  • 返回值：返回一个指向包含错误信息的字符串的指针。

参数绑定（旧）

从 2.1.1.0 和 2.1.2.0 版本开始，TDengine TSDB 大幅改进了参数绑定接口对数据写入（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() 把当前绑定的参数加入批处理；
7. 可以重复第 3 ～ 6 步，为批处理加入更多的数据行；
8. 调用 taos_stmt_execute() 执行已经准备好的批处理指令；
9. 执行完毕，调用 taos_stmt_close() 释放所有资源。

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

接口相关的具体函数如下（也可以参考 prepare.c 文件中使用对应函数的方式）：

• TAOS_STMT* taos_stmt_init(TAOS *taos)

  • 接口说明：初始化一个预编译的 SQL 语句对象。
  • 参数说明：
    • taos：[入参] 指向数据库连接的指针，数据库连接是通过 taos_connect() 函数建立。
  • 返回值：非 NULL：成功，返回一个指向 TAOS_STMT 结构体的指针，该结构体表示预编译的 SQL 语句对象。NULL：失败，详情请调用 taos_stmt_errstr() 函数来获取错误提示。

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

  • 接口说明：解析一条预编译的 SQL 语句，将解析结果和参数信息绑定到 stmt 上。
  • 参数说明：
    • stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
    • sql：[入参] 需要解析的 SQL 语句。
    • length：[入参] 参数 sql 的长度。如果参数 length 大于 0，将使用此参数作为 SQL 语句的长度，如等于 0，将自动判断 SQL 语句的长度。
  • 返回值：0：成功。非 0：失败，详情请参考错误码页面。

• int taos_stmt_bind_param(TAOS_STMT *stmt, TAOS_MULTI_BIND *bind)

  • 接口说明：绑定参数到一个预编译的 SQL 语句。不如 taos_stmt_bind_param_batch() 效率高，但可以支持非 INSERT 类型的 SQL 语句。
  • 参数说明：
    • stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
    • bind：[入参] 指向一个有效的 TAOS_MULTI_BIND 结构体指针，该结构体包含了要绑定到 SQL 语句中的参数列表。需保证此数组中的元素数量和顺序与 SQL 语句中的参数完全一致。TAOS_MULTI_BIND 的使用方法与 MySQL 中的 MYSQL_BIND 类似。
  • 返回值：0：成功。非 0：失败，详情请参考错误码页面。

• int taos_stmt_set_tbname(TAOS_STMT* stmt, const char* name)

  • 接口说明：（2.1.1.0 版本新增，仅支持用于替换 INSERT 语句中的参数值）当 SQL 语句中的表名使用了 ? 占位时，可以使用此函数绑定一个具体的表名。
  • 参数说明：
    • stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
    • name：[入参] 指向一个包含子表名称的字符串常量。
  • 返回值：0：成功。非 0：失败，详情请参考错误码页面。

• int taos_stmt_set_tbname_tags(TAOS_STMT* stmt, const char* name, TAOS_MULTI_BIND* tags)

  • 接口说明：（2.1.2.0 版本新增，仅支持用于替换 INSERT 语句中的参数值）当 SQL 语句中的表名和 TAGS 都使用了 ? 占位时，可以使用此函数绑定具体的表名和具体的 TAGS 取值。最典型的使用场景是使用了自动建表功能的 INSERT 语句（目前版本不支持指定具体的 TAGS 列）。TAGS 参数中的列数量需要与 SQL 语句中要求的 TAGS 数量完全一致。
  • 参数说明：
    • stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
    • name：[入参] 指向一个包含子表名称的字符串常量。
    • tags：[入参] 指向一个有效的 TAOS_MULTI_BIND 结构体指针，该结构体包含了子表标签的值。
  • 返回值：0：成功。非 0：失败，详情请参考错误码页面。

• int taos_stmt_bind_param_batch(TAOS_STMT* stmt, TAOS_MULTI_BIND* bind)

  • 接口说明：（2.1.1.0 版本新增，仅支持用于替换 INSERT 语句中的参数值）以多列的方式传递待绑定的数据，需要保证这里传递的数据列的顺序、列的数量与 SQL 语句中的 VALUES 参数完全一致。
  • 参数说明：
    • stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
    • bind：[入参] 指向一个有效的 TAOS_MULTI_BIND 结构体指针，该结构体包含了要批量绑定到 SQL 语句中的参数列表。
  • 返回值：0：成功。非 0：失败，详情请参考错误码页面。

• int taos_stmt_add_batch(TAOS_STMT *stmt)

  • 接口说明：将当前绑定的参数加入批处理中，调用此函数后，可以再次调用 taos_stmt_bind_param() 或 taos_stmt_bind_param_batch() 绑定新的参数。需要注意，此函数仅支持 INSERT/IMPORT 语句，如果是 SELECT 等其他 SQL 语句，将返回错误。
    • stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
  • 返回值：0：成功。非 0：失败，详情请参考错误码页面。

• int taos_stmt_execute(TAOS_STMT *stmt)

  • 接口说明：执行准备好的语句。目前，一条语句只能执行一次。
    • stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
  • 返回值：0：成功。非 0：失败，详情请参考错误码页面。

• int taos_stmt_affected_rows(TAOS_STMT *stmt)

  • 接口说明：获取执行预编译 SQL 语句后受影响的行数。
    • stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
  • 返回值：返回受影响的行数。

• int taos_stmt_affected_rows_once(TAOS_STMT *stmt)

  • 接口说明：获取执行一次绑定语句影响的行数。
    • stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
  • 返回值：返回受影响的行数。

• TAOS_RES* taos_stmt_use_result(TAOS_STMT *stmt)

  • 接口说明：获取语句的结果集。结果集的使用方式与非参数化调用时一致，使用完成后，应对此结果集调用 taos_free_result() 以释放资源。
    • stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
  • 返回值：非 NULL：成功，返回一个指向查询结果集的指针。NULL：失败，详情请调用 taos_stmt_errstr() 函数来获取错误提示。

• int taos_stmt_close(TAOS_STMT *stmt)

  • 接口说明：执行完毕，释放所有资源。
    • stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
  • 返回值：0：成功。非 0：失败，详情请参考错误码页面。

• char * taos_stmt_errstr(TAOS_STMT *stmt)

  • 接口说明：（2.1.3.0 版本新增）用于在其他 STMT API 返回错误（返回错误码或空指针）时获取错误信息。
    • stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
  • 返回值：返回一个指向包含错误信息的字符串的指针。

无模式写入

除了使用 SQL 方式或者使用参数绑定 API 写入数据外，还可以使用 Schemaless 的方式完成写入。Schemaless 可以免于预先创建超级表/数据子表的数据结构，而是可以直接写入数据，TDengine TSDB 系统会根据写入的数据内容自动创建和维护所需要的表结构。Schemaless 的使用方式详见 Schemaless 写入 章节，这里介绍与之配套使用的 C/C++ API。

• TAOS_RES* taos_schemaless_insert(TAOS* taos, const char* lines[], int numLines, int protocol, int precision)

  • 接口说明：执行无模式的批量插入操作，将行协议的文本数据写入到 TDengine TSDB 中。
    • taos：[入参] 指向数据库连接的指针，数据库连接是通过 taos_connect() 函数建立。
    • lines：[入参] 文本数据。满足解析格式要求的无模式文本字符串。
    • numLines：[入参] 文本数据的行数，不能为 0。
    • protocol：[入参] 行协议类型，用于标识文本数据格式。
    • precision：[入参] 文本数据中的时间戳精度字符串。
  • 返回值：返回一个指向 TAOS_RES 结构体的指针，该结构体包含了插入操作的结果。应用可以通过使用 taos_errstr() 获得错误信息，也可以使用 taos_errno() 获得错误码。在某些情况下，返回的 TAOS_RES 为 NULL，此时仍然可以调用 taos_errno() 来安全地获得错误码信息。 返回的 TAOS_RES 需要调用方来负责释放，否则会出现内存泄漏。

  说明

  协议类型是枚举类型，包含以下三种格式：

  • TSDB_SML_LINE_PROTOCOL：InfluxDB 行协议（Line Protocol)
  • TSDB_SML_TELNET_PROTOCOL：OpenTSDB Telnet 文本行协议
  • TSDB_SML_JSON_PROTOCOL：OpenTSDB Json 协议格式

  时间戳分辨率的定义，定义在 taos.h 文件中，具体内容如下：

  • TSDB_SML_TIMESTAMP_NOT_CONFIGURED = 0,
  • TSDB_SML_TIMESTAMP_HOURS,
  • TSDB_SML_TIMESTAMP_MINUTES,
  • TSDB_SML_TIMESTAMP_SECONDS,
  • TSDB_SML_TIMESTAMP_MILLI_SECONDS,
  • TSDB_SML_TIMESTAMP_MICRO_SECONDS,
  • TSDB_SML_TIMESTAMP_NANO_SECONDS

  需要注意的是，时间戳分辨率参数只在协议类型为 SML_LINE_PROTOCOL 的时候生效。 对于 OpenTSDB 的文本协议，时间戳的解析遵循其官方解析规则 — 按照时间戳包含的字符的数量来确认时间精度。

  schemaless 其他相关的接口

• TAOS_RES *taos_schemaless_insert_with_reqid(TAOS *taos, char *lines[], int numLines, int protocol, int precision, int64_t reqid)

  • 接口说明：执行无模式的批量插入操作，将行协议的文本数据写入到 TDengine TSDB 中。通过传递参数 reqid 来跟踪整个的函数调用链情况。
    • taos：[入参] 指向数据库连接的指针，数据库连接是通过 taos_connect() 函数建立。
    • lines：[入参] 文本数据。满足解析格式要求的无模式文本字符串。
    • numLines：[入参] 文本数据的行数，不能为 0。
    • protocol：[入参] 行协议类型，用于标识文本数据格式。
    • precision：[入参] 文本数据中的时间戳精度字符串。
    • reqid：[入参] 指定的请求 ID，用于跟踪调用请求。请求 ID (reqid) 可以用于在客户端和服务器端之间建立请求和响应之间的关联，对于分布式系统中的跟踪和调试非常有用。
  • 返回值：返回一个指向 TAOS_RES 结构体的指针，该结构体包含了插入操作的结果。应用可以通过使用 taos_errstr() 获得错误信息，也可以使用 taos_errno() 获得错误码。在某些情况下，返回的 TAOS_RES 为 NULL，此时仍然可以调用 taos_errno() 来安全地获得错误码信息。 返回的 TAOS_RES 需要调用方来负责释放，否则会出现内存泄漏。

• TAOS_RES *taos_schemaless_insert_raw(TAOS *taos, char *lines, int len, int32_t *totalRows, int protocol, int precision)

  • 接口说明：执行无模式的批量插入操作，将行协议的文本数据写入到 TDengine TSDB 中。通过传递的参数 lines 指针和长度 len 来表示数据，为了解决原始接口数据包含'\0'而被截断的问题。
    • taos：[入参] 指向数据库连接的指针，数据库连接是通过 taos_connect() 函数建立。
    • lines：[入参] 文本数据。满足解析格式要求的无模式文本字符串。
    • len：[入参] 数据缓冲区 lines 的总长度（字节数）。
    • totalRows：[出参] 指向一个整数指针，用于返回成功插入的记录总数。
    • protocol：[入参] 行协议类型，用于标识文本数据格式。
    • precision：[入参] 文本数据中的时间戳精度字符串。
  • 返回值：返回一个指向 TAOS_RES 结构体的指针，该结构体包含了插入操作的结果。应用可以通过使用 taos_errstr() 获得错误信息，也可以使用 taos_errno() 获得错误码。在某些情况下，返回的 TAOS_RES 为 NULL，此时仍然可以调用 taos_errno() 来安全地获得错误码信息。 返回的 TAOS_RES 需要调用方来负责释放，否则会出现内存泄漏。

• TAOS_RES *taos_schemaless_insert_raw_with_reqid(TAOS *taos, char *lines, int len, int32_t *totalRows, int protocol, int precision, int64_t reqid)

  • 接口说明：执行无模式的批量插入操作，将行协议的文本数据写入到 TDengine TSDB 中。通过传递的参数 lines 指针和长度 len 来表示数据，为了解决原始接口数据包含'\0'而被截断的问题。通过传递参数 reqid 来跟踪整个的函数调用链情况。
    • taos：[入参] 指向数据库连接的指针，数据库连接是通过 taos_connect() 函数建立。
    • lines：[入参] 文本数据。满足解析格式要求的无模式文本字符串。
    • len：[入参] 数据缓冲区 lines 的总长度（字节数）。
    • totalRows：[出参] 指向一个整数指针，用于返回成功插入的记录总数。
    • protocol：[入参] 行协议类型，用于标识文本数据格式。
    • precision：[入参] 文本数据中的时间戳精度字符串。
    • reqid：[入参] 指定的请求 ID，用于跟踪调用请求。请求 ID (reqid) 可以用于在客户端和服务器端之间建立请求和响应之间的关联，对于分布式系统中的跟踪和调试非常有用。
  • 返回值：返回一个指向 TAOS_RES 结构体的指针，该结构体包含了插入操作的结果。应用可以通过使用 taos_errstr() 获得错误信息，也可以使用 taos_errno() 获得错误码。在某些情况下，返回的 TAOS_RES 为 NULL，此时仍然可以调用 taos_errno() 来安全地获得错误码信息。 返回的 TAOS_RES 需要调用方来负责释放，否则会出现内存泄漏。

• TAOS_RES *taos_schemaless_insert_ttl(TAOS *taos, char *lines[], int numLines, int protocol, int precision, int32_t ttl)

  • 接口说明：执行无模式的批量插入操作，将行协议的文本数据写入到 TDengine TSDB 中。通过传递 ttl 参数来控制建表的 ttl 到期时间。
    • taos：[入参] 指向数据库连接的指针，数据库连接是通过 taos_connect() 函数建立。
    • lines：[入参] 文本数据。满足解析格式要求的无模式文本字符串。
    • numLines：[入参] 文本数据的行数，不能为 0。
    • protocol：[入参] 行协议类型，用于标识文本数据格式。
    • precision：[入参] 文本数据中的时间戳精度字符串。
    • ttl：[入参] 指定的生存时间（TTL），单位为天。记录在超过这个生存时间后会被自动删除。
  • 返回值：返回一个指向 TAOS_RES 结构体的指针，该结构体包含了插入操作的结果。应用可以通过使用 taos_errstr() 获得错误信息，也可以使用 taos_errno() 获得错误码。在某些情况下，返回的 TAOS_RES 为 NULL，此时仍然可以调用 taos_errno() 来安全地获得错误码信息。 返回的 TAOS_RES 需要调用方来负责释放，否则会出现内存泄漏。

• TAOS_RES *taos_schemaless_insert_ttl_with_reqid(TAOS *taos, char *lines[], int numLines, int protocol, int precision, int32_t ttl, int64_t reqid)

  • 接口说明：执行无模式的批量插入操作，将行协议的文本数据写入到 TDengine TSDB 中。通过传递 ttl 参数来控制建表的 ttl 到期时间。通过传递参数 reqid 来跟踪整个的函数调用链情况。
    • taos：[入参] 指向数据库连接的指针，数据库连接是通过 taos_connect() 函数建立。
    • lines：[入参] 文本数据。满足解析格式要求的无模式文本字符串。
    • numLines：[入参] 文本数据的行数，不能为 0。
    • protocol：[入参] 行协议类型，用于标识文本数据格式。
    • precision：[入参] 文本数据中的时间戳精度字符串。
    • ttl：[入参] 指定的生存时间（TTL），单位为天。记录在超过这个生存时间后会被自动删除。
    • reqid：[入参] 指定的请求 ID，用于跟踪调用请求。请求 ID (reqid) 可以用于在客户端和服务器端之间建立请求和响应之间的关联，对于分布式系统中的跟踪和调试非常有用。
  • 返回值：返回一个指向 TAOS_RES 结构体的指针，该结构体包含了插入操作的结果。应用可以通过使用 taos_errstr() 获得错误信息，也可以使用 taos_errno() 获得错误码。在某些情况下，返回的 TAOS_RES 为 NULL，此时仍然可以调用 taos_errno() 来安全地获得错误码信息。 返回的 TAOS_RES 需要调用方来负责释放，否则会出现内存泄漏。

• TAOS_RES *taos_schemaless_insert_raw_ttl(TAOS *taos, char *lines, int len, int32_t *totalRows, int protocol, int precision, int32_t ttl)

  • 接口说明：执行无模式的批量插入操作，将行协议的文本数据写入到 TDengine TSDB 中。通过传递的参数 lines 指针和长度 len 来表示数据，为了解决原始接口数据包含'\0'而被截断的问题。通过传递 ttl 参数来控制建表的 ttl 到期时间。
    • taos：[入参] 指向数据库连接的指针，数据库连接是通过 taos_connect() 函数建立。
    • lines：[入参] 文本数据。满足解析格式要求的无模式文本字符串。
    • len：[入参] 数据缓冲区 lines 的总长度（字节数）。
    • totalRows：[出参] 指向一个整数指针，用于返回成功插入的记录总数。
    • protocol：[入参] 行协议类型，用于标识文本数据格式。
    • precision：[入参] 文本数据中的时间戳精度字符串。
    • ttl：[入参] 指定的生存时间（TTL），单位为天。记录在超过这个生存时间后会被自动删除。
  • 返回值：返回一个指向 TAOS_RES 结构体的指针，该结构体包含了插入操作的结果。应用可以通过使用 taos_errstr() 获得错误信息，也可以使用 taos_errno() 获得错误码。在某些情况下，返回的 TAOS_RES 为 NULL，此时仍然可以调用 taos_errno() 来安全地获得错误码信息。 返回的 TAOS_RES 需要调用方来负责释放，否则会出现内存泄漏。

• TAOS_RES *taos_schemaless_insert_raw_ttl_with_reqid(TAOS *taos, char *lines, int len, int32_t *totalRows, int protocol, int precision, int32_t ttl, int64_t reqid)

  • 接口说明：执行无模式的批量插入操作，将行协议的文本数据写入到 TDengine TSDB 中。通过传递的参数 lines 指针和长度 len 来表示数据，为了解决原始接口数据包含'\0'而被截断的问题。通过传递 ttl 参数来控制建表的 ttl 到期时间。通过传递参数 reqid 来跟踪整个的函数调用链情况。
    • taos：[入参] 指向数据库连接的指针，数据库连接是通过 taos_connect() 函数建立。
    • lines：[入参] 文本数据。满足解析格式要求的无模式文本字符串。
    • len：[入参] 数据缓冲区 lines 的总长度（字节数）。
    • totalRows：[出参] 指向一个整数指针，用于返回成功插入的记录总数。
    • protocol：[入参] 行协议类型，用于标识文本数据格式。
    • precision：[入参] 文本数据中的时间戳精度字符串。
    • ttl：[入参] 指定的生存时间（TTL），单位为天。记录在超过这个生存时间后会被自动删除。
    • reqid：[入参] 指定的请求 ID，用于跟踪调用请求。请求 ID (reqid) 可以用于在客户端和服务器端之间建立请求和响应之间的关联，对于分布式系统中的跟踪和调试非常有用。
  • 返回值：返回一个指向 TAOS_RES 结构体的指针，该结构体包含了插入操作的结果。应用可以通过使用 taos_errstr() 获得错误信息，也可以使用 taos_errno() 获得错误码。在某些情况下，返回的 TAOS_RES 为 NULL，此时仍然可以调用 taos_errno() 来安全地获得错误码信息。 返回的 TAOS_RES 需要调用方来负责释放，否则会出现内存泄漏。

  说明

  • 上面这 7 个接口是扩展接口，主要用于在 schemaless 写入时传递 ttl、reqid 参数，可以根据需要使用。
  • 带_raw 的接口通过传递的参数 lines 指针和长度 len 来表示数据，为了解决原始接口数据包含'\0'而被截断的问题。totalRows 指针返回解析出来的数据行数。
  • 带_ttl 的接口可以传递 ttl 参数来控制建表的 ttl 到期时间。
  • 带_reqid 的接口可以通过传递 reqid 参数来追踪整个的调用链。

数据订阅

• const char *tmq_err2str(int32_t code)

  • 接口说明：用于将数据订阅的错误码转换为错误信息。
    • code：[入参] 数据订阅的错误码。
  • 返回值：返回一个指向包含错误信息字符串的指针，返回值非 NULL，但是错误信息可能为空字符串。

• tmq_conf_t *tmq_conf_new()

  • 接口说明：创建一个新的 TMQ 配置对象。
  • 返回值：非 NULL：成功，返回一个指向 tmq_conf_t 结构体的指针，该结构体用于配置 TMQ 的行为和特性。NULL：失败，可调用函数 taos_errstr(NULL) 获取更详细的错误信息。

• tmq_conf_res_t tmq_conf_set(tmq_conf_t *conf, const char *key, const char *value)

  • 接口说明：设置 TMQ 配置对象中的配置项，用于配置消费参数。

    • conf：[入参] 指向一个有效的 tmq_conf_t 结构体指针，该结构体代表一个 TMQ 配置对象。
    • key：[入参] 数配置项的键名。
    • value：[入参] 配置项的值。

  • 返回值：返回一个 tmq_conf_res_t 枚举值，表示配置设置的结果。tmq_conf_res_t 定义如下：

    typedef enum tmq_conf_res_t {
         TMQ_CONF_UNKNOWN = -2,  // 键名无效
         TMQ_CONF_INVALID = -1,  // 键值无效
         TMQ_CONF_OK = 0,        // 成功设置配置项
       } tmq_conf_res_t;

• void tmq_conf_set_auto_commit_cb(tmq_conf_t *conf, tmq_commit_cb *cb, void *param)

  • 接口说明：设置 TMQ 配置对象中的自动提交回调函数。
    • conf：[入参] 指向一个有效的 tmq_conf_t 结构体指针，该结构体代表一个 TMQ 配置对象。
    • cb：[入参] 指向一个有效的 tmq_commit_cb 回调函数指针，该函数将在消息被消费后调用以确认消息处理状态。
    • param：[入参] 传递给回调函数的用户自定义参数。
  • 设置自动提交回调函数的定义如下： typedef void(tmq_commit_cb(tmq_t *tmq, int32_t code, void *param))

• void tmq_conf_destroy(tmq_conf_t *conf)

  • 接口说明：销毁一个 TMQ 配置对象并释放相关资源。
    • conf：[入参] 指向一个有效的 tmq_conf_t 结构体指针，该结构体代表一个 TMQ 配置对象。

• tmq_list_t *tmq_list_new()

  • 接口说明：用于创建一个 tmq_list_t 结构体，用于存储订阅的 topic。
  • 返回值：非 NULL：成功，返回一个指向 tmq_list_t 结构体的指针。NULL：失败，可调用函数 taos_errstr(NULL) 获取更详细的错误信息。

• int32_t tmq_list_append(tmq_list_t *list, const char* topic)

  • 接口说明：用于向 tmq_list_t 结构体中添加一个 topic。
    • list：[入参] 指向一个有效的 tmq_list_t 结构体指针，该结构体代表一个 TMQ 列表对象。
    • topic：[入参] topic 名称。
  • 返回值：0：成功。非 0：失败，可调用函数 char *tmq_err2str(int32_t code) 获取更详细的错误信息。

• void tmq_list_destroy(tmq_list_t *list)

  • 接口说明：用于销毁 tmq_list_t 结构体，tmq_list_new 的结果需要通过该接口销毁。
    • list：[入参] 指向一个有效的 tmq_list_t 结构体指针，该结构体代表一个 TMQ 列表对象。

• int32_t tmq_list_get_size(const tmq_list_t *list)

  • 接口说明：用于获取 tmq_list_t 结构体中 topic 的个数。
    • list：[入参] 指向一个有效的 tmq_list_t 结构体指针，该结构体代表一个 TMQ 列表对象。
  • 返回值：>=0：成功，返回 tmq_list_t 结构体中 topic 的个数。-1：失败，表示输入参数 list 为 NULL。

• char **tmq_list_to_c_array(const tmq_list_t *list)

  • 接口说明：用于将 tmq_list_t 结构体转换为 C 数组，数组每个元素为字符串指针。
    • list：[入参] 指向一个有效的 tmq_list_t 结构体指针，该结构体代表一个 TMQ 列表对象。
  • 返回值：非 NULL：成功，返回 c 数组，每个元素是字符串指针，代表一个 topic 名称。NULL：失败，表示输入参数 list 为 NULL。

• tmq_t *tmq_consumer_new(tmq_conf_t *conf, char *errstr, int32_t errstrLen)

  • 接口说明：用于创建一个 tmq_t 结构体，用于消费数据，消费完数据后需调用 tmq_consumer_close 关闭消费者。
    • conf：[入参] 指向一个有效的 tmq_conf_t 结构体指针，该结构体代表一个 TMQ 配置对象。
    • errstr：[出参] 指向一个有效的字符缓冲区指针，用于接收创建过程中可能产生的错误信息。内存的申请/释放由调用者负责。
    • errstrLen：[入参] 指定 errstr 缓冲区的大小（以字节为单位）。
  • 返回值：非 NULL：成功，返回一个指向 tmq_t 结构体的指针，该结构体代表一个 TMQ 消费者对象。。NULL：失败，错误信息存储在参数 errstr 中。

• int32_t tmq_subscribe(tmq_t *tmq, const tmq_list_t *topic_list)

  • 接口说明：用于订阅 topic 列表，消费完数据后，需调用 tmq_subscribe 取消订阅。
    • tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
    • topic_list：[入参] 指向一个有效的 tmq_list_t 结构体指针，该结构体包含一个或多个主题名称。
  • 返回值：0：成功。非 0：失败，可调用函数 char *tmq_err2str(int32_t code) 获取更详细的错误信息。

• int32_t tmq_unsubscribe(tmq_t *tmq)

  • 接口说明：用于取消订阅的 topic 列表。需与 tmq_subscribe 配合使用。
    • tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
  • 返回值：0：成功。非 0：失败，可调用函数 char *tmq_err2str(int32_t code) 获取更详细的错误信息。

• int32_t tmq_subscription(tmq_t *tmq, tmq_list_t **topic_list)

  • 接口说明：用于获取订阅的 topic 列表。
    • tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
    • topic_list：[出参] 指向一个 tmq_list_t 结构体指针的指针，用于接收当前订阅的主题列表。
  • 返回值：0：成功。非 0：失败，可调用函数 char *tmq_err2str(int32_t code) 获取更详细的错误信息。

• TAOS_RES *tmq_consumer_poll(tmq_t *tmq, int64_t timeout)

  • 接口说明：用于轮询消费数据，每一个消费者，只能单线程调用该接口。
    • tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
    • timeout：[入参] 轮询的超时时间，单位为毫秒，负数表示默认超时 1 秒。
  • 返回值：非 NULL：成功，返回一个指向 TAOS_RES 结构体的指针，该结构体包含了接收到的消息。。NULL：表示没有数据，可通过 taos_errno(NULL) 获取错误码，具体错误码参见参考手册。TAOS_RES 结果和 taos_query 返回结果一致，可通过查询的各种接口获取 TAOS_RES 里的信息，比如 schema 等。

• int32_t tmq_consumer_close(tmq_t *tmq)

  • 接口说明：用于关闭 tmq_t 结构体。需与 tmq_consumer_new 配合使用。
    • tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
  • 返回值：非 NULL：成功，返回一个指向 TAOS_RES 结构体的指针，该结构体包含了接收到的消息。。NULL：表示没有数据，可通过 taos_errno(NULL) 获取错误码，具体错误码参见参考手册。TAOS_RES 结果和 taos_query 返回结果一致，可通过查询的各种接口获取 TAOS_RES 里的信息，比如 schema 等。

• int32_t tmq_get_topic_assignment(tmq_t *tmq, const char *pTopicName, tmq_topic_assignment **assignment, int32_t *numOfAssignment)

  • 接口说明：返回当前 consumer 分配的 vgroup 的信息，每个 vgroup 的信息包括 vgId，wal 的最大最小 offset，以及当前消费到的 offset。
    • tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
    • pTopicName：[入参] 要查询分配信息的主题名称。
    • assignment：[出参] 指向一个 tmq_topic_assignment 结构体指针的指针，用于接收分配信息。数据大小为 numOfAssignment，需要通过 tmq_free_assignment 接口释放。
    • numOfAssignment：[出参] 指向一个整数指针，用于接收分配给该 consumer 有效的 vgroup 个数。
  • 返回值：0：成功。非 0：失败，可调用函数 char *tmq_err2str(int32_t code) 获取更详细的错误信息。

• void tmq_free_assignment(tmq_topic_assignment* pAssignment)

  • 接口说明：返回当前 consumer 分配的 vgroup 的信息，每个 vgroup 的信息包括 vgId，wal 的最大最小 offset，以及当前消费到的 offset。
    • pAssignment：[入参] 指向一个有效的 tmq_topic_assignment 结构体数组的指针，该数组包含了 vgroup 分配信息。

• int64_t tmq_committed(tmq_t *tmq, const char *pTopicName, int32_t vgId)

  • 接口说明：获取 TMQ 消费者对象对特定 topic 和 vgroup 的已提交偏移量。
    • tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
    • pTopicName：[入参] 要查询已提交偏移量的主题名称。
    • vgId：[入参] vgroup 的 ID。
  • 返回值：>=0：成功，返回一个 int64_t 类型的值，表示已提交的偏移量。<0：失败，返回值就是错误码，可调用函数 char *tmq_err2str(int32_t code) 获取更详细的错误信息。

• int32_t tmq_commit_sync(tmq_t *tmq, const TAOS_RES *msg)

  • 接口说明：同步提交 TMQ 消费者对象处理的消息偏移量。
    • tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
    • msg：[入参] 指向一个有效的 TAOS_RES 结构体指针，该结构体包含了已处理的消息。如果为 NULL，提交当前 consumer 所有消费的 vgroup 的当前进度。
  • 返回值：0：成功，已经成功提交偏移量。非 0：失败，可调用函数 char *tmq_err2str(int32_t code) 获取更详细的错误信息。

• void tmq_commit_async(tmq_t *tmq, const TAOS_RES *msg, tmq_commit_cb *cb, void *param)

  • 接口说明：异步提交 TMQ 消费者对象处理的消息偏移量。
    • tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
    • msg：[入参] 指向一个有效的 TAOS_RES 结构体指针，该结构体包含了已处理的消息。如果为 NULL，提交当前 consumer 所有消费的 vgroup 的当前进度。
    • cb：[入参] 一个回调函数指针，当提交完成时会被调用。
    • param：[入参] 一个用户自定义的参数，将在回调函数中传递给 cb。

• int32_t tmq_commit_offset_sync(tmq_t *tmq, const char *pTopicName, int32_t vgId, int64_t offset)

  • 接口说明：同步提交 TMQ 消费者对象的特定主题和 vgroup 的偏移量。
    • tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
    • pTopicName：[入参] 要提交偏移量的主题名称。
    • vgId：[入参] 虚拟组 vgroup 的 ID。
    • offset：[入参] 要提交的偏移量。
  • 返回值：0：成功，已经成功提交偏移量。非 0：失败，可调用函数 char *tmq_err2str(int32_t code) 获取更详细的错误信息。

• void tmq_commit_offset_async(tmq_t *tmq, const char *pTopicName, int32_t vgId, int64_t offset, tmq_commit_cb *cb, void *param)

  • 接口说明：异步提交 TMQ 消费者对象的特定主题和 vgroup 的偏移量。
    • tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
    • pTopicName：[入参] 要提交偏移量的主题名称。
    • vgId：[入参] 虚拟组 vgroup 的 ID。
    • offset：[入参] 要提交的偏移量。
    • cb：[入参] 一个回调函数指针，当提交完成时会被调用。
    • param：[入参] 一个用户自定义的参数，将在回调函数中传递给 cb。

• int64_t tmq_position(tmq_t *tmq, const char *pTopicName, int32_t vgId)

  • 接口说明：获取当前消费位置，即已消费到的数据位置的下一个位置。
    • tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
    • pTopicName：[入参] 要查询当前位置的主题名称。
    • vgId：[入参] 虚拟组 vgroup 的 ID。
  • 返回值：>=0：成功，返回一个 int64_t 类型的值，表示当前位置的偏移量。<0：失败，返回值就是错误码，可调用函数 char *tmq_err2str(int32_t code) 获取更详细的错误信息。

• int32_t tmq_offset_seek(tmq_t *tmq, const char *pTopicName, int32_t vgId, int64_t offset)

  • 接口说明：将 TMQ 消费者对象在某个特定 topic 和 vgroup 的偏移量设置到指定的位置。
    • tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
    • pTopicName：[入参] 要查询当前位置的主题名称。
    • vgId：[入参] 虚拟组 vgroup 的 ID。
    • offset：[入参] 虚拟组 vgroup 的 ID。
  • 返回值：0：成功，非 0：失败，可调用函数 char *tmq_err2str(int32_t code) 获取更详细的错误信息。

• int64_t tmq_get_vgroup_offset(TAOS_RES* res)

  • 接口说明：从 TMQ 消费者获取的消息结果中提取虚拟组（vgroup）的当前消费数据位置的偏移量。
    • res：[入参] 指向一个有效的 TAOS_RES 结构体指针，该结构体包含了从 TMQ 消费者轮询得到的消息。
  • 返回值：>=0：成功，返回一个 int64_t 类型的值，表示当前消费位置的偏移量。<0：失败，返回值就是错误码，可调用函数 char *tmq_err2str(int32_t code) 获取更详细的错误信息。

• int32_t tmq_get_vgroup_id(TAOS_RES *res)

  • 接口说明：从 TMQ 消费者获取的消息结果中提取所属虚拟组（vgroup）的 ID。
    • res：[入参] 指向一个有效的 TAOS_RES 结构体指针，该结构体包含了从 TMQ 消费者轮询得到的消息。
  • 返回值：>=0：成功，返回一个 int32_t 类型的值，表示虚拟组（vgroup）的 ID。<0：失败，返回值就是错误码，可调用函数 char *tmq_err2str(int32_t code) 获取更详细的错误信息。

• TAOS *tmq_get_connect(tmq_t *tmq)

  • 接口说明：从 TMQ 消费者对象中获取与 TDengine TSDB 数据库的连接句柄。
    • tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
  • 返回值：非 NULL：成功，返回一个 TAOS * 类型的指针，指向与 TDengine TSDB 数据库的连接句柄。NULL：失败，非法的输入参数。

• const char *tmq_get_table_name(TAOS_RES *res)

  • 接口说明：从 TMQ 消费者获取的消息结果中获取所属的表名。
    • res：[入参] 指向一个有效的 TAOS_RES 结构体指针，该结构体包含了从 TMQ 消费者轮询得到的消息。
  • 返回值：非 NULL：成功，返回一个 const char * 类型的指针，指向表名字符串。NULL：失败，非法的输入参数。

• tmq_res_t tmq_get_res_type(TAOS_RES *res)

  • 接口说明：从 TMQ 消费者获取的消息结果中获取消息类型。
    • res：[入参] 指向一个有效的 TAOS_RES 结构体指针，该结构体包含了从 TMQ 消费者轮询得到的消息。
  • 返回值：返回一个 tmq_res_t 类型的枚举值，表示消息类型。

    • tmq_res_t 表示消费到的数据类型，定义如下：

      typedef enum tmq_res_t {
        TMQ_RES_INVALID = -1,   // 无效
        TMQ_RES_DATA = 1,       // 数据类型
        TMQ_RES_TABLE_META = 2, // 元数据类型
        TMQ_RES_METADATA = 3    // 既有元数据类型又有数据类型，即自动建表
      } tmq_res_t;

• const char *tmq_get_topic_name(TAOS_RES *res)

  • 接口说明：从 TMQ 消费者获取的消息结果中获取所属的 topic 名称。
    • res：[入参] 指向一个有效的 TAOS_RES 结构体指针，该结构体包含了从 TMQ 消费者轮询得到的消息。
  • 返回值：非 NULL：成功，返回一个 const char * 类型的指针，指向 topic 名称字符串。NULL：失败，非法的输入参数。

• const char *tmq_get_db_name(TAOS_RES *res)

  • 接口说明：从 TMQ 消费者获取的消息结果中获取所属的数据库名称。
    • res：[入参] 指向一个有效的 TAOS_RES 结构体指针，该结构体包含了从 TMQ 消费者轮询得到的消息。
  • 返回值：非 NULL：成功，返回一个 const char * 类型的指针，指向数据库名称字符串。NULL：失败，非法的输入参数。