执行 SQL

来源涛思数据浏览 1 扫码打印 2026-10-26 14:01:31

执行 SQL

执行 SQL

TDengine 对 SQL 语言提供了全面的支持，允许用户以熟悉的 SQL 语法进行数据的查询、插入和删除操作。 TDengine 的 SQL 还支持对数据库和数据表的管理操作，如创建、修改和删除数据库及数据表。TDengine 扩展了标准 SQL，引入了时序数据处理特有的功能，如时间序列数据的聚合查询、降采样、插值查询等，以适应时序数据的特点。这些扩展使得用户可以更高效地处理时间序列数据，进行复杂的数据分析和处理。具体支持的 SQL 语法请参考 TDengine SQL

下面介绍使用各语言连接器通过执行 SQL 完成建库、建表、写入数据和查询数据。

备注

REST 连接：各编程语言的连接器封装使用 HTTP 请求的连接，支持数据写入和查询操作，开发者依然使用连接器提供的接口访问 TDengine。 REST API：直接调用 taosadapter 提供的 REST API 接口，进行数据写入和查询操作。代码示例使用 curl 命令来演示。

建库和表

下面以智能电表为例，展示使用各语言连接器如何执行 SQL 命令创建一个名为 power 的数据库，然后使用 power 数据库为默认数据库。接着创建一个名为 meters 的超级表（STABLE），其表结构包含时间戳、电流、电压、相位等列，以及分组 ID 和位置作为标签。

Java
Python
Go
Rust
Node.js
C#
C
REST API

1. try (Connection connection = DriverManager.getConnection(jdbcUrl, properties);
2. Statement stmt = connection.createStatement()) {

4. // create database
5. int rowsAffected = stmt.executeUpdate("CREATE DATABASE IF NOT EXISTS power");
6. // you can check rowsAffected here
7. System.out.println("Create database power successfully, rowsAffected: " + rowsAffected);
8. // create table
9. rowsAffected = stmt.executeUpdate("CREATE STABLE IF NOT EXISTS power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (groupId INT, location BINARY(24))");
10. // you can check rowsAffected here
11. System.out.println("Create stable power.meters successfully, rowsAffected: " + rowsAffected);
12. } catch (Exception ex) {
13. // please refer to the JDBC specifications for detailed exceptions info
14. System.out.printf("Failed to create database power or stable meters, %sErrMessage: %s%n",
15. ex instanceof SQLException ? "ErrCode: " + ((SQLException) ex).getErrorCode() + ", " : "",
16. ex.getMessage());
17. // Print stack trace for context in examples. Use logging in production.
18. ex.printStackTrace();
19. throw ex;
20. }

WebSocket 连接

1. import taosws

3. conn = None
4. host = "localhost"
5. port = 6041
6. try:
7. conn = taosws.connect(user="root",
8. password="taosdata",
9. host=host,
10. port=port)

12. # create database
13. rowsAffected = conn.execute(f"CREATE DATABASE IF NOT EXISTS power")
14. print(f"Create database power successfully, rowsAffected: {rowsAffected}");

16. # create super table
17. rowsAffected = conn.execute(
18. "CREATE TABLE IF NOT EXISTS power.meters (`ts` TIMESTAMP, `current` FLOAT, `voltage` INT, `phase` FLOAT) TAGS (`groupid` INT, `location` BINARY(16))"
19. )
20. print(f"Create stable power.meters successfully, rowsAffected: {rowsAffected}");

22. except Exception as err:
23. print(f"Failed to create database power or stable meters, ErrMessage:{err}")
24. raise err
25. finally:
26. if conn:
27. conn.close()

原生连接

1. import taos

3. conn = None
4. host = "localhost"
5. port = 6030
6. try:
7. conn = taos.connect(host=host,
8. port=port,
9. user="root",
10. password="taosdata")

12. # create database
13. rowsAffected = conn.execute(f"CREATE DATABASE IF NOT EXISTS power")
14. print(f"Create database power successfully, rowsAffected: {rowsAffected}");

16. # create super table
17. rowsAffected = conn.execute(
18. "CREATE TABLE IF NOT EXISTS power.meters (`ts` TIMESTAMP, `current` FLOAT, `voltage` INT, `phase` FLOAT) TAGS (`groupid` INT, `location` BINARY(16))"
19. )
20. print(f"Create stable power.meters successfully, rowsAffected: {rowsAffected}");

22. except Exception as err:
23. print(f"Failed to create database power or stable meters, ErrMessage:{err}")
24. raise err
25. finally:
26. if conn:
27. conn.close()

Rest 连接

1. import taosrest

3. conn = None
4. url = "http://localhost:6041"
5. try:
6. conn = taosrest.connect(url=url,
7. user="root",
8. password="taosdata",
9. timeout=30)

11. # create database
12. rowsAffected = conn.execute(f"CREATE DATABASE IF NOT EXISTS power")
13. print(f"Create database power successfully, rowsAffected: {rowsAffected}");

15. # create super table
16. rowsAffected = conn.execute(
17. f"CREATE TABLE IF NOT EXISTS power.meters (`ts` TIMESTAMP, `current` FLOAT, `voltage` INT, `phase` FLOAT) TAGS (`groupid` INT, `location` BINARY(16))"
18. )
19. print(f"Create stable power.meters successfully, rowsAffected: {rowsAffected}");

21. except Exception as err:
22. print(f"Failed to create database power or stable meters, ErrMessage:{err}")
23. raise err
24. finally:
25. if conn:
26. conn.close()

1. // create database
2. res, err := db.Exec("CREATE DATABASE IF NOT EXISTS power")
3. if err != nil {
4. log.Fatalln("Failed to create database power, ErrMessage: " + err.Error())
5. }
6. rowsAffected, err := res.RowsAffected()
7. if err != nil {
8. log.Fatalln("Failed to get create database rowsAffected, ErrMessage: " + err.Error())
9. }
10. // you can check rowsAffected here
11. fmt.Println("Create database power successfully, rowsAffected: ", rowsAffected)
12. // create table
13. res, err = db.Exec("CREATE STABLE IF NOT EXISTS power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (groupId INT, location BINARY(24))")
14. if err != nil {
15. log.Fatalln("Failed to create stable meters, ErrMessage: " + err.Error())
16. }
17. rowsAffected, err = res.RowsAffected()
18. if err != nil {
19. log.Fatalln("Failed to get create stable rowsAffected, ErrMessage: " + err.Error())
20. }
21. // you can check rowsAffected here
22. fmt.Println("Create stable power.meters successfully, rowsAffected:", rowsAffected)

