Skip to main content

C/C++ Connector

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

#include <taos.h>

TDengine 服务端或客户端安装后,taos.h 位于:

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

TDengine 客户端驱动的动态库位于:

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

支持的平台

请参考支持的平台列表

支持的版本

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

安装步骤

TDengine 客户端驱动的安装请参考 安装指南

建立连接

使用客户端驱动访问 TDengine 集群的基本过程为:建立连接、查询和写入、关闭连接、清除资源。

下面为建立连接的示例代码,其中省略了查询和写入部分,展示了如何建立连接、关闭连接以及清除资源。

  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 文件中。

示例程序

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

同步查询示例

同步查询
/*
* Copyright (c) 2019 TAOS Data, Inc. <jhtao@taosdata.com>
*
* 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 <http://www.gnu.org/licenses/>.
*/

// TAOS standard API example. The same syntax as MySQL, but only a subset
// to compile: gcc -o demo demo.c -ltaos

#include <inttypes.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "taos.h" // TAOS header file

static void queryDB(TAOS *taos, char *command) {
int i;
TAOS_RES *pSql = NULL;
int32_t code = -1;

for (i = 0; i < 5; i++) {
if (NULL != pSql) {
taos_free_result(pSql);
pSql = NULL;
}

pSql = taos_query(taos, command);
code = taos_errno(pSql);
if (0 == code) {
break;
}
}

if (code != 0) {
fprintf(stderr, "Failed to run %s, reason: %s\n", command, taos_errstr(pSql));
taos_free_result(pSql);
taos_close(taos);
exit(EXIT_FAILURE);
}

taos_free_result(pSql);
}

void Test(TAOS *taos, char *qstr, int i);

int main(int argc, char *argv[]) {
char qstr[1024];

// connect to server
if (argc < 2) {
printf("please input server-ip \n");
return 0;
}

TAOS *taos = taos_connect(argv[1], "root", "taosdata", NULL, 0);
if (taos == NULL) {
printf("failed to connect to server, reason:%s\n", "null taos"/*taos_errstr(taos)*/);
exit(1);
}
for (int i = 0; i < 100; i++) {
Test(taos, qstr, i);
}
taos_close(taos);
taos_cleanup();
}
void Test(TAOS *taos, char *qstr, int index) {
printf("==================test at %d\n================================", index);
queryDB(taos, "drop database if exists demo");
queryDB(taos, "create database demo");
TAOS_RES *result;
queryDB(taos, "use demo");

queryDB(taos, "create table m1 (ts timestamp, ti tinyint, si smallint, i int, bi bigint, f float, d double, b binary(10))");
printf("success to create table\n");

int i = 0;
for (i = 0; i < 10; ++i) {
sprintf(qstr, "insert into m1 values (%" PRId64 ", %d, %d, %d, %d, %f, %lf, '%s')", (uint64_t)(1546300800000 + i * 1000), i, i, i, i*10000000, i*1.0, i*2.0, "hello");
printf("qstr: %s\n", qstr);

// note: how do you wanna do if taos_query returns non-NULL
// if (taos_query(taos, qstr)) {
// printf("insert row: %i, reason:%s\n", i, taos_errstr(taos));
// }
TAOS_RES *result1 = taos_query(taos, qstr);
if (result1 == NULL || taos_errno(result1) != 0) {
printf("failed to insert row, reason:%s\n", taos_errstr(result1));
taos_free_result(result1);
exit(1);
} else {
printf("insert row: %i\n", i);
}
taos_free_result(result1);
}
printf("success to insert rows, total %d rows\n", i);

// query the records
sprintf(qstr, "SELECT * FROM m1");
result = taos_query(taos, qstr);
if (result == NULL || taos_errno(result) != 0) {
printf("failed to select, reason:%s\n", taos_errstr(result));
taos_free_result(result);
exit(1);
}

TAOS_ROW row;
int rows = 0;
int num_fields = taos_field_count(result);
TAOS_FIELD *fields = taos_fetch_fields(result);

printf("num_fields = %d\n", num_fields);
printf("select * from table, result:\n");
// 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);
}

taos_free_result(result);
printf("====demo end====\n\n");
}


查看源码 格式化输出不同类型字段函数 taos_print_row

