IoTDB JDBC 完整使用教程：连接、查询、批处理与字符集配置

IoTDB JDBC 完整使用教程：连接、查询、批处理与字符集配置

大家在对接 BI 工具、做通用数据查询、或者写兼容 JDBC 标准的 Java 程序时，基本都会用到 IoTDB JDBC。这篇文章就把依赖引入、驱动连接、CRUD、批量插入、多字符集支持、版本兼容一次性讲全，直接复制就能跑。

先记住官方一句话：
JDBC 适合查询和第三方工具对接，不适合高性能写入；Java 应用优先用原生 Session 接口。

---

一、重要说明（先看这个，少踩90%坑）

• JDBC 目前主要用于和第三方工具连接
• 不推荐用 JDBC 做大量插入，性能不如原生 API
• 查询推荐用 JDBC，标准通用
• Java 项目优先用：IoTDB Java Native API（Session/SessionPool）
• 客户端版本 必须与服务端版本一致，高版本连低版本会出问题

---

二、环境依赖

• JDK ≥ 1.8
• Maven ≥ 3.6

---

三、Maven 依赖引入

直接在 pom.xml 加入即可，版本号要和你的 IoTDB 服务端一致。

<dependencies>
    <dependency>
      <groupId>org.apache.iotdb</groupId>
      <artifactId>iotdb-jdbc</artifactId>
      <version>${project.version}</version>
    </dependency>
</dependencies>

如果你是自己编译 IoTDB，在源码根目录执行：

mvn clean install -pl iotdb-client/jdbc -am -DskipTests

---

四、JDBC 连接基本格式

4.1 标准 URL

jdbc:iotdb://127.0.0.1:6667/

4.2 开启 RPC 压缩（建议加上）

jdbc:iotdb://127.0.0.1:6667?rpc_compress=true

4.3 指定 SQL 语法版本（升级兼容用）

jdbc:iotdb://127.0.0.1:6006?version=V_1_0

可选项：V_0_12 / V_0_13 / V_1_0

4.4 指定字符集（例如 GB18030）

jdbc:iotdb://127.0.0.1:6667?charset=GB18030

---

五、完整示例代码（最常用模板）

包含：获取连接 → 创建库 → 创建时间序列 → 批量插入 → 各类查询 → 删除 → 关闭。

import java.sql.*;
import org.apache.iotdb.jdbc.IoTDBSQLException;

public class IoTDBJdbcDemo {

    public static void main(String[] args) throws SQLException {
        // 1. 获取连接
        Connection conn = getConnection();
        if (conn == null) {
            System.out.println("连接失败");
            return;
        }

        Statement stmt = conn.createStatement();

        try {
            // 2. 创建数据库
            stmt.execute("CREATE DATABASE root.demo");
        } catch (IoTDBSQLException e) {
            System.out.println(e.getMessage());
        }

        // 3. 查看数据库
        stmt.execute("SHOW DATABASES");
        printResult(stmt.getResultSet());

        // 4. 创建时间序列
        try {
            stmt.execute("CREATE TIMESERIES root.demo.s0 WITH DATATYPE=INT32,ENCODING=RLE;");
        } catch (IoTDBSQLException e) {
            System.out.println(e.getMessage());
        }

        // 5. 查看时间序列
        stmt.execute("SHOW TIMESERIES root.demo");
        printResult(stmt.getResultSet());

        // 6. 批量插入（推荐方式）
        stmt.addBatch("insert into root.demo(timestamp,s0) values(1,1);");
        stmt.addBatch("insert into root.demo(timestamp,s0) values(2,15);");
        stmt.addBatch("insert into root.demo(timestamp,s0) values(3,17);");
        stmt.addBatch("insert into root.demo(timestamp,s0) values(4,12);");
        stmt.executeBatch();
        stmt.clearBatch();

        // 7. 全量查询
        String sql = "select * from root.demo";
        System.out.println("执行：" + sql);
        ResultSet rs = stmt.executeQuery(sql);
        printResult(rs);

        // 8. 精确时间查询
        sql = "select s0 from root.demo where time = 4";
        System.out.println("执行：" + sql);
        rs = stmt.executeQuery(sql);
        printResult(rs);

        // 9. 时间范围查询
        sql = "select s0 from root.demo where time >=2 and time <5";
        System.out.println("执行：" + sql);
        rs = stmt.executeQuery(sql);
        printResult(rs);

        // 10. 聚合查询
        sql = "select count(s0) from root.demo";
        System.out.println("执行：" + sql);
        rs = stmt.executeQuery(sql);
        printResult(rs);

        // 11. 删除时间序列
        stmt.execute("delete timeseries root.demo.s0");

        // 关闭
        stmt.close();
        conn.close();
    }