1. let taos = TaosBuilder::from_dsn(url)?.build().await?;

3. // create database and use it
4. match taos.exec_many([
5. "CREATE DATABASE IF NOT EXISTS power",
6. ]).await {
7. Ok(afffected_rows) => println!("Create database power successfully, rowsAffected: {}", afffected_rows),
8. Err(err) => {
9. eprintln!("Failed to create database power, ErrMessage: {}", err);
10. return Err(err.into());
11. }
12. }

14. // create super table
15. match taos.exec_many([
16. "CREATE STABLE IF NOT EXISTS power.meters (`ts` TIMESTAMP, `current` FLOAT, `voltage` INT, `phase` FLOAT) \
17. TAGS (`groupid` INT, `location` BINARY(24))",
18. ]).await {
19. Ok(afffected_rows) => println!("Create stable power.meters successfully, rowsAffected: {}", afffected_rows),
20. Err(err) => {
21. eprintln!("Failed to create stable power.meters, ErrMessage: {}", err);
22. return Err(err.into());
23. }
24. }

26. Ok(())

1. async function createDbAndTable() {
2. let wsSql = null;
3. try {
4. let conf = new taos.WSConfig(dsn);
5. conf.setUser('root');
6. conf.setPwd('taosdata');
7. conf.setDb('power');
8. wsSql = await taos.sqlConnect(conf);
9. console.log("Connected to " + dsn + " successfully.");
10. // create database
11. await wsSql.exec('CREATE DATABASE IF NOT EXISTS power');
12. console.log("Create database power successfully.");
13. // create table
14. await wsSql.exec('CREATE STABLE IF NOT EXISTS power.meters ' +
15. '(ts timestamp, current float, voltage int, phase float) ' +
16. 'TAGS (location binary(64), groupId int);');

18. console.log("Create stable power.meters successfully");
19. } catch (err) {
20. console.error(`Failed to create database power or stable meters, ErrCode: ${err.code}, ErrMessage: ${err.message}`);
21. throw err;
22. } finally {
23. if (wsSql) {
24. await wsSql.close();
25. }
26. }

28. }

1. try
2. {
3. // create database
4. var affected = client.Exec("CREATE DATABASE IF NOT EXISTS power");
5. Console.WriteLine($"Create database power successfully, rowsAffected: {affected}");
6. // create table
7. affected = client.Exec(
8. "CREATE STABLE IF NOT EXISTS power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (groupId INT, location BINARY(24))");
9. Console.WriteLine($"Create stable power.meters successfully, rowsAffected: {affected}");
10. }
11. catch (TDengineError e)
12. {
13. // handle TDengine error
14. Console.WriteLine("Failed to create database power or stable meters, ErrCode: " + e.Code +
15. ", ErrMessage: " + e.Error);
16. throw;
17. }
18. catch (Exception e)
19. {
20. // handle other exceptions
21. Console.WriteLine("Failed to create database power or stable meters, ErrMessage: " + e.Message);
22. throw;
23. }

WebSocket 连接

1. int   code = 0;
2. char *dsn = "ws://localhost:6041";
3. // connect
4. WS_TAOS *taos = ws_connect(dsn);

6. if (taos == NULL) {
7. fprintf(stderr, "Failed to connect to %s, ErrCode: 0x%x, ErrMessage: %s.\n", dsn, ws_errno(NULL), ws_errstr(NULL));
8. return -1;
9. }

11. // create database
12. WS_RES *result = ws_query(taos, "CREATE DATABASE IF NOT EXISTS power");
13. code = ws_errno(result);
14. if (code != 0) {
15. fprintf(stderr, "Failed to create database power, ErrCode: 0x%x, ErrMessage: %s.\n", code, ws_errstr(result));
16. ws_close(taos);
17. return -1;
18. }
19. ws_free_result(result);
20. fprintf(stdout, "Create database power successfully.\n");

22. // create table
23. const char *sql =
24. "CREATE STABLE IF NOT EXISTS power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (groupId "
25. "INT, location BINARY(24))";
26. result = ws_query(taos, sql);
27. code = ws_errno(result);
28. if (code != 0) {
29. fprintf(stderr, "Failed to create stable power.meters, ErrCode: 0x%x, ErrMessage: %s\n.", code, ws_errstr(result));
30. ws_close(taos);
31. return -1;
32. }
33. ws_free_result(result);
34. fprintf(stdout, "Create stable power.meters successfully.\n");

36. // close & clean
37. ws_close(taos);
38. return 0;

原生连接

1. const char *host = "localhost";
2. const char *user = "root";
3. const char *password = "taosdata";
4. uint16_t    port = 6030;
5. int         code = 0;

7. // connect
8. TAOS *taos = taos_connect(host, user, password, NULL, port);
9. if (taos == NULL) {
10. fprintf(stderr, "Failed to connect to %s:%hu, ErrCode: 0x%x, ErrMessage: %s.\n", host, port, taos_errno(NULL),
11. taos_errstr(NULL));
12. taos_cleanup();
13. return -1;
14. }

16. // create database
17. TAOS_RES *result = taos_query(taos, "CREATE DATABASE IF NOT EXISTS power");
18. code = taos_errno(result);
19. if (code != 0) {
20. fprintf(stderr, "Failed to create database power, ErrCode: 0x%x, ErrMessage: %s.\n", code, taos_errstr(result));
21. taos_close(taos);
22. taos_cleanup();
23. return -1;
24. }
25. taos_free_result(result);
26. fprintf(stdout, "Create database power successfully.\n");