int taos_print_row(char *str, TAOS_ROW row, TAOS_FIELD *fields, int num_fields) {
int32_t len = 0;
for (int i = 0; i < num_fields; ++i) {
if (i > 0) {
str[len++] = ' ';
}

if (row[i] == NULL) {
len += sprintf(str + len, "%s", TSDB_DATA_NULL_STR);
continue;
}

switch (fields[i].type) {
case TSDB_DATA_TYPE_TINYINT:
len += sprintf(str + len, "%d", *((int8_t *)row[i]));
break;

case TSDB_DATA_TYPE_UTINYINT:
len += sprintf(str + len, "%u", *((uint8_t *)row[i]));
break;

case TSDB_DATA_TYPE_SMALLINT:
len += sprintf(str + len, "%d", *((int16_t *)row[i]));
break;

case TSDB_DATA_TYPE_USMALLINT:
len += sprintf(str + len, "%u", *((uint16_t *)row[i]));
break;

case TSDB_DATA_TYPE_INT:
len += sprintf(str + len, "%d", *((int32_t *)row[i]));
break;

case TSDB_DATA_TYPE_UINT:
len += sprintf(str + len, "%u", *((uint32_t *)row[i]));
break;

case TSDB_DATA_TYPE_BIGINT:
len += sprintf(str + len, "%" PRId64, *((int64_t *)row[i]));
break;

case TSDB_DATA_TYPE_UBIGINT:
len += sprintf(str + len, "%" PRIu64, *((uint64_t *)row[i]));
break;

case TSDB_DATA_TYPE_FLOAT: {
float fv = 0;
fv = GET_FLOAT_VAL(row[i]);
len += sprintf(str + len, "%f", fv);
} break;

case TSDB_DATA_TYPE_DOUBLE: {
double dv = 0;
dv = GET_DOUBLE_VAL(row[i]);
len += sprintf(str + len, "%lf", dv);
} break;

case TSDB_DATA_TYPE_BINARY:
case TSDB_DATA_TYPE_NCHAR: {
int32_t charLen = varDataLen((char *)row[i] - VARSTR_HEADER_SIZE);
if (fields[i].type == TSDB_DATA_TYPE_BINARY) {
assert(charLen <= fields[i].bytes && charLen >= 0);
} else {
assert(charLen <= fields[i].bytes * TSDB_NCHAR_SIZE && charLen >= 0);
}

memcpy(str + len, row[i], charLen);
len += charLen;
} break;

case TSDB_DATA_TYPE_TIMESTAMP:
len += sprintf(str + len, "%" PRId64, *((int64_t *)row[i]));
break;

case TSDB_DATA_TYPE_BOOL:
len += sprintf(str + len, "%d", *((int8_t *)row[i]));
default:
break;
}
}
str[len] = 0;

return len;
}

异步查询示例

异步查询
/*
* Copyright (c) 2019 TAOS Data, Inc. <jhtao@taosdata.com>
*
* 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 <http://www.gnu.org/licenses/>.
*/

// TAOS asynchronous API example
// this example opens multiple tables, insert/retrieve multiple tables
// it is used by TAOS internally for one performance testing
// to compiple: gcc -o asyncdemo asyncdemo.c -ltaos

#include <stdio.h>
#include <stdlib.h>
#include <sys/time.h>
#include <unistd.h>
#include <string.h>
#include <inttypes.h>
#include "taos.h"

int points = 5;
int numOfTables = 3;
int tablesInsertProcessed = 0;
int tablesSelectProcessed = 0;
int64_t st, et;

typedef struct {
int id;
TAOS *taos;
char name[32];
time_t timeStamp;
int value;
int rowsInserted;
int rowsTried;
int rowsRetrieved;
} STable;

void taos_insert_call_back(void *param, TAOS_RES *tres, int code);
void taos_select_call_back(void *param, TAOS_RES *tres, int code);
void shellPrintError(TAOS *taos);

static void queryDB(TAOS *taos, char *command) {
int i;
TAOS_RES *pSql = NULL;
int32_t code = -1;

for (i = 0; i < 5; i++) {
if (NULL != pSql) {
taos_free_result(pSql);
pSql = NULL;
}

pSql = taos_query(taos, command);
code = taos_errno(pSql);
if (0 == code) {
break;
}
}

if (code != 0) {
fprintf(stderr, "Failed to run %s, reason: %s\n", command, taos_errstr(pSql));
taos_free_result(pSql);
taos_close(taos);
taos_cleanup();
exit(EXIT_FAILURE);
}

taos_free_result(pSql);
}

