执行 SQL

TDengine 对 SQL 提供全面支持，可用熟悉的 SQL 语法进行查询、插入和删除，以及对库表的创建、修改与删除。相对标准 SQL，TDengine 扩展了时序场景常用能力，如聚合、降采样、插值查询等。具体语法请参考 TDengine SQL。

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

备注

REST API：直接调用 taosAdapter 提供的 REST API 接口，进行数据写入和查询操作。代码示例使用 curl 命令来演示。

建库和表

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

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

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

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

查看源码

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

插入数据

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

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

// insert data, please make sure the database and table are created before
String insertQuery = "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) ";
try (Connection connection = DriverManager.getConnection(jdbcUrl, properties);
     Statement stmt = connection.createStatement()) {

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

查看源码

说明 NOW 为系统函数，默认为客户端当前时间。NOW + 1s 表示客户端当前时间加 1 秒；数字后的时间单位为：a（毫秒）、s（秒）、m（分）、h（小时）、d（天）、w（周）。自然月/季/年（n/q/y）不可用于 NOW 的时间加减，详见 时间单位。

查询数据

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

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

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

    Timestamp ts;
    float current;
    String location;
    while (resultSet.next()) {
        // we recommend using the column index to get the value for better performance
        ts = resultSet.getTimestamp(1);
        current = resultSet.getFloat(2);

        // you can also use the column name to get the value
        location = resultSet.getString("location");

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

查看源码

说明：与关系型数据库一致，使用下标获取返回字段时从 1 开始，建议使用字段名获取。

执行带有 reqId 的 SQL

reqId 可用于请求链路追踪，作用类似分布式系统中的 traceId：一个请求可能经过多个服务或模块，reqId 用于标识并关联相关操作，便于追踪完整路径。

使用 reqId 有下面好处：

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

如果用户不设置 reqId，连接器会在内部随机生成一个；建议由应用显式设置，以便与业务请求关联。

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

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

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

    try (ResultSet resultSet = aStmt.executeQuery("SELECT ts, current, location FROM power.meters limit 1",
            reqId)) {
        Timestamp ts;
        float current;
        String location;
        while (resultSet.next()) {
            // we recommend using the column index to get the value for better performance
            ts = resultSet.getTimestamp(1);
            current = resultSet.getFloat(2);
            // you can also use the column name to get the value
            location = resultSet.getString("location");

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

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

查看源码