28. // create table
29. const char *sql =
30. "CREATE STABLE IF NOT EXISTS power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (groupId "
31. "INT, location BINARY(24))";
32. result = taos_query(taos, sql);
33. code = taos_errno(result);
34. if (code != 0) {
35. fprintf(stderr, "Failed to create stable power.meters, ErrCode: 0x%x, ErrMessage: %s\n.", code, taos_errstr(result));
36. taos_close(taos);
37. taos_cleanup();
38. return -1;
39. }
40. taos_free_result(result);
41. fprintf(stdout, "Create stable power.meters successfully.\n");

43. // close & clean
44. taos_close(taos);
45. taos_cleanup();
46. return 0;

创建数据库

1. curl --location -uroot:taosdata 'http://127.0.0.1:6041/rest/sql' \
2. --data 'CREATE DATABASE IF NOT EXISTS power'

创建表，在 url 中指定数据库为 power

1. curl --location -uroot:taosdata 'http://127.0.0.1:6041/rest/sql/power' \
2. --data 'CREATE STABLE IF NOT EXISTS meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (groupId INT, location BINARY(24))'

注意：建议采用 <dbName>.<tableName> 的格式构造SQL语句，不推荐在应用中采用 USE DBName 方式访问。

插入数据

下面以智能电表为例，展示如何使用连接器执行 SQL 来插入数据到 power 数据库的 meters 超级表。样例使用 TDengine 自动建表 SQL 语法，写入 d1001 子表中 3 条数据，写入 d1002 子表中 1 条数据，然后打印出实际插入数据条数。

Java
Python
Go
Rust
Node.js
C#
C
REST API

1. // insert data, please make sure the database and table are created before
2. String insertQuery = "INSERT INTO " +
3. "power.d1001 USING power.meters TAGS(2,'California.SanFrancisco') " +
4. "VALUES " +
5. "(NOW + 1a, 10.30000, 219, 0.31000) " +
6. "(NOW + 2a, 12.60000, 218, 0.33000) " +
7. "(NOW + 3a, 12.30000, 221, 0.31000) " +
8. "power.d1002 USING power.meters TAGS(3, 'California.SanFrancisco') " +
9. "VALUES " +
10. "(NOW + 1a, 10.30000, 218, 0.25000) ";
11. try (Connection connection = DriverManager.getConnection(jdbcUrl, properties);
12. Statement stmt = connection.createStatement()) {

14. int affectedRows = stmt.executeUpdate(insertQuery);
15. // you can check affectedRows here
16. System.out.println("Successfully inserted " + affectedRows + " rows to power.meters.");
17. } catch (Exception ex) {
18. // please refer to the JDBC specifications for detailed exceptions info
19. System.out.printf("Failed to insert data to power.meters, sql: %s, %sErrMessage: %s%n",
20. insertQuery,
21. ex instanceof SQLException ? "ErrCode: " + ((SQLException) ex).getErrorCode() + ", " : "",
22. ex.getMessage());
23. // Print stack trace for context in examples. Use logging in production.
24. ex.printStackTrace();
25. throw ex;
26. }

Note NOW 为系统内部函数，默认为客户端所在计算机当前时间。 NOW + 1s 代表客户端当前时间往后加 1 秒，数字后面代表时间单位：a（毫秒），s（秒），m（分），h（小时），d（天），w（周），n（月），y（年）。

WebSocket 连接

1. import taosws

3. conn = None
4. host="localhost"
5. port=6041
6. try:
7. conn = taosws.connect(user="root",
8. password="taosdata",
9. host=host,
10. port=port)

12. sql = """
13. INSERT INTO
14. power.d1001 USING power.meters (groupid, location) TAGS(2, 'California.SanFrancisco')
15. VALUES (NOW + 1a, 10.30000, 219, 0.31000)
16. (NOW + 2a, 12.60000, 218, 0.33000) (NOW + 3a, 12.30000, 221, 0.31000)
17. power.d1002 USING power.meters (groupid, location) TAGS(3, 'California.SanFrancisco')
18. VALUES (NOW + 1a, 10.30000, 218, 0.25000)
19. """
20. affectedRows = conn.execute(sql)
21. print(f"Successfully inserted {affectedRows} rows to power.meters.")

23. except Exception as err:
24. print(f"Failed to insert data to power.meters, sql: {sql}, ErrMessage: {err}.")
25. raise err
26. finally:
27. if conn:
28. conn.close()

原生连接

1. import taos

3. conn = None
4. host = "localhost"
5. port = 6030
6. try:
7. conn = taos.connect(host=host,
8. port=port,
9. user="root",
10. password="taosdata")

12. sql = """
13. INSERT INTO
14. power.d1001 USING power.meters (groupid, location) TAGS(2, 'California.SanFrancisco')
15. VALUES (NOW + 1a, 10.30000, 219, 0.31000)
16. (NOW + 2a, 12.60000, 218, 0.33000) (NOW + 3a, 12.30000, 221, 0.31000)
17. power.d1002 USING power.meters (groupid, location)  TAGS(3, 'California.SanFrancisco')
18. VALUES (NOW + 1a, 10.30000, 218, 0.25000)
19. """
20. affectedRows = conn.execute(sql)
21. print(f"Successfully inserted {affectedRows} rows to power.meters.")

23. except Exception as err:
24. print(f"Failed to insert data to power.meters, sql: {sql}, ErrMessage: {err}.")
25. raise err
26. finally:
27. if conn:
28. conn.close()

Rest 连接

1. import taosrest

3. conn = None
4. url="http://localhost:6041"
5. try:
6. conn = taosrest.connect(url=url,
7. user="root",
8. password="taosdata",
9. timeout=30)

11. sql = """
12. INSERT INTO
13. power.d1001 USING power.meters (groupid, location) TAGS(2, 'California.SanFrancisco')
14. VALUES (NOW + 1a, 10.30000, 219, 0.31000)
15. (NOW + 2a, 12.60000, 218, 0.33000) (NOW + 3a, 12.30000, 221, 0.31000)
16. power.d1002 USING power.meters (groupid, location) TAGS(3, 'California.SanFrancisco')
17. VALUES (NOW + 1a, 10.30000, 218, 0.25000)
18. """
19. affectedRows = conn.execute(sql)
20. print(f"Successfully inserted {affectedRows} rows to power.meters.")