int main(int argc, char *argv[])
{
TAOS *taos;
struct timeval systemTime;
int i;
char sql[1024] = { 0 };
char prefix[20] = { 0 };
char db[128] = { 0 };
STable *tableList;

if (argc != 5) {
printf("usage: %s server-ip dbname rowsPerTable numOfTables\n", argv[0]);
exit(0);
}

// a simple way to parse input parameters
if (argc >= 3) strcpy(db, argv[2]);
if (argc >= 4) points = atoi(argv[3]);
if (argc >= 5) numOfTables = atoi(argv[4]);

size_t size = sizeof(STable) * (size_t)numOfTables;
tableList = (STable *)malloc(size);
memset(tableList, 0, size);

taos = taos_connect(argv[1], "root", "taosdata", NULL, 0);
if (taos == NULL)
shellPrintError(taos);

printf("success to connect to server\n");

sprintf(sql, "drop database if exists %s", db);
queryDB(taos, sql);

sprintf(sql, "create database %s", db);
queryDB(taos, sql);

sprintf(sql, "use %s", db);
queryDB(taos, sql);

strcpy(prefix, "asytbl_");
for (i = 0; i < numOfTables; ++i) {
tableList[i].id = i;
tableList[i].taos = taos;
sprintf(tableList[i].name, "%s%d", prefix, i);
sprintf(sql, "create table %s%d (ts timestamp, volume bigint)", prefix, i);
queryDB(taos, sql);
}

gettimeofday(&systemTime, NULL);
for (i = 0; i < numOfTables; ++i)
tableList[i].timeStamp = (time_t)(systemTime.tv_sec) * 1000 + systemTime.tv_usec / 1000;

printf("success to create tables, press any key to insert\n");
getchar();

printf("start to insert...\n");
gettimeofday(&systemTime, NULL);
st = systemTime.tv_sec * 1000000 + systemTime.tv_usec;

tablesInsertProcessed = 0;
tablesSelectProcessed = 0;

for (i = 0; i<numOfTables; ++i) {
// insert records in asynchronous API
sprintf(sql, "insert into %s values(%ld, 0)", tableList[i].name, 1546300800000 + i);
taos_query_a(taos, sql, taos_insert_call_back, (void *)(tableList + i));
}

printf("once insert finished, presse any key to query\n");
getchar();

while(1) {
if (tablesInsertProcessed < numOfTables) {
printf("wait for process finished\n");
sleep(1);
continue;
}

break;
}

printf("start to query...\n");
gettimeofday(&systemTime, NULL);
st = systemTime.tv_sec * 1000000 + systemTime.tv_usec;


for (i = 0; i < numOfTables; ++i) {
// select records in asynchronous API
sprintf(sql, "select * from %s", tableList[i].name);
taos_query_a(taos, sql, taos_select_call_back, (void *)(tableList + i));
}

printf("\nonce finished, press any key to exit\n");
getchar();

while(1) {
if (tablesSelectProcessed < numOfTables) {
printf("wait for process finished\n");
sleep(1);
continue;
}

break;
}

for (i = 0; i<numOfTables; ++i) {
printf("%s inserted:%d retrieved:%d\n", tableList[i].name, tableList[i].rowsInserted, tableList[i].rowsRetrieved);
}

taos_close(taos);
free(tableList);

printf("==== async demo end====\n");
printf("\n");
return 0;
}

void shellPrintError(TAOS *con)
{
fprintf(stderr, "TDengine error: %s\n", taos_errstr(con));
taos_close(con);
taos_cleanup();
exit(1);
}

void taos_insert_call_back(void *param, TAOS_RES *tres, int code)
{
STable *pTable = (STable *)param;
struct timeval systemTime;
char sql[128];

pTable->rowsTried++;

if (code < 0) {
printf("%s insert failed, code:%d, rows:%d\n", pTable->name, code, pTable->rowsTried);
}
else if (code == 0) {
printf("%s not inserted\n", pTable->name);
}
else {
pTable->rowsInserted++;
}

if (pTable->rowsTried < points) {
// for this demo, insert another record
sprintf(sql, "insert into %s values(%ld, %d)", pTable->name, 1546300800000+pTable->rowsTried*1000, pTable->rowsTried);
taos_query_a(pTable->taos, sql, taos_insert_call_back, (void *)pTable);
}
else {
printf("%d rows data are inserted into %s\n", points, pTable->name);
tablesInsertProcessed++;
if (tablesInsertProcessed >= numOfTables) {
gettimeofday(&systemTime, NULL);
et = systemTime.tv_sec * 1000000 + systemTime.tv_usec;
printf("%" PRId64 " mseconds to insert %d data points\n", (et - st) / 1000, points*numOfTables);
}
}

taos_free_result(tres);
}

