TQL- und JDBC-Treiber

Zwei Wege, um von außen Abfragen an die Zeitreihen-Engine (TSE) zu stellen – die Abfragesprache ist TQL, die Zugriffsmethode ist der JDBC-Treiber.

Kurze Zusammenfassung

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

TQL ist eine von vieren

Der Data Gateway (:5500) wählt das Backend anhand der Abfragesprache aus. Die Struktur ist so ausgelegt, dass man nicht wissen muss, an welche Engine man sich anschließt, und TQL ist für die Zeitreihen-Engine zuständig.

Sprache	Backend	Wofür
PQL	PostgreSQL	Stammdaten · Konfiguration (mm_*)
CQL	Aster TSDB	Zeitreihen-Rohdaten · Aggregation (tm_*)
SQL	Spark	Lakehouse · große Analysen
TQL	Zeitreihen-Engine (TSE)	Zeitfenster-Aggregation · Gap-Filling

Beim Senden an das Gateway wird die Sprache im Header angegeben.

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'"

Die Antwort hat die Form {"result":"SUCCESS","data":[...]}.

Bei 5500 wird ein 302 zu 5501 gesendet

5500 ist Klartext, 5501 ist TLS. Auch bei Klartext wird umgeleitet, daher ist es besser, von Anfang an 5501 zu verwenden, um einen Roundtrip zu sparen.

Tabellenname ist ein »Pfad«

Die FROM-Klausel von TQL ist kein relationaler Tabellenname, sondern ein Tag-Pfad.

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

Der Zeitbereich wird über WHERE timestamp BETWEEN … AND … angegeben, String-Literale sind in 'YYYY-MM-DD HH:mm:ss.SSS'.

Verbindung über JDBC

BI-Tools, Batch-Prozesse und selbst entwickelte Programme verwenden 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));
}

Für die Konfiguration über Einstellungen werden die jdbc.tse.* aus plantpulse-jdbc.properties verwendet.

Schlüssel	Wert
jdbc.tse.driver	plantpulse.timeseries.tql.TQLDriver
jdbc.tse.url	jdbc:ts://<호스트>:${PP_TSE_PORT}
jdbc.tse.username	tse
jdbc.tse.password	Wert aus der Installation

Als optionale Schlüssel gibt es jdbc.tse.pool.initial|min|max und jdbc.tse.query.timeout|fetch-size.

jdbc.tse.url nicht auf tss (7801) ändern

Der TQL-JDBC-Treiber verwendet den Klartext-TSE-Listener (7800). Für TSE-Clients ist global Klartext ts/7800 der Standard (Stand 2026-08).

Wenn man auf tss/7801 setzt, führt das zu JDBC-Verbindungsfehler → Data-Gateway-Startfehler → alle /api/v1/* 404 → Analytics-Katalog 404. Deshalb sind sie über ts und PP_TSE_PORT fest verdrahtet → Eigenschaften-Referenz

TSE-Client (Java)

Wenn JDBC leseorientiert ist, ist der TSE-Client eine native Bibliothek, die auch Schreiben unterstützt. Es ist dieselbe, die die Plattform selbst zum Einspeisen von Metriken verwendet.

plantpulse-platform:plantpulse-timeseries-engine-client

Es gibt zwei Varianten

Klasse	Was	Wann
TSEClient	Store-and-Forward mit Pufferung von Schreibvorgängen	Standard. Verliert keine Schreibvorgänge, auch wenn die Engine kurz ausfällt
DirectTSEClient	Ungepufferter roher HTTP	Wenn der Puffer stört (Tests, einmalige Tools)

TSEClient hat einen Konstruktor, der identisch mit DirectTSEClient ist, sodass man ihn direkt austauschen kann. Der Puffer-Worker-Thread startet erst beim ersten gepufferten Schreibvorgang, daher verbrauchen reine Abfrage-Clients keinen zusätzlichen Thread.

Verbinden

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");

Standardwerte sind https · 7801 · Timeout 60초.

Client-Standard ist 7801 (TLS), JDBC ist 7800 (Klartext)

Die beiden unterscheiden sich. Der TSE-Client verwendet DEFAULT_PROTOCOL=https · DEFAULT_PORT=7801, der JDBC-Treiber verwendet Klartext 7800 (siehe Danger oben). Das sind zwei Listener derselben Engine.

Werte schreiben

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);

Werte lesen

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

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

Wenn man JSON direkt erstellt hat, kann man es über client.query(String jsonText) unverändert senden.

Weitere Möglichkeiten

Gewünschte Aktion	Methode
Liste der Metriknamen	getMetricNames()
Engine-Status	getStatus() · getStatusCheck()
Rollup-Verwaltung (Vorab-Aggregation)	createRollupTask() · getRollupTasks() · deleteRollupTask()
Metriken löschen	deleteMetric(name) · delete(QueryBuilder)
Metadaten	getMetricMetadata() · setMetricMetadata() · deleteMetricMetadata()
Tag-Abfragen	queryTags(QueryTagBuilder)

Welchen Weg wählen

Situation	Was verwenden
App mit vier Backends über eine Schnittstelle	Gateway POST /api/v1/query + X-Lang
Java-Programm, das nur TSE nutzt	JDBC (jdbc:ts://)
PlantPulse Dashboard · BI-Tools	JDBC → Dashboard erstellen
Bequem über die Client-Bibliothek	Data-Gateway-Client mit tql()
Java, das Schreiben in TSE benötigt	TSE-Client – siehe Abschnitt oben

Siehe auch

• Zeitreihen-Funktionen – Buckets · Gap-Filling · Interpolation
• Data-Gateway-Client – Java-Wrapper
• Abfragekonsole – direkt im Browser