跳到主要内容

TQL 与 JDBC 驱动

时序引擎（TSE）有 两种从外部查询 的途径 — 查询语言是 TQL， 连接方式是 JDBC 驱动。

一句话总结
드라이버   plantpulse.timeseries.tql.TQLDriver
URL       jdbc:ts://<호스트>:7800
계정      tse / (설치가 정한 비밀번호)

TQL 是四种语言之一​

数据网关（:5500）通过查询语言来选择后端。 这种结构设计使得您无需关心连接的是哪个引擎， 而 TQL 负责时序引擎。

语言后端用途
PQLPostgreSQL主数据 · 配置（mm_*）
CQLAster TSDB时序原始数据 · 聚合（tm_*）
SQLSpark湖仓 · 大规模分析
TQL时序引擎（TSE）时间窗口聚合 · 填补空缺

发送到网关时，通过请求头指定语言。

curl -sk -X POST https://<호스트>:5501/api/v1/query \
  -H 'X-Lang: TQL' \
  -H 'X-API-Key: <data.gateway.api.key>' \
  -H 'Content-Type: text/plain' \
  --data "SELECT LAST('1 DAYS', 'END') FROM CHANNEL1.PUMP1.TEMP_0001 \
          WHERE timestamp BETWEEN '2022-01-01 00:00:00.000' AND '2030-12-31 23:59:59.999'"

响应格式为 {"result":"SUCCESS","data":[...]}。

发送到 5500 会 302 到 5501

5500 是明文，5501 是 TLS。即使发送明文也会被重定向，所以 一开始就用 5501 发送可以省一次往返。

表名就是«路径»​

TQL 中的 FROM 子句不是关系型表名，而是 标签路径。

FROM <채널>.<설비>.<태그>
예:  CHANNEL1.PUMP1.TEMP_0001

时间范围通过 WHERE timestamp BETWEEN … AND … 指定，字符串字面量使用 'YYYY-MM-DD HH:mm:ss.SSS'。

通过 JDBC 连接​

BI 工具、批处理、自己写的程序使用 JDBC。

Class.forName("plantpulse.timeseries.tql.TQLDriver");

try (Connection c = DriverManager.getConnection(
        "jdbc:ts://192.168.0.41:7800", "tse", "<password>");
     Statement st = c.createStatement();
     ResultSet rs = st.executeQuery(
        "SELECT LAST('1 DAYS','END') FROM CHANNEL1.PUMP1.TEMP_0001 "
      + "WHERE timestamp BETWEEN '2026-09-01 00:00:00.000' "
      + "AND '2026-09-02 00:00:00.000'")) {
    while (rs.next()) System.out.println(rs.getString(1));
}

如果要通过配置指定，使用 plantpulse-jdbc.properties 中的 jdbc.tse.*。

键值
jdbc.tse.driverplantpulse.timeseries.tql.TQLDriver
jdbc.tse.urljdbc:ts://<호스트>:${PP_TSE_PORT}
jdbc.tse.usernametse
jdbc.tse.password安装时设定的值

可选的键有 jdbc.tse.pool.initial|min|max 和 jdbc.tse.query.timeout|fetch-size。

不要将 jdbc.tse.url 改为 tss（7801）

TQL JDBC 驱动使用 明文 TSE 监听器（7800）。TSE 客户端全局默认使用明文 ts/7800（2026-08）。

如果设置为 tss/7801，会导致 JDBC 连接失败 → 数据网关启动失败 → /api/v1/* 全部 404 → analytics 目录 404 的连锁故障。因此，通过 ts 和 PP_TSE_PORT 固定值进行了锁定 → 属性参考

TSE 客户端（Java）​

如果说 JDBC 是 只读为主，那么 TSE 客户端是 支持写入 的原生库。 平台自身在推送指标时使用的正是这个。

plantpulse-platform:plantpulse-timeseries-engine-client

有两种类型​

类功能适用场景
TSEClient对写入进行 缓冲 的 store-and-forward默认。即使引擎短暂断开也不会丢失写入
DirectTSEClient无缓冲的原始 HTTP缓冲成为阻碍时（测试、一次性工具）

TSEClient 的构造函数与 DirectTSEClient 完全相同，因此可以直接替换。 由于缓冲工作线程是在 第一次缓冲写入时才延迟启动，所以仅执行查询的客户端不会额外占用线程。

连接​

import plantpulse.timeseries.engine.client.TSEClient;

// protocol · host · port · user · password
TSEClient client = new TSEClient("https", "192.168.0.41", 7801, "tse", "<password>");

// URL 한 줄로도 됩니다
TSEClient client2 = new TSEClient("https://192.168.0.41:7801");

默认值为 https · 7801 · 超时 60초。

客户端默认 7801（TLS），JDBC 使用 7800（明文）

两者不同。TSE 客户端使用 DEFAULT_PROTOCOL=https · DEFAULT_PORT=7801， JDBC 驱动使用明文 7800（参见上述 danger 提示）。它们是同一引擎的两个监听器。

写入值​

import plantpulse.timeseries.engine.client.builder.MetricBuilder;

MetricBuilder builder = MetricBuilder.getInstance();
builder.addMetric("PLANTPULSE.LINE1.PUMP1.TEMP")
       .addDataPoint(System.currentTimeMillis(), 42.7)
       .addTag("site", "SITE_00001");

client.pushMetrics(builder);

读取值​

import plantpulse.timeseries.engine.client.builder.QueryBuilder;

QueryBuilder q = QueryBuilder.getInstance();
// 범위와 메트릭을 지정한 뒤
QueryResponse res = client.query(q);

如果已经手动构建了 JSON，可以通过 client.query(String jsonText) 直接发送。

其他可执行操作​

要执行的操作方法
指标名称列表getMetricNames()
引擎状态getStatus() · getStatusCheck()
汇总（预聚合）任务管理createRollupTask() · getRollupTasks() · deleteRollupTask()
删除指标deleteMetric(name) · delete(QueryBuilder)
元数据getMetricMetadata() · setMetricMetadata() · deleteMetricMetadata()
标签查询queryTags(QueryTagBuilder)

如何选择​

场景使用
应用中通过一个入口访问四个后端网关 POST /api/v1/query + X-Lang
Java 程序中只用 TSEJDBC（jdbc:ts://）
PlantPulse Dashboard · BI 工具JDBC → 创建仪表盘
通过客户端库便捷使用Data Gateway 客户端 中的 tql()
Java 中需要对 TSE 进行 写入TSE 客户端 — 上述章节

相关文档​