void taos_retrieve_call_back(void *param, TAOS_RES *tres, int numOfRows)
{
STable *pTable = (STable *)param;
struct timeval systemTime;

if (numOfRows > 0) {

for (int i = 0; i<numOfRows; ++i) {
// synchronous API to retrieve a row from batch of records
/*TAOS_ROW row = */(void)taos_fetch_row(tres);
// process row
}

pTable->rowsRetrieved += numOfRows;

// retrieve next batch of rows
taos_fetch_rows_a(tres, taos_retrieve_call_back, pTable);

}
else {
if (numOfRows < 0)
printf("%s retrieve failed, code:%d\n", pTable->name, numOfRows);

//taos_free_result(tres);
printf("%d rows data retrieved from %s\n", pTable->rowsRetrieved, pTable->name);

tablesSelectProcessed++;
if (tablesSelectProcessed >= numOfTables) {
gettimeofday(&systemTime, NULL);
et = systemTime.tv_sec * 1000000 + systemTime.tv_usec;
printf("%" PRId64 " mseconds to query %d data rows\n", (et - st) / 1000, points * numOfTables);
}

taos_free_result(tres);
}


}

void taos_select_call_back(void *param, TAOS_RES *tres, int code)
{
STable *pTable = (STable *)param;

if (code == 0 && tres) {
// asynchronous API to fetch a batch of records
taos_fetch_rows_a(tres, taos_retrieve_call_back, pTable);
}
else {
printf("%s select failed, code:%d\n", pTable->name, code);
taos_free_result(tres);
taos_cleanup();
exit(1);
}
}

查看源码

参数绑定示例

参数绑定
// TAOS standard API example. The same syntax as MySQL, but only a subet 
// to compile: gcc -o prepare prepare.c -ltaos

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "taos.h"

void taosMsleep(int mseconds);