22. except Exception as err:
23. print(f"Failed to insert data to power.meters, sql:{sql}, ErrMessage:{err}.")
24. raise err
25. finally:
26. if conn:
27. conn.close()

1. // insert data, please make sure the database and table are created before
2. insertQuery := "INSERT INTO " +
3. "power.d1001 USING power.meters TAGS(2,'California.SanFrancisco') " +
4. "VALUES " +
5. "(NOW + 1a, 10.30000, 219, 0.31000) " +
6. "(NOW + 2a, 12.60000, 218, 0.33000) " +
7. "(NOW + 3a, 12.30000, 221, 0.31000) " +
8. "power.d1002 USING power.meters TAGS(3, 'California.SanFrancisco') " +
9. "VALUES " +
10. "(NOW + 1a, 10.30000, 218, 0.25000) "
11. res, err = db.Exec(insertQuery)
12. if err != nil {
13. log.Fatalf("Failed to insert data to power.meters, sql: %s, ErrMessage: %s\n", insertQuery, err.Error())
14. }
15. rowsAffected, err = res.RowsAffected()
16. if err != nil {
17. log.Fatalf("Failed to get insert rowsAffected, sql: %s, ErrMessage: %s\n", insertQuery, err.Error())
18. }
19. // you can check affectedRows here
20. fmt.Printf("Successfully inserted %d rows to power.meters.\n", rowsAffected)

1. let insert_sql = r#"INSERT INTO
2. power.d1001 USING power.meters TAGS(2,'California.SanFrancisco')
3. VALUES
4. (NOW + 1a, 10.30000, 219, 0.31000)
5. (NOW + 2a, 12.60000, 218, 0.33000)
6. (NOW + 3a, 12.30000, 221, 0.31000)
7. power.d1002 USING power.meters TAGS(3, 'California.SanFrancisco')
8. VALUES
9. (NOW + 1a, 10.30000, 218, 0.25000) "#;
10. match taos.exec(insert_sql).await{
11. Ok(affected_rows) => println!("Successfully inserted {} rows to power.meters.", affected_rows),
12. Err(err) => {
13. eprintln!("Failed to insert data to power.meters, sql: {}, ErrMessage: {}", insert_sql, err);
14. return Err(err.into());
15. }
16. }

1. async function insertData() {
2. let wsSql = null
3. let insertQuery = "INSERT INTO " +
4. "power.d1001 USING power.meters (location, groupId) TAGS('California.SanFrancisco', 2) " +
5. "VALUES " +
6. "(NOW + 1a, 10.30000, 219, 0.31000) " +
7. "(NOW + 2a, 12.60000, 218, 0.33000) " +
8. "(NOW + 3a, 12.30000, 221, 0.31000) " +
9. "power.d1002 USING power.meters (location, groupId) TAGS('California.SanFrancisco', 3) " +
10. "VALUES " +
11. "(NOW + 1a, 10.30000, 218, 0.25000) ";

13. try {
14. wsSql = await createConnect();
15. taosResult = await wsSql.exec(insertQuery);
16. console.log("Successfully inserted " + taosResult.getAffectRows() + " rows to power.meters.");
17. } catch (err) {
18. console.error(`Failed to insert data to power.meters, sql: ${insertQuery}, ErrCode: ${err.code}, ErrMessage: ${err.message}`);
19. throw err;
20. } finally {
21. if (wsSql) {
22. await wsSql.close();
23. }
24. }
25. }

1. // insert data, please make sure the database and table are created before
2. var insertQuery = "INSERT INTO " +
3. "power.d1001 USING power.meters TAGS(2,'California.SanFrancisco') " +
4. "VALUES " +
5. "(NOW + 1a, 10.30000, 219, 0.31000) " +
6. "(NOW + 2a, 12.60000, 218, 0.33000) " +
7. "(NOW + 3a, 12.30000, 221, 0.31000) " +
8. "power.d1002 USING power.meters TAGS(3, 'California.SanFrancisco') " +
9. "VALUES " +
10. "(NOW + 1a, 10.30000, 218, 0.25000) ";
11. try
12. {
13. var affectedRows = client.Exec(insertQuery);
14. Console.WriteLine("Successfully inserted " + affectedRows + " rows to power.meters.");
15. }
16. catch (TDengineError e)
17. {
18. // handle TDengine error
19. Console.WriteLine("Failed to insert data to power.meters, sql: " + insertQuery + ", ErrCode: " +
20. e.Code + ", ErrMessage: " +
21. e.Error);
22. throw;
23. }
24. catch (Exception e)
25. {
26. // handle other exceptions
27. Console.WriteLine("Failed to insert data to power.meters, sql: " + insertQuery + ", ErrMessage: " +
28. e.Message);
29. throw;
30. }

WebSocket 连接

1. int   code = 0;
2. char *dsn = "ws://localhost:6041";
3. // connect
4. WS_TAOS *taos = ws_connect(dsn);
5. if (taos == NULL) {
6. fprintf(stderr, "Failed to connect to %s, ErrCode: 0x%x, ErrMessage: %s.\n", dsn, ws_errno(NULL), ws_errstr(NULL));
7. return -1;
8. }

10. // insert data, please make sure the database and table are already created
11. const char *sql =
12. "INSERT INTO "
13. "power.d1001 USING power.meters TAGS(2,'California.SanFrancisco') "
14. "VALUES "
15. "(NOW + 1a, 10.30000, 219, 0.31000) "
16. "(NOW + 2a, 12.60000, 218, 0.33000) "
17. "(NOW + 3a, 12.30000, 221, 0.31000) "
18. "power.d1002 USING power.meters TAGS(3, 'California.SanFrancisco') "
19. "VALUES "
20. "(NOW + 1a, 10.30000, 218, 0.25000) ";
21. WS_RES *result = ws_query(taos, sql);
22. code = ws_errno(result);
23. if (code != 0) {
24. fprintf(stderr, "Failed to insert data to power.meters, sql: %s, ErrCode: 0x%x, ErrMessage: %s\n.", sql, code,
25. ws_errstr(result));
26. ws_close(taos);
27. return -1;
28. }
29. ws_free_result(result);

