C/C++ Connector

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

CPU类型x64(64bit)ARM64ARM32
OS类型LinuxWin64Win32LinuxLinux
支持与否支持支持支持支持开发中

C/C++的API类似于MySQL的C API。应用程序使用时,需要包含TDengine头文件 taos.h(安装后,位于 /usr/local/taos/include):

  1. #include <taos.h>

注意:

  • 在编译时需要链接TDengine动态库。Linux 为 libtaos.so ,安装后,位于 /usr/local/taos/driver。Windows为 taos.dll,安装后位于 C:\TDengine
  • 如未特别说明,当API的返回值是整数时,0 代表成功,其它是代表失败原因的错误码,当返回值是指针时, NULL 表示失败。

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

基础API

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

  • void taos_init()

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

  • void taos_cleanup()

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

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

    设置客户端选项,目前只支持时区设置(_TSDB_OPTIONTIMEZONE)和编码设置(_TSDB_OPTIONLOCALE)。时区和编码默认为操作系统当前设置。

  • 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:端口号

    返回值为空表示失败。应用程序需要保存返回的参数,以便后续API调用。

  • char *taos_get_server_info(TAOS *taos)

    获取服务端版本信息。

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

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

  • void taos_close(TAOS *taos)

    关闭连接, 其中taostaos_connect函数返回的指针。

同步查询API

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

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

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

  • int taos_result_precision(TAOS_RES *res)

    返回结果集时间戳字段的精度,0 代表毫秒,1 代表微秒,2 代表纳秒。

  • 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)

    获取查询结果集每列数据的属性(数据类型、名字、字节数),与taos_num_fileds配合使用,可用来解析taos_fetch_row返回的一个元组(一行)的数据。 TAOS_FIELD 的结构如下:

  1. typedef struct taosField {
  2. char name[65]; // 列名
  3. uint8_t type; // 数据类型
  4. int16_t bytes; // 字节数
  5. } TAOS_FIELD;
  • void taos_stop_query(TAOS_RES *res)

    停止一个查询的执行。

  • void taos_free_result(TAOS_RES *res)

    释放查询结果集以及相关的资源。查询完成后,务必调用该API释放资源,否则可能导致应用内存泄露。但也需注意,释放资源后,如果再调用taos_consume等获取查询结果的函数,将导致应用Crash。

  • char *taos_errstr(TAOS_RES *res)

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

  • char *taos_errno(TAOS_RES *res)

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

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

异步查询API

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

参数绑定API

除了直接调用 taos_query 进行查询,TDengine也提供了支持参数绑定的Prepare API,与 MySQL 一样,这些API目前也仅支持用问号?来代表待绑定的参数,具体如下:

  • TAOS_STMT* taos_stmt_init(TAOS *taos)

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

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

    解析一条sql语句,将解析结果和参数信息绑定到stmt上,如果参数length大于0,将使用此参数作为sql语句的长度,如等于0,将自动判断sql语句的长度。

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

    进行参数绑定,bind指向一个数组,需保证此数组的元素数量和顺序与sql语句中的参数完全一致。TAOS_BIND 的使用方法与 MySQL中的 MYSQL_BIND 一致,具体定义如下:

  1. typedef struct TAOS_BIND {
  2. int buffer_type;
  3. void * buffer;
  4. unsigned long buffer_length; // 未实际使用
  5. unsigned long *length;
  6. int * is_null;
  7. int is_unsigned; // 未实际使用
  8. int * error; // 未实际使用
  9. } TAOS_BIND;
  • int taos_stmt_add_batch(TAOS_STMT *stmt)

    将当前绑定的参数加入批处理中,调用此函数后,可以再次调用taos_stmt_bind_param绑定新的参数。需要注意,此函数仅支持 insert/import 语句,如果是select等其他SQL语句,将返回错误。

  • int taos_stmt_execute(TAOS_STMT *stmt)

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

  • TAOS_RES* taos_stmt_use_result(TAOS_STMT *stmt)

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

  • int taos_stmt_close(TAOS_STMT *stmt)

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

连续查询接口

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:是流式计算开始的时间,如果是0,表示从现在开始,如果不为零,表示从指定的时间开始计算(UTC时间从1970/1/1算起的毫秒数)
    • param:是应用提供的用于回调的一个参数,回调时,提供给应用
    • callback: 第二个回调函数,会在连续查询自动停止时被调用。

    返回值为NULL,表示创建成功,返回值不为空,表示成功。

  • 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,其参数为:

    • taos:已经建立好的数据库连接
    • restart:如果订阅已经存在,是重新开始,还是继续之前的订阅
    • topic:订阅的主题(即名称),此参数是订阅的唯一标识
    • sql:订阅的查询语句,此语句只能是 select 语句,只应查询原始数据,只能按时间正序查询数据
    • fp:收到查询结果时的回调函数(稍后介绍函数原型),只在异步调用时使用,同步调用时此参数应该传 NULL
    • param:调用回调函数时的附加参数,系统API将其原样传递到回调函数,不进行任何处理
    • interval:轮询周期,单位为毫秒。异步调用时,将根据此参数周期性的调用回调函数,为避免对系统性能造成影响,不建议将此参数设置的过小;同步调用时,如两次调用taos_consume的间隔小于此周期,API将会阻塞,直到时间间隔超过此周期。
  • typedef void (*TAOS_SUBSCRIBE_CALLBACK)(TAOS_SUB* tsub, TAOS_RES *res, void* param, int code)

    异步模式下,回调函数的原型,其参数为:

    • tsub:订阅对象
    • res:查询结果集,注意结果集中可能没有记录
    • param:调用 taos_subscribe时客户程序提供的附加参数
    • code:错误码
  • TAOS_RES *taos_consume(TAOS_SUB *tsub)

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

  • void taos_unsubscribe(TAOS_SUB *tsub, int keepProgress)

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