int main(int argc, char *argv[])
{
TAOS *taos;
TAOS_RES *result;
int code;
TAOS_STMT *stmt;

// connect to server
if (argc < 2) {
printf("please input server ip \n");
return 0;
}

taos = taos_connect(argv[1], "root", "taosdata", NULL, 0);
if (taos == NULL) {
printf("failed to connect to db, reason:%s\n", taos_errstr(taos));
exit(1);
}

result = taos_query(taos, "drop database demo");
taos_free_result(result);

result = taos_query(taos, "create database demo");
code = taos_errno(result);
if (code != 0) {
printf("failed to create database, reason:%s\n", taos_errstr(result));
taos_free_result(result);
exit(1);
}
taos_free_result(result);

result = taos_query(taos, "use demo");
taos_free_result(result);

// create table
const char* sql = "create table m1 (ts timestamp, b bool, v1 tinyint, v2 smallint, v4 int, v8 bigint, f4 float, f8 double, bin binary(40), blob nchar(10))";
result = taos_query(taos, sql);
code = taos_errno(result);
if (code != 0) {
printf("failed to create table, reason:%s\n", taos_errstr(result));
taos_free_result(result);
exit(1);
}
taos_free_result(result);

// sleep for one second to make sure table is created on data node
// taosMsleep(1000);

// insert 10 records
struct {
int64_t ts;
int8_t b;
int8_t v1;
int16_t v2;
int32_t v4;
int64_t v8;
float f4;
double f8;
char bin[40];
char blob[80];
} v = {0};

int32_t boolLen = sizeof(int8_t);
int32_t sintLen = sizeof(int16_t);
int32_t intLen = sizeof(int32_t);
int32_t bintLen = sizeof(int64_t);
int32_t floatLen = sizeof(float);
int32_t doubleLen = sizeof(double);
int32_t binLen = sizeof(v.bin);
int32_t ncharLen = 30;

stmt = taos_stmt_init(taos);
TAOS_MULTI_BIND params[10];
params[0].buffer_type = TSDB_DATA_TYPE_TIMESTAMP;
params[0].buffer_length = sizeof(v.ts);
params[0].buffer = &v.ts;
params[0].length = &bintLen;
params[0].is_null = NULL;
params[0].num = 1;

params[1].buffer_type = TSDB_DATA_TYPE_BOOL;
params[1].buffer_length = sizeof(v.b);
params[1].buffer = &v.b;
params[1].length = &boolLen;
params[1].is_null = NULL;
params[1].num = 1;

params[2].buffer_type = TSDB_DATA_TYPE_TINYINT;
params[2].buffer_length = sizeof(v.v1);
params[2].buffer = &v.v1;
params[2].length = &boolLen;
params[2].is_null = NULL;
params[2].num = 1;

params[3].buffer_type = TSDB_DATA_TYPE_SMALLINT;
params[3].buffer_length = sizeof(v.v2);
params[3].buffer = &v.v2;
params[3].length = &sintLen;
params[3].is_null = NULL;
params[3].num = 1;

params[4].buffer_type = TSDB_DATA_TYPE_INT;
params[4].buffer_length = sizeof(v.v4);
params[4].buffer = &v.v4;
params[4].length = &intLen;
params[4].is_null = NULL;
params[4].num = 1;

params[5].buffer_type = TSDB_DATA_TYPE_BIGINT;
params[5].buffer_length = sizeof(v.v8);
params[5].buffer = &v.v8;
params[5].length = &bintLen;
params[5].is_null = NULL;
params[5].num = 1;

params[6].buffer_type = TSDB_DATA_TYPE_FLOAT;
params[6].buffer_length = sizeof(v.f4);
params[6].buffer = &v.f4;
params[6].length = &floatLen;
params[6].is_null = NULL;
params[6].num = 1;

params[7].buffer_type = TSDB_DATA_TYPE_DOUBLE;
params[7].buffer_length = sizeof(v.f8);
params[7].buffer = &v.f8;
params[7].length = &doubleLen;
params[7].is_null = NULL;
params[7].num = 1;

params[8].buffer_type = TSDB_DATA_TYPE_BINARY;
params[8].buffer_length = sizeof(v.bin);
params[8].buffer = v.bin;
params[8].length = &binLen;
params[8].is_null = NULL;
params[8].num = 1;

strcpy(v.blob, "一二三四五六七八九十");
params[9].buffer_type = TSDB_DATA_TYPE_NCHAR;
params[9].buffer_length = sizeof(v.blob);
params[9].buffer = v.blob;
params[9].length = &ncharLen;
params[9].is_null = NULL;
params[9].num = 1;

char is_null = 1;

sql = "insert into m1 values(?,?,?,?,?,?,?,?,?,?)";
code = taos_stmt_prepare(stmt, sql, 0);
if (code != 0){
printf("failed to execute taos_stmt_prepare. code:0x%x\n", code);
}
v.ts = 1591060628000;
for (int i = 0; i < 10; ++i) {
v.ts += 1;
for (int j = 1; j < 10; ++j) {
params[j].is_null = ((i == j) ? &is_null : 0);
}
v.b = (int8_t)i % 2;
v.v1 = (int8_t)i;
v.v2 = (int16_t)(i * 2);
v.v4 = (int32_t)(i * 4);
v.v8 = (int64_t)(i * 8);
v.f4 = (float)(i * 40);
v.f8 = (double)(i * 80);
for (int j = 0; j < sizeof(v.bin); ++j) {
v.bin[j] = (char)(i + '0');
}

taos_stmt_bind_param(stmt, params);
taos_stmt_add_batch(stmt);
}
if (taos_stmt_execute(stmt) != 0) {
printf("failed to execute insert statement.\n");
exit(1);
}
taos_stmt_close(stmt);

// query the records
stmt = taos_stmt_init(taos);
taos_stmt_prepare(stmt, "SELECT * FROM m1 WHERE v1 > ? AND v2 < ?", 0);
v.v1 = 5;
v.v2 = 15;
taos_stmt_bind_param(stmt, params + 2);
if (taos_stmt_execute(stmt) != 0) {
printf("failed to execute select statement.\n");
exit(1);
}

result = taos_stmt_use_result(stmt);

TAOS_ROW row;
int rows = 0;
int num_fields = taos_num_fields(result);
TAOS_FIELD *fields = taos_fetch_fields(result);

// fetch the records row by row
while ((row = taos_fetch_row(result))) {
char temp[256] = {0};
rows++;
taos_print_row(temp, row, fields, num_fields);
printf("%s\n", temp);
}
if (rows == 2) {
printf("two rows are fetched as expectation\n");
} else {
printf("expect two rows, but %d rows are fetched\n", rows);
}

taos_free_result(result);
taos_stmt_close(stmt);

return 0;
}


查看源码

无模式写入示例

无模式写入
#include "taos.h"
#include <stdio.h>
#include <stdlib.h>
#include <sys/time.h>
#include <time.h>
#include <unistd.h>
#include <inttypes.h>
#include <string.h>


int numSuperTables = 8;
int numChildTables = 4;
int numRowsPerChildTable = 2048;

static int64_t getTimeInUs() {
struct timeval systemTime;
gettimeofday(&systemTime, NULL);
return (int64_t)systemTime.tv_sec * 1000000L + (int64_t)systemTime.tv_usec;
}

