跳转至

11-TDengine 时序库

📄 创建: ZCode AI 2026-08-14 · 修改: JimWb 2026-08-14

https://doc.xpku.com/raw/tech/backend/bams-sdk/11-tdengine.md

tdengine（10 个类）封装 TDengine（涛思数据时序数据库）的 JDBC/REST 双模式访问，提供超级表/子表的 DDL、批量写入、查询执行能力。包路径：cn.cnbm.energy.db.tdengine。

⚠️ 注意：本模块的类不是 Spring Bean，需手动创建实例管理生命周期。

一、DbManager（连接池版，主类）

cn.cnbm.energy.db.tdengine.DbManager

连接初始化（两种模式）

方法 模式 说明
initDbJni(String url) JNI（连接池） HikariCP（minIdle=3, maxPoolSize=10, validationQuery=show databases）
initDbRest(String url) REST 解析 url 提取 user/passwd/db/host，生成 Basic Auth，用 HttpClient

URL 示例：

# JNI
jdbc:TAOS://192.168.1.115:6030/db2?user=root&password=taosdata

# REST（自动用 :6041 端口）
jdbc:TAOS://192.168.1.115:6041/db2?user=root&password=taosdata

内部枚举 CON_TYPE { RESTFUL, JNI }，静态变量 type 控制模式（默认 JNI）。

DDL 操作

方法签名 功能
createEntityTable(String tableName, List<Column> cols) 建普通表
createStable(Stable stable) 建超级表（委托 Stable.createTable() 生成 SQL）
createTableFromSt(String stableName, String tableName, List<Column> tagList, boolean deleteOld) 通过超级表建子表：create table X using Y tags(...)
deleteTable(String name) drop table if exists
checkStableColumns(String tableName, List<Column> cols) 检查超级表列，缺失则 alter table add column
deleteColumn(String tableName, List<String> fields) alter table drop column

数据写入

方法签名 功能
insertBatch(List<InsertObj> objs) 按 maxSqlLength(65480) 分批拼接 insert into，超长先执行再续拼
insertBatchEx(List<InsertObj> objs) 同上，但异常抛 IOException
importBatch(List<InsertObj> objs) 用 import into（TDengine 快速导入语法）

查询

方法签名 功能
executeQuery(String sql) 按 type 分发 REST 或 JNI
executeQuery(List<String> sqls) 批量查询（每条间 sleep 10ms）
getTableInfos(String tableName) describe 表，返回 Map<超级表名, List>
getAllTables() show tables，返回 Map
tableExist(String tableName) 通过 describe 是否报错判断

查询结果处理： - 时间戳格式化为 yyyy-MM-dd HH:mm:ss - DOUBLE/DECIMAL/FLOAT 用 NumberFormat 按 digits（默认 2 位）+ roundingMode（默认 UP）格式化 - 遇 invalid resultset pointer 自动重连 - 兼容 TDengine 2.x（head 字段）和 3.x（column_meta 字段）

配置

DbManager manager = new DbManager();
manager.setDigits(3);                    // 查询数值精度（默认 2）
manager.setRoundingMode(RoundingMode.HALF_UP);  // 舍入模式

二、DbManagerSingle（单连接版）

cn.cnbm.energy.db.tdengine.DbManagerSingle

API 与 DbManager 几乎一致，区别： - JNI 模式用单个 Connection（DriverManager.getConnection）而非连接池 - getTableInfos 未做 3.0 byte[] 兼容 - executeQueryRest 只兼容 2.x

三、数据对象（objs 包）

Column

cn.cnbm.energy.db.tdengine.objs.Column

字段 类型 说明
columnName String 列名
columnType ColumnType 列类型
size int 长度

getRealSize()：对 BINARY/NCHAR 返回 (bytes)。

ColumnType（枚举）

枚举值 类型名 说明
TIMESTAMP timestamp 时间戳
INT int 整型
BIGINT bigint 长整型
TM bigint 等同 bigint
FLOAT float 单精度
DOUBLE double 双精度
BINARY binary 二进制字符串
SMALLINT smallint 短整型
TINYINT tinyint 微整型
BOOL bool 布尔
NCHAR nchar 定长字符串

ColumnType.parseType(String type) 静态方法反查枚举。

InsertObj

字段 类型 说明
tableName String 表名
values List 值列表

getSql()：懒加载生成 tableName (col1,col2) values (v1,v2) SQL。

InsertValue

字段 类型 说明
value Object 值
type String 类型
colName String 列名

getValSql()：TIMESTAMP/BINARY/BOOL/NCHAR 加单引号；数值类型用 DecimalFormat("#.####") 格式化。

Stable（超级表模型）

字段 说明
name 超级表名
cols List 列
tags List 标签
tableInfos 表信息

createTable() 生成建表 SQL：create table name (col1 type1(size),...) tags(tag1 type1,...)

四、完整使用示例

// 1. 初始化（JNI 连接池）
DbManager manager = new DbManager();
manager.initDbJni("jdbc:TAOS://192.168.1.115:6030/energy?user=root&password=taosdata");

// 2. 建超级表
Stable stable = new Stable();
stable.setName("device_data");
stable.setCols(Arrays.asList(
    new Column("ts", ColumnType.TIMESTAMP),
    new Column("value", ColumnType.DOUBLE)
));
stable.setTags(Arrays.asList(
    new Column("device_id", ColumnType.BINARY)
));
manager.createStable(stable);

// 3. 建子表
manager.createTableFromSt("device_data", "dev_001",
    Arrays.asList(new Column("dev_001", ColumnType.BINARY)), true);

// 4. 写入数据
List<InsertObj> batch = new ArrayList<>();
InsertObj obj = new InsertObj();
obj.setTableName("dev_001");
obj.setValues(Arrays.asList(
    new InsertValue(System.currentTimeMillis(), "TIMESTAMP", "ts"),
    new InsertValue(42.5, "DOUBLE", "value")
));
batch.add(obj);
manager.insertBatch(batch);

// 5. 查询
List<Map<String, Object>> result = manager.executeQuery(
    "SELECT * FROM dev_001 WHERE ts > NOW - 1h");
// 时间已格式化，数值已按精度截断

// 6. 检查列（缺失自动加列）
manager.checkStableColumns("device_data", Arrays.asList(
    new Column("quality", ColumnType.INT)
));

五、注意事项

⚠️ 以下几点在使用时务必注意，详见 12-FAQ与注意事项。

  1. 不是 Spring Bean：需手动 new DbManager() 创建实例并管理生命周期
  2. type 是静态变量：全局影响所有实例，多数据源场景需注意
  3. 版本兼容：REST 模式需注意 TDengine 2.x 和 3.x 的字段差异（head vs column_meta）
  4. 数值精度：查询结果默认 2 位小数四舍五入，可通过 setDigits() 调整

相关文档