Data Gateway 클라이언트

DataGatewayClient 는 질의 게이트웨이에 붙는 자바 라이브러리입니다. PostgreSQL · Aster TSDB · Spark · 시계열 엔진에 각각 드라이버로 붙는 대신, 게이트웨이 하나에 질의를 보내고 JSON 으로 결과를 받습니다.

항목	값
좌표	`plantpulse-platform:plantpulse-data-gateway-client`
서버	`plantpulse-data-gateway` — 기본 포트 5501 (TLS)
요구	Java 21 이상 — 클라이언트가 21 로 컴파일됩니다(그 아래에서는 `UnsupportedClassVersionError`)
인증	API 키

질의 언어 넷

게이트웨이가 언어에 따라 뒤의 엔진을 고릅니다. 어디에 있는지 몰라도 됩니다.

메서드	언어	뒤에 있는 것	쓰는 자리
`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 헤더로 전달됩니다.

타입	자바	예
`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 컴포넌트 · 콘솔 로그인

질의 언어 넷​

시작하기​

파라미터 타입 — 이름:타입​

조회 외의 것​

실패를 다루는 법​

함께 보기​