int main(int argc, char* argv[]) {
TAOS_RES *result;
const char* host = "127.0.0.1";
const char* user = "root";
const char* passwd = "taosdata";

taos_options(TSDB_OPTION_TIMEZONE, "GMT-8");
TAOS* taos = taos_connect(host, user, passwd, "", 0);
if (taos == NULL) {
printf("\033[31mfailed to connect to db, reason:%s\033[0m\n", taos_errstr(taos));
exit(1);
}

const char* info = taos_get_server_info(taos);
printf("server info: %s\n", info);
info = taos_get_client_info(taos);
printf("client info: %s\n", info);
result = taos_query(taos, "drop database if exists db;");
taos_free_result(result);
usleep(100000);
result = taos_query(taos, "create database db precision 'ms';");
taos_free_result(result);
usleep(100000);

(void)taos_select_db(taos, "db");

time_t ct = time(0);
int64_t ts = ct * 1000;
char* lineFormat = "sta%d,t0=true,t1=127i8,t2=32767i16,t3=%di32,t4=9223372036854775807i64,t9=11.12345f32,t10=22.123456789f64,t11=\"binaryTagValue\",t12=L\"ncharTagValue\" c0=true,c1=127i8,c2=32767i16,c3=2147483647i32,c4=9223372036854775807i64,c5=254u8,c6=32770u16,c7=2147483699u32,c8=9223372036854775899u64,c9=11.12345f32,c10=22.123456789f64,c11=\"binaryValue\",c12=L\"ncharValue\" %" PRId64;

int lineNum = numSuperTables * numChildTables * numRowsPerChildTable;
char** lines = calloc((size_t)lineNum, sizeof(char*));
int l = 0;
for (int i = 0; i < numSuperTables; ++i) {
for (int j = 0; j < numChildTables; ++j) {
for (int k = 0; k < numRowsPerChildTable; ++k) {
char* line = calloc(512, 1);
snprintf(line, 512, lineFormat, i, j, ts + 10 * l);
lines[l] = line;
++l;
}
}
}

printf("%s\n", "begin taos_insert_lines");
int64_t begin = getTimeInUs();
TAOS_RES *res = taos_schemaless_insert(taos, lines, lineNum, TSDB_SML_LINE_PROTOCOL, TSDB_SML_TIMESTAMP_MILLI_SECONDS);
int64_t end = getTimeInUs();
printf("code: %s. time used: %" PRId64 "\n", taos_errstr(res), end-begin);
taos_free_result(res);

return 0;
}

查看源码

订阅和消费示例

订阅和消费
/*
* Copyright (c) 2019 TAOS Data, Inc. <jhtao@taosdata.com>
*
* 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 <http://www.gnu.org/licenses/>.
*/

#include <assert.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>
#include "taos.h"

static int running = 1;

static int32_t msg_process(TAOS_RES* msg) {
char buf[1024];
int32_t rows = 0;

const char* topicName = tmq_get_topic_name(msg);
const char* dbName = tmq_get_db_name(msg);
int32_t vgroupId = tmq_get_vgroup_id(msg);

printf("topic: %s\n", topicName);
printf("db: %s\n", dbName);
printf("vgroup id: %d\n", vgroupId);

while (1) {
TAOS_ROW row = taos_fetch_row(msg);
if (row == NULL) break;

TAOS_FIELD* fields = taos_fetch_fields(msg);
int32_t numOfFields = taos_field_count(msg);
// int32_t* length = taos_fetch_lengths(msg);
int32_t precision = taos_result_precision(msg);
rows++;
taos_print_row(buf, row, fields, numOfFields);
printf("precision: %d, row content: %s\n", precision, buf);
}

return rows;
}