    // 获取连接
    public static Connection getConnection() {
        String driver = "org.apache.iotdb.jdbc.IoTDBDriver";
        String url = "jdbc:iotdb://127.0.0.1:6667/";
        String user = "root";
        String pwd = "root";

        Connection conn = null;
        try {
            Class.forName(driver);
            conn = DriverManager.getConnection(url, user, pwd);
        } catch (Exception e) {
            e.printStackTrace();
        }
        return conn;
    }

    // 通用结果打印
    public static void printResult(ResultSet rs) throws SQLException {
        if (rs == null) return;

        ResultSetMetaData meta = rs.getMetaData();
        int col = meta.getColumnCount();

        System.out.println("--------------------------");
        for (int i = 1; i <= col; i++) {
            System.out.print(meta.getColumnLabel(i) + "\t");
        }
        System.out.println();

        while (rs.next()) {
            for (int i = 1; i <= col; i++) {
                System.out.print(rs.getString(i) + "\t");
            }
            System.out.println();
        }
        System.out.println("--------------------------\n");
        rs.close();
    }
}

---

六、高级特性：多字符集支持（GB18030/UTF-8 等）

IoTDB 默认 UTF-8。

如果你需要存 中文、少数民族语言、繁体、特殊符号 等，可以指定字符集，比如 GB18030。

6.1 连接时指定 charset

String url = "jdbc:iotdb://127.0.0.1:6667?charset=GB18030";
Connection conn = DriverManager.getConnection(url, "root", "root");

6.2 执行 byte[] 编码的 SQL

适合中文/多语言：

IoTDBStatement stmt = (IoTDBStatement) conn.createStatement();
String sql = "insert into root.测试(timestamp,简体,繁体) values(1,'简体','繁體')";
byte[] bytes = sql.getBytes("GB18030");
stmt.execute(bytes);

6.3 按 charset 获取结果

resultSet.getBytes(i); // 按连接指定的 charset 返回字节数组
new String(resultSet.getBytes(i), "GB18030");

---

七、最常用 JDBC 操作总结

功能	示例 SQL
创建数据库	CREATE DATABASE root.demo
创建时序	CREATE TIMESERIES root.demo.s0 WITH DATATYPE=INT32,ENCODING=RLE
插入	insert into root.demo(timestamp,s0) values(1,10)
批量插入	addBatch + executeBatch
查询	select * from root.demo
条件查询	select s0 from root.demo where time >=1000
聚合	select count(s0) from root.demo
删除时序	delete timeseries root.demo.s0
查看时序	SHOW TIMESERIES root.demo

---

八、重要提醒（生产必看）

1. 不要用 JDBC 做高频大批量写入，性能远不如原生 Session/Tablet
2. Java 项目优先使用：IoTDB SessionPool
3. 客户端与服务端版本必须一致
4. 查询可以放心用 JDBC，兼容各类 BI、报表、ETL 工具
5. 中文/特殊字符建议使用 charset=GB18030

---

九、总结

IoTDB JDBC 就是标准、简单、通用，适合工具对接、查询、简单运维操作。

这篇文章已经把你从 0 → 能跑通代码 → 会批量插入 → 会多字符集 → 懂版本兼容 全部覆盖完了。