31. // you can check affectedRows here
32. int rows = ws_affected_rows(result);
33. fprintf(stdout, "Successfully inserted %d rows into power.meters.\n", rows);

35. // close & clean
36. ws_close(taos);
37. return 0;

原生连接

1. const char *host = "localhost";
2. const char *user = "root";
3. const char *password = "taosdata";
4. uint16_t    port = 6030;
5. int         code = 0;

7. // connect
8. TAOS *taos = taos_connect(host, user, password, NULL, port);
9. if (taos == NULL) {
10. fprintf(stderr, "Failed to connect to %s:%hu, ErrCode: 0x%x, ErrMessage: %s.\n", host, port, taos_errno(NULL),
11. taos_errstr(NULL));
12. taos_cleanup();
13. return -1;
14. }

16. // insert data, please make sure the database and table are already created
17. const char *sql =
18. "INSERT INTO "
19. "power.d1001 USING power.meters TAGS(2,'California.SanFrancisco') "
20. "VALUES "
21. "(NOW + 1a, 10.30000, 219, 0.31000) "
22. "(NOW + 2a, 12.60000, 218, 0.33000) "
23. "(NOW + 3a, 12.30000, 221, 0.31000) "
24. "power.d1002 USING power.meters TAGS(3, 'California.SanFrancisco') "
25. "VALUES "
26. "(NOW + 1a, 10.30000, 218, 0.25000) ";
27. TAOS_RES *result = taos_query(taos, sql);
28. code = taos_errno(result);
29. if (code != 0) {
30. fprintf(stderr, "Failed to insert data to power.meters, sql: %s, ErrCode: 0x%x, ErrMessage: %s\n.", sql, code, taos_errstr(result));
31. taos_close(taos);
32. taos_cleanup();
33. return -1;
34. }
35. taos_free_result(result);

37. // you can check affectedRows here
38. int rows = taos_affected_rows(result);
39. fprintf(stdout, "Successfully inserted %d rows into power.meters.\n", rows);

41. // close & clean
42. taos_close(taos);
43. taos_cleanup();
44. return 0;

Note NOW 为系统内部函数，默认为客户端所在计算机当前时间。 NOW + 1s 代表客户端当前时间往后加 1 秒，数字后面代表时间单位：a（毫秒），s（秒），m（分），h（小时），d（天），w（周），n（月），y（年）。

写入数据

1. curl --location -uroot:taosdata 'http://127.0.0.1:6041/rest/sql' \
2. --data '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)'

查询数据

下面以智能电表为例，展示如何使用各语言连接器执行 SQL 来查询数据，从 power 数据库 meters 超级表中查询最多 100 行数据，并将获取到的结果按行打印出来。

Java
Python
Go
Rust
Node.js
C#
C
REST API

1. String sql = "SELECT ts, current, location FROM power.meters limit 100";
2. try (Connection connection = DriverManager.getConnection(jdbcUrl, properties);
3. Statement stmt = connection.createStatement();
4. // query data, make sure the database and table are created before
5. ResultSet resultSet = stmt.executeQuery(sql)) {

7. Timestamp ts;
8. float current;
9. String location;
10. while (resultSet.next()) {
11. ts = resultSet.getTimestamp(1);
12. current = resultSet.getFloat(2);
13. // we recommend using the column name to get the value
14. location = resultSet.getString("location");

16. // you can check data here
17. System.out.printf("ts: %s, current: %f, location: %s %n", ts, current, location);
18. }
19. } catch (Exception ex) {
20. // please refer to the JDBC specifications for detailed exceptions info
21. System.out.printf("Failed to query data from power.meters, sql: %s, %sErrMessage: %s%n",
22. sql,
23. ex instanceof SQLException ? "ErrCode: " + ((SQLException) ex).getErrorCode() + ", " : "",
24. ex.getMessage());
25. // Print stack trace for context in examples. Use logging in production.
26. ex.printStackTrace();
27. throw ex;
28. }

Note 查询和操作关系型数据库一致，使用下标获取返回字段内容时从 1 开始，建议使用字段名称获取。

WebSocket 连接

1. import taosws

3. conn = None
4. host="localhost"
5. port=6041
6. try:
7. conn = taosws.connect(user="root",
8. password="taosdata",
9. host=host,
10. port=port)
11. sql = "SELECT ts, current, location FROM power.meters limit 100"
12. result = conn.query(sql)
13. for row in result:
14. print(f"ts: {row[0]}, current: {row[1]}, location:  {row[2]}")

16. except Exception as err:
17. print(f"Failed to query data from power.meters, sql: {sql}, ErrMessage:{err}")
18. raise err
19. finally:
20. if conn:
21. conn.close()

原生连接

1. import taos
2. host="localhost"
3. port=6030
4. conn = None
5. try:
6. conn = taos.connect(host=host,
7. port=port,
8. user="root",
9. password="taosdata")
10. sql = "SELECT ts, current, location FROM power.meters limit 100"
11. result = conn.query(sql)
12. # Get data from result as list of tuple
13. data = result.fetch_all()
14. for row in data:
15. print(f"ts: {row[0]}, current: {row[1]}, location:  {row[2]}")

17. except Exception as err:
18. print(f"Failed to query data from power.meters, sql: {sql}, ErrMessage:{err}")
19. raise err
20. finally:
21. if conn:
22. conn.close()

Rest 连接

1. import taosrest

3. client = None
4. url="http://localhost:6041"
5. try:
6. client = taosrest.RestClient(url=url,
7. user="root",
8. password="taosdata",
9. timeout=30)
10. sql = f"SELECT ts, current, location FROM power.meters limit 100"
11. result = client.sql(sql)
12. if result["data"]:
13. for row in result["data"]:
14. print(f"ts: {row[0]}, current: {row[1]}, location:  {row[2]}")