static int32_t init_env() {
TAOS* pConn = taos_connect("localhost", "root", "taosdata", NULL, 0);
if (pConn == NULL) {
return -1;
}

TAOS_RES* pRes;
// drop database if exists
printf("create database\n");
pRes = taos_query(pConn, "drop topic topicname");
if (taos_errno(pRes) != 0) {
printf("error in drop tmqdb, reason:%s\n", taos_errstr(pRes));
}
taos_free_result(pRes);

pRes = taos_query(pConn, "drop database if exists tmqdb");
if (taos_errno(pRes) != 0) {
printf("error in drop tmqdb, reason:%s\n", taos_errstr(pRes));
}
taos_free_result(pRes);

// create database
pRes = taos_query(pConn, "create database tmqdb precision 'ns'");
if (taos_errno(pRes) != 0) {
printf("error in create tmqdb, reason:%s\n", taos_errstr(pRes));
goto END;
}
taos_free_result(pRes);

// create super table
printf("create super table\n");
pRes = taos_query(
pConn, "create table tmqdb.stb (ts timestamp, c1 int, c2 float, c3 varchar(16)) tags(t1 int, t3 varchar(16))");
if (taos_errno(pRes) != 0) {
printf("failed to create super table stb, reason:%s\n", taos_errstr(pRes));
goto END;
}
taos_free_result(pRes);

// create sub tables
printf("create sub tables\n");
pRes = taos_query(pConn, "create table tmqdb.ctb0 using tmqdb.stb tags(0, 'subtable0')");
if (taos_errno(pRes) != 0) {
printf("failed to create super table ctb0, reason:%s\n", taos_errstr(pRes));
goto END;
}
taos_free_result(pRes);

pRes = taos_query(pConn, "create table tmqdb.ctb1 using tmqdb.stb tags(1, 'subtable1')");
if (taos_errno(pRes) != 0) {
printf("failed to create super table ctb1, reason:%s\n", taos_errstr(pRes));
goto END;
}
taos_free_result(pRes);

pRes = taos_query(pConn, "create table tmqdb.ctb2 using tmqdb.stb tags(2, 'subtable2')");
if (taos_errno(pRes) != 0) {
printf("failed to create super table ctb2, reason:%s\n", taos_errstr(pRes));
goto END;
}
taos_free_result(pRes);

pRes = taos_query(pConn, "create table tmqdb.ctb3 using tmqdb.stb tags(3, 'subtable3')");
if (taos_errno(pRes) != 0) {
printf("failed to create super table ctb3, reason:%s\n", taos_errstr(pRes));
goto END;
}
taos_free_result(pRes);

// insert data
printf("insert data into sub tables\n");
pRes = taos_query(pConn, "insert into tmqdb.ctb0 values(now, 0, 0, 'a0')(now+1s, 0, 0, 'a00')");
if (taos_errno(pRes) != 0) {
printf("failed to insert into ctb0, reason:%s\n", taos_errstr(pRes));
goto END;
}
taos_free_result(pRes);

pRes = taos_query(pConn, "insert into tmqdb.ctb1 values(now, 1, 1, 'a1')(now+1s, 11, 11, 'a11')");
if (taos_errno(pRes) != 0) {
printf("failed to insert into ctb0, reason:%s\n", taos_errstr(pRes));
goto END;
}
taos_free_result(pRes);

pRes = taos_query(pConn, "insert into tmqdb.ctb2 values(now, 2, 2, 'a1')(now+1s, 22, 22, 'a22')");
if (taos_errno(pRes) != 0) {
printf("failed to insert into ctb0, reason:%s\n", taos_errstr(pRes));
goto END;
}
taos_free_result(pRes);

pRes = taos_query(pConn, "insert into tmqdb.ctb3 values(now, 3, 3, 'a1')(now+1s, 33, 33, 'a33')");
if (taos_errno(pRes) != 0) {
printf("failed to insert into ctb0, reason:%s\n", taos_errstr(pRes));
goto END;
}
taos_free_result(pRes);
taos_close(pConn);
return 0;

END:
taos_free_result(pRes);
taos_close(pConn);
return -1;
}

int32_t create_topic() {
printf("create topic\n");
TAOS_RES* pRes;
TAOS* pConn = taos_connect("localhost", "root", "taosdata", NULL, 0);
if (pConn == NULL) {
return -1;
}

pRes = taos_query(pConn, "use tmqdb");
if (taos_errno(pRes) != 0) {
printf("error in use tmqdb, reason:%s\n", taos_errstr(pRes));
return -1;
}
taos_free_result(pRes);

pRes = taos_query(pConn, "create topic topicname as select ts, c1, c2, c3, tbname from tmqdb.stb where c1 > 1");
if (taos_errno(pRes) != 0) {
printf("failed to create topic topicname, reason:%s\n", taos_errstr(pRes));
return -1;
}
taos_free_result(pRes);

taos_close(pConn);
return 0;
}

void tmq_commit_cb_print(tmq_t* tmq, int32_t code, void* param) {
printf("tmq_commit_cb_print() code: %d, tmq: %p, param: %p\n", code, tmq, param);
}

tmq_t* build_consumer() {
tmq_conf_res_t code;
tmq_conf_t* conf = tmq_conf_new();
code = tmq_conf_set(conf, "enable.auto.commit", "true");
if (TMQ_CONF_OK != code) return NULL;
code = tmq_conf_set(conf, "auto.commit.interval.ms", "1000");
if (TMQ_CONF_OK != code) return NULL;
code = tmq_conf_set(conf, "group.id", "cgrpName");
if (TMQ_CONF_OK != code) return NULL;
code = tmq_conf_set(conf, "client.id", "user defined name");
if (TMQ_CONF_OK != code) return NULL;
code = tmq_conf_set(conf, "td.connect.user", "root");
if (TMQ_CONF_OK != code) return NULL;
code = tmq_conf_set(conf, "td.connect.pass", "taosdata");
if (TMQ_CONF_OK != code) return NULL;
code = tmq_conf_set(conf, "auto.offset.reset", "earliest");
if (TMQ_CONF_OK != code) return NULL;
code = tmq_conf_set(conf, "experimental.snapshot.enable", "false");
if (TMQ_CONF_OK != code) return NULL;

tmq_conf_set_auto_commit_cb(conf, tmq_commit_cb_print, NULL);

tmq_t* tmq = tmq_consumer_new(conf, NULL, 0);
tmq_conf_destroy(conf);
return tmq;
}

