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 fcb70f2293..3a47f41d00 100644 --- a/docs/zh/08-develop/01-connect/index.md +++ b/docs/zh/08-develop/01-connect/index.md @@ -337,6 +337,34 @@ properties 中的配置参数如下： +使用客户端驱动访问 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 4fef3c8659..2325becfdf 100644 --- a/docs/zh/08-develop/02-sql.md +++ b/docs/zh/08-develop/02-sql.md @@ -35,6 +35,10 @@ TDengine 对 SQL 语言提供了全面的支持，允许用户以熟悉的 SQL +```c +{{#include docs/examples/c/CCreateDBDemo.c:create_db_and_table}} +``` +> **注意**：如果不使用 `USE power` 指定数据库，则后续对表的操作都需要增加数据库名称作为前缀，如 power.meters。 @@ -65,6 +69,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（年）。 @@ -95,6 +105,9 @@ NOW 为系统内部函数，默认为客户端所在计算机当前时间。 NOW +```c +{{#include docs/examples/c/CQueryDataDemo.c:query_data}} +``` @@ -133,6 +146,9 @@ reqId 可用于请求链路追踪，reqId 就像分布式系统中的 traceId +```c +{{#include docs/examples/c/CWithReqIdDemo.c:with_reqid}} +```