16. except Exception as err:
17. print(f"Failed to query data from power.meters, sql: {sql}, ErrMessage:{err}")
18. raise err

1. // query data, make sure the database and table are created before
2. sql := "SELECT ts, current, location FROM power.meters limit 100"
3. rows, err := db.Query(sql)
4. if err != nil {
5. log.Fatalf("Failed to query data from power.meters, sql: %s, ErrMessage: %s\n", sql, err.Error())
6. }
7. for rows.Next() {
8. // Add your data processing logic here
9. var (
10. ts       time.Time
11. current  float32
12. location string
13. )
14. err = rows.Scan(&ts, &current, &location)
15. if err != nil {
16. log.Fatalf("Failed to scan data, sql: %s, ErrMessage: %s\n", sql, err)
17. }
18. fmt.Printf("ts: %s, current: %f, location: %s\n", ts, current, location)
19. }

1. // query data, make sure the database and table are created before
2. let sql = "SELECT ts, current, location FROM power.meters limit 100";
3. match taos.query(sql).await{
4. Ok(mut result) => {
5. for field in result.fields() {
6. println!("got field: {}", field.name());
7. }

9. let mut rows = result.rows();
10. let mut nrows = 0;
11. while let Some(row) = rows.try_next().await? {
12. for (col, (name, value)) in row.enumerate() {
13. println!(
14. "[{}] got value in col {} (named `{:>8}`): {}",
15. nrows, col, name, value
16. );
17. }
18. nrows += 1;
19. }
20. }
21. Err(err) => {
22. eprintln!("Failed to query data from power.meters, sql: {}, ErrMessage: {}", sql, err);
23. return Err(err.into());
24. }
25. }

rust 连接器还支持使用 serde 进行反序列化行为结构体的结果获取方式：

1. // query data, make sure the database and table are created before
2. #[derive(Debug, serde::Deserialize)]
3. #[allow(dead_code)]
4. struct Record {
5. // deserialize timestamp to chrono::DateTime<Local>
6. ts: DateTime<Local>,
7. // float to f32
8. current: Option<f32>,
9. // binary/varchar to String
10. location: String,
11. }

13. let sql = "SELECT ts, current, location FROM power.meters limit 100";
14. match taos.query("SELECT ts, current, location FROM power.meters limit 100").await {
15. Ok(mut query) => {
16. match query.deserialize::<Record>().try_collect::<Vec<_>>().await {
17. Ok(records) => {
18. dbg!(records);
19. }
20. Err(err) => {
21. eprintln!("Failed to deserialize query results; ErrMessage: {}", err);
22. return Err(err.into());
23. }
24. }
25. }
26. Err(err) => {
27. eprintln!("Failed to query data from power.meters, sql: {}, ErrMessage: {}", sql, err);
28. return Err(err.into());
29. }
30. }

1. async function queryData() {
2. let wsRows = null;
3. let wsSql = null;
4. let sql = 'SELECT ts, current, location FROM power.meters limit 100';
5. try {
6. wsSql = await createConnect();
7. wsRows = await wsSql.query(sql);
8. while (await wsRows.next()) {
9. let row = wsRows.getData();
10. console.log('ts: ' + row[0] + ', current: ' + row[1] + ', location:  ' + row[2]);
11. }
12. }
13. catch (err) {
14. console.error(`Failed to query data from power.meters, sql: ${sql}, ErrCode: ${err.code}, ErrMessage: ${err.message}`);
15. throw err;
16. }
17. finally {
18. if (wsRows) {
19. await wsRows.close();
20. }
21. if (wsSql) {
22. await wsSql.close();
23. }
24. }
25. }

1. // query data, make sure the database and table are created before
2. var query = "SELECT ts, current, location FROM power.meters limit 100";
3. try
4. {
5. using (var rows = client.Query(query))
6. {
7. while (rows.Read())
8. {
9. // Add your data processing logic here
10. var ts = (DateTime)rows.GetValue(0);
11. var current = (float)rows.GetValue(1);
12. var location = Encoding.UTF8.GetString((byte[])rows.GetValue(2));
13. Console.WriteLine(
14. $"ts: {ts:yyyy-MM-dd HH:mm:ss.fff}, current: {current}, location: {location}");
15. }
16. }
17. }
18. catch (TDengineError e)
19. {
20. // handle TDengine error
21. Console.WriteLine("Failed to query data from power.meters, sql: " + query + ", ErrCode: " + e.Code +
22. ", ErrMessage: " + e.Error);
23. throw;
24. }
25. catch (Exception e)
26. {
27. // handle other exceptions
28. Console.WriteLine(
29. "Failed to query data from power.meters, sql: " + query + ", ErrMessage: " + e.Message);
30. throw;
31. }

WebSocket 连接

1. int   code = 0;
2. char *dsn = "ws://localhost:6041";

4. // connect
5. WS_TAOS *taos = ws_connect(dsn);
6. if (taos == NULL) {
7. fprintf(stderr, "Failed to connect to %s, ErrCode: 0x%x, ErrMessage: %s.\n", dsn, ws_errno(NULL), ws_errstr(NULL));
8. return -1;
9. }

11. // query data, please make sure the database and table are already created
12. const char *sql = "SELECT ts, current, location FROM power.meters limit 100";
13. WS_RES     *result = ws_query(taos, sql);
14. code = ws_errno(result);
15. if (code != 0) {
16. fprintf(stderr, "Failed to query data from power.meters, sql: %s, ErrCode: 0x%x, ErrMessage: %s\n.", sql, code,
17. ws_errstr(result));
18. ws_close(taos);
19. return -1;
20. }

22. WS_ROW          row = NULL;
23. int             rows = 0;
24. int             num_fields = ws_field_count(result);
25. const WS_FIELD *fields = ws_fetch_fields(result);

27. fprintf(stdout, "query successfully, got %d fields, the sql is: %s.\n", num_fields, sql);

29. // fetch the records row by row
30. while ((row = ws_fetch_row(result))) {
31. // Add your data processing logic here

33. rows++;
34. }
35. fprintf(stdout, "total rows: %d\n", rows);
36. ws_free_result(result);

