时序数据库长期有个尴尬——JDBC 支持残缺，ORM 框架接不上。Apache IoTDB 早期版本（0.1x）只提供了基础查询接口，metadata 和 PreparedStatement 一概没有，主流数据访问框架基本绕道走。IoTDB 2.0 补齐了这两块短板，BeetlSQL 3.39 紧跟着推出了对应适配，这意味着用 BeetlSQL 风格操作时序数据不再是空谈。
IoTDB 2.0 的 JDBC 补齐意味着什么
之前 IoTDB 的 JDBC 实现更像一个薄壳：能执行 SQL，但无法通过标准接口获取表结构、列类型等元信息；PreparedStatement 缺位则让参数绑定只能靠手动拼接，既不安全又低效。对 BeetlSQL 这类依赖 JDBC 元数据做代码生成、依赖 PreparedStatement 做参数绑定的框架来说，这些是硬性前置条件。
2.0 版本补上之后，BeetlSQL 的以下核心能力可以正常落地：
- SQLManager 自动映射：根据元数据推断实体字段类型，不再需要手写映射配置
- Markdown 风格 SQL 模板：参数通过
PreparedStatement绑定，防注入且复用执行计划 - 代码生成器：直接从 IoTDB 的 schema 生成 Entity 和 Mapper，和操作 MySQL 一样的流程
快速接入：从配置到查询
下面是一个最小可运行的项目结构，展示 BeetlSQL 3.39 + IoTDB 2.0 的接入方式。
1. Maven 依赖
<dependencies>
<!-- BeetlSQL 核心 -->
<dependency>
<groupId>com.ibeetl</groupId>
<artifactId>beetlsql</artifactId>
<version>3.39.0</version>
</dependency>
<!-- IoTDB JDBC 驱动 -->
<dependency>
<groupId>org.apache.iotdb</groupId>
<artifactId>iotdb-jdbc</artifactId>
<version>2.0.0</version>
</dependency>
</dependencies>
版本号请以 Maven Central 最新发布为准，上述是本次发布对应的最低版本。
2. SQLManager 初始化
import org.beetl.sql.core.SQLManager;
import org.beetl.sql.core.db.IoTDBStyle;
import org.beetl.sql.core.ConnectionSource;
import org.beetl.sql.core.ConnectionSourceHelper;
public class BeetlSQLIoTDBSetup {
public static SQLManager createSQLManager() {
// IoTDB 2.0 JDBC 连接串，默认端口 6667
String url = "jdbc:iotdb://127.0.0.1:6667/";
String user = "root";
String password = "root";
ConnectionSource cs = ConnectionSourceHelper.getSimple(url, user, password);
// 使用 IoTDBStyle，针对时序数据库的 SQL 语法做了适配
SQLManager sqlManager = new SQLManager(new IoTDBStyle(), cs);
return sqlManager;
}
}
IoTDBStyle 是 3.39 新增的数据库风格类，处理了 IoTDB 在分页、时间窗口查询等场景的语法差异。如果你之前用 BeetlSQL 操作关系库，切换成本仅在 Style 和连接串两处。
3. 定义实体与查询
IoTDB 的数据模型以"设备-测点"为核心，和关系库的"表-列"有映射差异。BeetlSQL 通过注解做适配：
import org.beetl.sql.annotation.Table;
import org.beetl.sql.annotation.Column;
// IoTDB 中 root.sg1.d1 对应的时序路径，映射为"表"
@Table(name = "root.sg1.d1")
public class DeviceData {
// 时间戳列，IoTDB 的 Time 列
@Column(name = "Time")
private Long timestamp;
// 测点：温度
@Column(name = "temperature")
private Double temperature;
// 测点：湿度
@Column(name = "humidity")
private Double humidity;
// getter/setter 略，IDE 可自动生成
public Long getTimestamp() { return timestamp; }
public void setTimestamp(Long timestamp) { this.timestamp = timestamp; }
public Double getTemperature() { return temperature; }
public void setTemperature(Double temperature) { this.temperature = temperature; }
public Double getHumidity() { return humidity; }
public void setHumidity(Double humidity) { this.humidity = humidity; }
}
查询示例——获取最近一小时某设备的温度数据：
SQLManager sqlManager = BeetlSQLIoTDBSetup.createSQLManager();
// 使用 Markdown SQL 模板，参数自动走 PreparedStatement 绑定
String sql = "SELECT Time as timestamp, temperature " +
"FROM root.sg1.d1 " +
"WHERE Time >= ?";
List<DeviceData> results = sqlManager.execute(sql, DeviceData.class)
.setParameter(1, System.currentTimeMillis() - 3600_000)
.select();
也可以用 BeetlSQL 的 Mapper 接口风格，把 SQL 模板写到 .md 文件里，和关系库用法完全一致：
// Mapper 定义
public interface DeviceDataMapper extends BaseMapper<DeviceData> {
// 对应模板文件 DeviceDataMapper_recentTemp.md
@SqlStatement("recentTemp")
List<DeviceData> queryRecentTemp(long startTime);
}
对应 Markdown 模板文件 DeviceDataMapper_recentTemp.md：
recentTemp
===
SELECT Time as timestamp, temperature, humidity
FROM root.sg1.d1
WHERE Time >= #startTime#
调用方式：
DeviceDataMapper mapper = sqlManager.getMapper(DeviceDataMapper.class);
List<DeviceData> recentData = mapper.queryRecentTemp(
System.currentTimeMillis() - 3600_000
);
时序场景的几个注意点
接入跑通只是第一步，时序数据库的使用模式和关系库有本质差异，直接照搬 CRUD 思路会踩坑：
写入策略不同。IoTDB 针对批量时序写入做了优化，逐条 INSERT 性能远不如批量对齐写入。BeetlSQL 的 insert 方法单条可用，但高频采集场景建议用 IoTDB 的批量 API 或 BeetlSQL 的批量模式。
查询以时间窗口为主。关系库习惯 WHERE id = ?，时序场景的核心过滤是时间范围。SQL 模板里优先用 Time >= ? AND Time < ?，配合 IoTDB 的时间索引才能拿到预期性能。
元数据是树形结构。IoTDB 的 root.sg.d.s 路径是层级命名，不是扁平表名。@Table 注解的 name 要写完整路径，不能只写最后一段。代码生成器会自动处理这个映射，手写实体时需要留意。
分页语法差异。IoTDB 的分页不是标准 LIMIT/OFFSET，IoTDBStyle 已经做了转换，但复杂分页（如带聚合）需要验证生成的 SQL 是否符合预期，建议开启 BeetlSQL 的 SQL 日志输出确认。
什么时候值得用这套组合
三个判断维度：
- 你的项目已经在用 BeetlSQL——接入 IoTDB 只需加依赖和换 Style，迁移成本极低，值得直接上。
- 时序数据和业务数据需要联合查询——BeetlSQL 支持多 SQLManager，一个指向 MySQL/PostgreSQL 做业务逻辑，一个指向 IoTDB 做时序分析，在同一套代码体系内协调。
- 纯时序写入、不做复杂查询——如果只是把传感器数据灌进去再用 Grafana 看板，BeetlSQL 的价值不大，直接用 IoTDB 原生 SDK 更简单。
最后给个快速验证清单，决定上手前逐条确认：
- ☐ IoTDB 版本确认是 2.0+（否则 JDBC 元数据接口不可用）
- ☐
iotdb-jdbc依赖版本与服务器版本匹配 - ☐ BeetlSQL 版本 ≥ 3.39
- ☐ 连接串端口正确（默认 6667，非 6668 的旧 RPC 端口）
- ☐ 实体
@Table.name写完整时序路径（如root.sg1.d1） - ☐ 时间列用
Long类型接收，IoTDB 内部是毫秒/纳秒时间戳 - ☐ 开启 SQL 日志，首次运行确认生成的 SQL 语法正确
BeetlSQL 从 2015 年一路迭代到现在，核心和生态全部自研，这次补上时序数据库支持，覆盖面又宽了一层。如果你手上有 IoTDB 的项目，3.39 是值得试的第一个版本。