tmq_list_t* build_topic_list() {
tmq_list_t* topicList = tmq_list_new();
int32_t code = tmq_list_append(topicList, "topicname");
if (code) {
tmq_list_destroy(topicList);
return NULL;
}
return topicList;
}

void basic_consume_loop(tmq_t* tmq) {
int32_t totalRows = 0;
int32_t msgCnt = 0;
int32_t timeout = 5000;
while (running) {
TAOS_RES* tmqmsg = tmq_consumer_poll(tmq, timeout);
if (tmqmsg) {
msgCnt++;
totalRows += msg_process(tmqmsg);
taos_free_result(tmqmsg);
} else {
break;
}
}

fprintf(stderr, "%d msg consumed, include %d rows\n", msgCnt, totalRows);
}

int main(int argc, char* argv[]) {
int32_t code;

if (init_env() < 0) {
return -1;
}

if (create_topic() < 0) {
return -1;
}

tmq_t* tmq = build_consumer();
if (NULL == tmq) {
fprintf(stderr, "build_consumer() fail!\n");
return -1;
}

tmq_list_t* topic_list = build_topic_list();
if (NULL == topic_list) {
return -1;
}

if ((code = tmq_subscribe(tmq, topic_list))) {
fprintf(stderr, "Failed to tmq_subscribe(): %s\n", tmq_err2str(code));
}
tmq_list_destroy(topic_list);

basic_consume_loop(tmq);

code = tmq_consumer_close(tmq);
if (code) {
fprintf(stderr, "Failed to close consumer: %s\n", tmq_err2str(code));
} else {
fprintf(stderr, "Consumer closed\n");
}

return 0;
}

查看源码

info

更多示例代码及下载请见 GitHub。 也可以在安装目录下的 examples/c 路径下找到。 该目录下有 makefile,在 Linux/macOS 环境下,直接执行 make 就可以编译得到执行文件。 提示:在 ARM 环境下编译时,请将 makefile 中的 -msse4.2 去掉,这个选项只有在 x64/x86 硬件平台上才能支持。

API 参考

以下分别介绍 TDengine 客户端驱动的基础 API、同步 API、异步 API、订阅 API 和无模式写入 API。

基础 API

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

  • void taos_init()

    初始化运行环境。如果没有主动调用该 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)。区域设置、字符集、时区默认为操作系统当前设置。

  • 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 程序监听的端口

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

    info

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

  • 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 均属于同步接口。应用调用后,会阻塞等待响应,直到获得返回结果或错误信息。

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

    执行 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 的结构如下:

typedef struct taosField {
char name[65]; // column name
uint8_t type; // data type
int16_t bytes; // length, in bytes
} TAOS_FIELD;
  • void taos_stop_query(TAOS_RES *res)

    停止当前查询的执行。

  • void taos_free_result(TAOS_RES *res)

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

  • char *taos_errstr(TAOS_RES *res)

    获取最近一次 API 调用失败的原因,返回值为字符串标识的错误提示信息。

  • int taos_errno(TAOS_RES *res)

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

note

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

异步查询 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 类似,目前也仅支持用问号 ? 来代表待绑定的参数。

从 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() 把当前绑定的参数加入批处理;
  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)

    创建一个 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)

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

    typedef struct TAOS_BIND {
    int buffer_type;
    void * buffer;
    uintptr_t buffer_length; // not in use
    uintptr_t * length;
    int * is_null;
    int is_unsigned; // not in use
    int * error; // not in use
    } TAOS_BIND;
  • int taos_stmt_set_tbname(TAOS_STMT* stmt, const char* name)

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

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

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

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

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

    typedef struct TAOS_MULTI_BIND {
    int buffer_type;
    void * buffer;
    uintptr_t buffer_length;
    uintptr_t * length;
    char * is_null;
    int num; // the number of columns
    } TAOS_MULTI_BIND;
  • int taos_stmt_add_batch(TAOS_STMT *stmt)

    将当前绑定的参数加入批处理中,调用此函数后,可以再次调用 taos_stmt_bind_param()taos_stmt_bind_param_batch() 绑定新的参数。需要注意,此函数仅支持 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)

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

  • char * taos_stmt_errstr(TAOS_STMT *stmt)

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

无模式(schemaless)写入 API

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

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

    功能说明 该接口将行协议的文本数据写入到 TDengine 中。

    参数说明 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 的文本协议,时间戳的解析遵循其官方解析规则 — 按照时间戳包含的字符的数量来确认时间精度。

    支持版本 该功能接口从 2.3.0.0 版本开始支持。