38. // close & clean
39. ws_close(taos);
40. return 0;

原生连接

1. const char *host = "localhost";
2. const char *user = "root";
3. const char *password = "taosdata";
4. uint16_t    port = 6030;
5. int         code = 0;

7. // connect
8. TAOS *taos = taos_connect(host, user, password, NULL, port);
9. if (taos == NULL) {
10. fprintf(stderr, "Failed to connect to %s:%hu, ErrCode: 0x%x, ErrMessage: %s.\n", host, port, taos_errno(NULL),
11. taos_errstr(NULL));
12. taos_cleanup();
13. return -1;
14. }

16. // query data, please make sure the database and table are already created
17. const char *sql = "SELECT ts, current, location FROM power.meters limit 100";
18. TAOS_RES   *result = taos_query(taos, sql);
19. code = taos_errno(result);
20. if (code != 0) {
21. fprintf(stderr, "Failed to query data from power.meters, sql: %s, ErrCode: 0x%x, ErrMessage: %s\n.", sql, code,
22. taos_errstr(result));
23. taos_close(taos);
24. taos_cleanup();
25. return -1;
26. }

28. TAOS_ROW    row = NULL;
29. int         rows = 0;
30. int         num_fields = taos_field_count(result);
31. TAOS_FIELD *fields = taos_fetch_fields(result);

33. fprintf(stdout, "query successfully, got %d fields, the sql is: %s.\n", num_fields, sql);

35. // fetch the records row by row
36. while ((row = taos_fetch_row(result))) {
37. // Add your data processing logic here

39. rows++;
40. }
41. fprintf(stdout, "total rows: %d\n", rows);
42. taos_free_result(result);

44. // close & clean
45. taos_close(taos);
46. taos_cleanup();
47. return 0;

查询数据

1. curl --location -uroot:taosdata 'http://127.0.0.1:6041/rest/sql' \
2. --data 'SELECT ts, current, location FROM power.meters limit 100'

执行带有 reqId 的 SQL

reqId 可用于请求链路追踪，reqId 就像分布式系统中的 traceId 作用一样。一个请求可能需要经过多个服务或者模块才能完成。reqId 用于标识和关联这个请求的所有相关操作，以便于我们可以追踪和分析请求的完整路径。

使用 reqId 有下面好处：

请求追踪：通过将同一个 reqId 关联到一个请求的所有相关操作，可以追踪请求在系统中的完整路径
性能分析：通过分析一个请求的 reqId，可以了解请求在各个服务和模块中的处理时间，从而找出性能瓶颈
故障诊断：当一个请求失败时，可以通过查看与该请求关联的 reqId 来找出问题发生的位置

如果用户不设置 reqId，连接器会在内部随机生成一个，但建议由显式用户设置以以更好地跟用户请求关联起来。

下面是各语言连接器设置 reqId 执行 SQL 的代码样例。

Java
Python
Go
Rust
Node.js
C#
C
REST API

1. long reqId = 3L;
2. try (Connection connection = DriverManager.getConnection(jdbcUrl, properties);
3. // Create a statement that allows specifying a request ID
4. AbstractStatement aStmt = (AbstractStatement) connection.createStatement()) {

6. try (ResultSet resultSet = aStmt.executeQuery("SELECT ts, current, location FROM power.meters limit 1", reqId)) {
7. Timestamp ts;
8. float current;
9. String location;
10. while (resultSet.next()) {
11. ts = resultSet.getTimestamp(1);
12. current = resultSet.getFloat(2);
13. // we recommend using the column name to get the value
14. location = resultSet.getString("location");

16. // you can check data here
17. System.out.printf("ts: %s, current: %f, location: %s %n", ts, current, location);

19. }
20. }
21. } catch (Exception ex) {
22. // please refer to the JDBC specifications for detailed exceptions info
23. System.out.printf("Failed to execute sql with reqId: %s, %sErrMessage: %s%n", reqId,
24. ex instanceof SQLException ? "ErrCode: " + ((SQLException) ex).getErrorCode() + ", " : "",
25. ex.getMessage());
26. // Print stack trace for context in examples. Use logging in production.
27. ex.printStackTrace();
28. throw ex;
29. }

WebSocket 连接

1. import taosws

3. conn = None
4. reqId = 3
5. host="localhost"
6. port=6041
7. try:
8. conn = taosws.connect(
9. user="root",
10. password="taosdata",
11. host=host,
12. port=port,
13. )

15. result = conn.query_with_req_id("SELECT ts, current, location FROM power.meters limit 100", req_id=3)
16. # Get data from result as list of tuple
17. for row in result:
18. print(f"ts: {row[0]}, current: {row[1]}, location:  {row[2]}")

20. except Exception as err:
21. print(f"Failed to execute sql with reqId:{reqId}, ErrMessage:{err}")
22. raise err
23. finally:
24. if conn:
25. conn.close()

原生连接

1. import taos

3. conn = None
4. reqId = 3
5. host="localhost"
6. port=6030
7. try:
8. conn = taos.connect(host=host,
9. port=port,
10. user="root",
11. password="taosdata")

13. result = conn.query("SELECT ts, current, location FROM power.meters limit 100", reqId)
14. # Get data from result as list of tuple
15. data = result.fetch_all()
16. for row in data:
17. print(f"ts: {row[0]}, current: {row[1]}, location:  {row[2]}")

19. except Exception as err:
20. print(f"Failed to execute sql with reqId:{reqId}, ErrMessage:{err}")
21. raise err
22. finally:
23. if conn:
24. conn.close()

Rest 连接

1. import taosrest

3. client = None
4. url="http://localhost:6041"
5. reqId = 3
6. try:
7. client = taosrest.RestClient(url=url,
8. user="root",
9. password="taosdata",
10. timeout=30)

12. result = client.sql(f"SELECT ts, current, location FROM power.meters limit 100", reqId)
13. if result["data"]:
14. for row in result["data"]:
15. print(f"ts: {row[0]}, current: {row[1]}, location:  {row[2]}")

