Data Gateway Client

DataGatewayClient is a Java library that attaches to the Query Gateway. Instead of connecting to PostgreSQL · Aster TSDB · Spark · time-series engine with separate drivers, it sends queries to a single gateway and receives results as JSON.

Item	Value
Coordinates	plantpulse-platform:plantpulse-data-gateway-client
Server	plantpulse-data-gateway — default port 5501 (TLS)
Requirement	Java 21 or later — the client is compiled with 21 (below that, UnsupportedClassVersionError)
Authentication	API key

Four Query Languages

The gateway selects the underlying engine based on the language. You don't need to know where it is.

Method	Language	Behind It	Where It's Used
pql()	PQL	PostgreSQL	Master data · settings (mm_* tables)
cql()	CQL	Aster TSDB	Time series raw · aggregates (tm_* tables)
sql()	SQL	Spark	Lakehouse · large-scale analytics
tql()	TQL	Time-series engine	Time-window aggregations · gap-filling
cache()	—	Valkey/Redis	Current values (PREFIX:ID form)

Getting Started

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

Parameter Types — 이름:타입

The suffix after the name determines how the gateway casts it. They are passed via the X-Params header.

Type	Java	Example
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	Timestamp (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")

Don't build queries by string concatenation

This is why suffixed parameters exist. Concatenating values into a string breaks types and exposes you to injection.

Beyond Queries

// 단일 행
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);

Handling Failures

429 · 502 · 503 · 504 are automatically retried by the client with exponential backoff. Other failures surface as exceptions.

Exception	When
HttpResponseException	HTTP error response — includes statusCode · errorCode · message
ConnectionException	Connection failure
DataGatewayClientException	General library error, e.g., response parsing failure

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

What the gateway rejects

DDL · multiple statements in one request · TQL updates are rejected by the server. Schema changes are not done through this path.

See Also

CEP Client · Data Gateway Component · Console Logins