Data Gateway Client

DataGatewayClient ist eine Java-Bibliothek für das Query-Gateway. Anstatt sich über separate Treiber mit PostgreSQL · Aster TSDB · Spark · der Zeitreihen-Engine zu verbinden, sendet sie Abfragen an ein einziges Gateway und empfängt die Ergebnisse als JSON.

Element	Wert
Koordinaten	`plantpulse-platform:plantpulse-data-gateway-client`
Server	`plantpulse-data-gateway` — Standardport 5501 (TLS)
Anforderung	Java 21 oder höher — der Client ist mit 21 kompiliert (darunter `UnsupportedClassVersionError`)
Authentifizierung	API-Key

Die vier Abfragesprachen

Das Gateway wählt die Engine basierend auf der Sprache aus. Sie müssen nicht wissen, wo sie sich befindet.

Methode	Sprache	Dahinter	Verwendungszweck
`pql()`	PQL	PostgreSQL	Masterdaten · Konfiguration (`mm_*` Tabellen)
`cql()`	CQL	Aster TSDB	Zeitreihen-Rohdaten · Aggregationen (`tm_*` Tabellen)
`sql()`	SQL	Spark	Lakehouse · Large-Scale-Analysen
`tql()`	TQL	Zeitreihen-Engine	Zeitfenster-Aggregationen · Gap-Filling
`cache()`	—	Valkey/Redis	Aktuelle Werte (`PREFIX:ID`-Format)

Erste Schritte

import plantpulse.data.gateway.client.DataGatewayClient;
import plantpulse.data.gateway.client.Protocol;
import plantpulse.json.JSONArray;
import plantpulse.json.JSONObject;

// AutoCloseable — try-with-resources 가 연결을 닫습니다.
try (DataGatewayClient client = DataGatewayClient.builder()
        .protocol(Protocol.HTTPS)
        .host("plant-server.example.com")
        .port(5501)
        .build()) {

    // 한 번 인증하면 이후 호출이 이 키를 답니다.
    client.connect(System.getenv("PP_DATA_GATEWAY_API_KEY"));

    // 언어를 고르면 자기 자신을 돌려주므로 query() 로 이어집니다.
    JSONArray databases = client.sql().query("SHOW DATABASES");

    JSONObject params = new JSONObject();
    params.put("tag_id:string", "TAG-0001");
    params.put("limit:int", 10);
    JSONArray points = client.pql().query(
            "SELECT * FROM mm_point WHERE tag_id = :tag_id LIMIT :limit", params);

    JSONObject cached = client.cache("TAG:TAG-0001");
}

Parametertypen — `이름:타입`

Das Suffix nach dem Namen bestimmt, wie das Gateway den Wert umwandelt. Es wird über den X-Params-Header übergeben.

Typ	Java	Beispiel
`int`	Integer	`params.put("count:int", 10)`
`long`	Long	`params.put("id:long", 9999999999L)`
`double` · `float`	Double · Float	`params.put("temp:float", 36.5f)`
`string`	String	`params.put("name:string", "abc")`
`epoch` · `ts-long`	Zeitstempel (ms)	`params.put("ts:epoch", 1700000000000L)`
`ts-string`	`yyyy-MM-dd HH:mm:ss`	`params.put("ts:ts-string", "2026-01-01 00:00:00")`

Erstellen Sie keine Abfragen durch String-Verkettung

Genau dafür gibt es die Suffix-Parameter. Wenn Sie Werte als Strings aneinanderhängen, geht der Typ verloren und es öffnet sich eine Angriffsfläche für Injection.

Neben Abfragen

// 단일 행
JSONObject one = client.get("SELECT * FROM mm_tag WHERE id = :id",
        new JSONObject().put("id:int", 1));

// 갱신 — {"count": N} 을 돌려줍니다
JSONObject r = client.sql().update(
        "UPDATE mm_tag SET name = :name WHERE id = :id",
        new JSONObject().put("name", "test").put("id:int", 1));

// 비동기 — 같은 패턴으로 queryAsync · cacheAsync · updateAsync
CompletableFuture<JSONArray> f = client.queryAsync(QueryLanguage.PQL,
        "SELECT * FROM mm_tag", null);
JSONArray rows = f.get(10, TimeUnit.SECONDS);

Umgang mit Fehlern

429 · 502 · 503 · 504 werden vom Client automatisch mit exponentiellem Backoff erneut versucht. Andere Fehler führen zu Ausnahmen.

Ausnahme	Wann
`HttpResponseException`	HTTP-Fehlerantwort — enthält `statusCode` · `errorCode` · `message`
`ConnectionException`	Verbindungsfehler
`DataGatewayClientException`	Allgemeiner Bibliotheksfehler, z.B. beim Parsen der Antwort

try {
    JSONArray result = client.pql().query("SELECT 1");
} catch (HttpResponseException ex) {
    System.err.println("HTTP " + ex.getStatusCode() + ": " + ex.getErrorCode());
} catch (DataGatewayClientException ex) {
    System.err.println("client error: " + ex.getMessage());
}

Was das Gateway ablehnt

DDL · mehrere Anweisungen auf einmal · TQL-Updates werden vom Server abgelehnt. Änderungen am Schema sind über diesen Pfad nicht möglich.

Siehe auch

CEP-Client · Data-Gateway-Komponente · Konsolen-Login

Die vier Abfragesprachen​

Erste Schritte​

Parametertypen — 이름:타입​

Neben Abfragen​

Umgang mit Fehlern​

Siehe auch​