17. except Exception as err:
18. print(f"Failed to execute sql with reqId:{reqId}, ErrMessage:{err}")
19. raise err

1. // use context to set request id
2. reqId := int64(3)
3. ctx := context.WithValue(context.Background(), "taos_req_id", reqId)
4. // execute query with context
5. querySql := "SELECT ts, current, location FROM power.meters limit 1"
6. rows, err := db.QueryContext(ctx, querySql)
7. if err != nil {
8. log.Fatalf("Failed to execute sql with reqId: %d, url: %s, sql: %s, ErrMessage: %s\n", reqId, taosDSN, querySql, err.Error())
9. }
10. for rows.Next() {
11. // Add your data processing logic here
12. var (
13. ts       time.Time
14. current  float32
15. location string
16. )
17. err = rows.Scan(&ts, &current, &location)
18. if err != nil {
19. log.Fatalf("Failed to scan data, reqId: %d, url:%s, sql: %s, ErrMessage: %s\n", reqId, taosDSN, querySql, err)
20. }
21. fmt.Printf("ts: %s, current: %f, location: %s\n", ts, current, location)
22. }

2. let req_id :u64  = 3;
3. match taos.query_with_req_id("SELECT ts, current, location FROM power.meters limit 1", req_id).await{
4. Ok(mut result) => {
5. for field in result.fields() {
6. println!("got field: {}", field.name());
7. }

9. let mut rows = result.rows();
10. let mut nrows = 0;
11. while let Some(row) = rows.try_next().await? {
12. for (col, (name, value)) in row.enumerate() {
13. println!(
14. "[{}] got value in col {} (named `{:>8}`): {}",
15. nrows, col, name, value
16. );
17. }
18. nrows += 1;
19. }
20. }
21. Err(err) => {
22. eprintln!("Failed to execute sql with reqId: {}, ErrMessage: {}", req_id, err);
23. return Err(err.into());
24. }
25. }

1. async function sqlWithReqid() {
2. let wsRows = null;
3. let wsSql = null;
4. let reqId = 1;
5. try {
6. wsSql = await createConnect();
7. wsRows = await wsSql.query('SELECT ts, current, location FROM power.meters limit 100', reqId);
8. while (await wsRows.next()) {
9. let row = wsRows.getData();
10. console.log('ts: ' + row[0] + ', current: ' + row[1] + ', location:  ' + row[2]);
11. }
12. }
13. catch (err) {
14. console.error(`Failed to query data from power.meters, reqId: ${reqId}, ErrCode: ${err.code}, ErrMessage: ${err.message}`);
15. throw err;
16. }
17. finally {
18. if (wsRows) {
19. await wsRows.close();
20. }
21. if (wsSql) {
22. await wsSql.close();
23. }
24. }
25. }

1. var reqId = (long)3;
2. // query data
3. var query = "SELECT ts, current, location FROM power.meters limit 1";
4. try
5. {
6. // query with request id 3
7. using (var rows = client.Query(query, reqId))
8. {
9. while (rows.Read())
10. {
11. var ts = (DateTime)rows.GetValue(0);
12. var current = (float)rows.GetValue(1);
13. var location = Encoding.UTF8.GetString((byte[])rows.GetValue(2));
14. Console.WriteLine(
15. $"ts: {ts:yyyy-MM-dd HH:mm:ss.fff}, current: {current}, location: {location}");
16. }
17. }
18. }
19. catch (TDengineError e)
20. {
21. // handle TDengine error
22. Console.WriteLine("Failed to execute sql with reqId: " + reqId + ", sql: " + query + ", ErrCode: " +
23. e.Code + ", ErrMessage: " + e.Error);
24. throw;
25. }
26. catch (Exception e)
27. {
28. // handle other exceptions
29. Console.WriteLine("Failed to execute sql with reqId: " + reqId + ", sql: " + query + ", ErrMessage: " +
30. e.Message);
31. throw;
32. }

1. int   code = 0;
2. char *dsn = "ws://localhost:6041";

4. // connect
5. WS_TAOS *taos = ws_connect(dsn);
6. if (taos == NULL) {
7. fprintf(stderr, "Failed to connect to %s, ErrCode: 0x%x, ErrMessage: %s.\n", dsn, ws_errno(NULL), ws_errstr(NULL));
8. return -1;
9. }

11. const char *sql = "SELECT ts, current, location FROM power.meters limit 1";
12. // query data with reqid
13. long    reqid = 3L;
14. WS_RES *result = ws_query_with_reqid(taos, sql, reqid);
15. code = ws_errno(result);
16. if (code != 0) {
17. fprintf(stderr, "Failed to execute sql withQID: %ld, ErrCode: 0x%x, ErrMessage: %s\n.", reqid, code,
18. ws_errstr(result));
19. ws_close(taos);
20. return -1;
21. }

23. WS_ROW          row = NULL;
24. int             rows = 0;
25. int             num_fields = ws_field_count(result);
26. const WS_FIELD *fields = ws_fetch_fields(result);

28. fprintf(stdout, "query successfully, got %d fields, the sql is: %s.\n", num_fields, sql);

30. // fetch the records row by row
31. while ((row = ws_fetch_row(result))) {
32. // Add your data processing logic here

34. rows++;
35. }
36. fprintf(stdout, "total rows: %d\n", rows);
37. ws_free_result(result);

39. // close & clean
40. ws_close(taos);
41. return 0;

``` 1. const char host = "localhost"; 2. const char user = "root"; 3. const char *password = "taosdata"; 4. uint16_t port = 6030; 5. int code = 0;

// connect
TAOS *taos = taos_connect(host, user, password, NULL, port);
if (taos == NULL) {
fprintf(stderr, "Failed to connect to %s:%hu, ErrCode: 0x%x, ErrMessage: %s.\n", host, port, taos_errno(NULL),
taos_errstr(NULL));
taos_cleanup();
return -1;
}
const char *sql = "SELECT ts, current, location FROM power.meters limit 1";
// query data with reqid
long

（本文超出站点单文档体积上限，已截断）

本文档使用 WanXiangYunDang 构建