Data Gateway クライアント

DataGatewayClient は クエリゲートウェイ に接続する Java ライブラリです。PostgreSQL · Aster TSDB · Spark · 時系列エンジンにそれぞれドライバで接続する代わりに、ゲートウェイ一つに クエリを送信し、JSON で結果を受け取ります。

項目	値
座標	plantpulse-platform:plantpulse-data-gateway-client
サーバ	plantpulse-data-gateway — デフォルトポート 5501 (TLS)
要件	Java 21 以上 — クライアントは 21 でコンパイルされています(それ以下では UnsupportedClassVersionError)
認証	API キー

クエリ言語 4 種

ゲートウェイは言語に応じて背後にあるエンジンを選択します。どこにあるかを知る必要はありません。

メソッド	言語	背後にあるもの	使用箇所
pql()	PQL	PostgreSQL	マスタデータ · 設定 (mm_* テーブル)
cql()	CQL	Aster TSDB	時系列生データ · 集計 (tm_* テーブル)
sql()	SQL	Spark	レイクハウス · 大容量分析
tql()	TQL	時系列エンジン	時間ウィンドウ集計 · ギャップフィル
cache()	—	Valkey/Redis	現在値 (PREFIX:ID 形式)

開始方法

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

パラメータタイプ — 이름:타입

名前の後の接尾辞が、ゲートウェイでどのようにキャストされるかを決定します。X-Params ヘッダで 送信されます。

タイプ	Java	例
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	タイムスタンプ(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")

文字列連結でクエリを作成しないでください

接尾辞パラメータが存在する理由です。値を文字列として連結すると、型が失われ、インジェクションに 晒されます。

クエリ以外の操作

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

障害処理

429 · 502 · 503 · 504 は クライアントが指数バックオフで自動リトライします。 その他の障害は例外として発生します。

例外	発生時
HttpResponseException	HTTP エラーレスポンス — statusCode · errorCode · message を含みます
ConnectionException	接続失敗
DataGatewayClientException	レスポンス解析失敗などライブラリ一般エラー

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

ゲートウェイが拒否するもの

DDL · 複数文の一括実行 · TQL 更新は サーバが拒否します。 スキーマ変更はこの経路では行いません。

関連項目

CEP クライアント · Data Gateway コンポーネント · コンソールログイン