SQL Gateway REST 엔드포인트
SQL Gateway REST 엔드포인트
SQL Gateway의 REST 엔드포인트는 클라이언트가 REST API로 SQL Gateway에 연결할 수 있게 해줘요. 세션을 열고, SQL을 제출하고, 결과를 가져오는 일련의 흐름과 엔드포인트·REST API 옵션을 설명해요.
출처: REST Endpoint
본문
Overview of SQL Processing
Open Session
클라이언트가 SQL Gateway에 연결하면 SQL Gateway가 클라이언트와 SQL Gateway 사이의 상호작용 동안 사용자가 지정한 정보를 저장하는 컨텍스트로 Session을 생성해요. Session 생성 후 SQL Gateway 서버는 이후 상호작용을 위해 SessionHandle이라는 식별자를 반환해요.
Submit SQL
Session이 등록된 후 클라이언트는 SQL을 SQL Gateway 서버에 제출할 수 있어요. SQL을 제출하면 SQL이 Operation으로 변환되고, 나중에 결과를 가져오기 위한 OperationHandle이라는 식별자가 반환돼요. Operation에는 수명주기가 있는데, 클라이언트는 Operation의 실행을 취소하거나 Operation을 닫아 Operation이 사용하는 리소스를 해제할 수 있어요.
Fetch Results
OperationHandle로 클라이언트는 Operation에서 결과를 가져올 수 있어요. Operation이 준비되면 SQL Gateway는 해당 스키마와 함께 데이터 배치와, 다음 데이터 배치를 가져오는 데 사용하는 URI를 반환해요. 모든 결과를 가져왔으면 SQL Gateway는 응답의 resultType을 EOS 값으로 채우고 다음 데이터 배치의 URI는 null로 설정해요.
Endpoint Options
| Key | Default | Type | Description |
|---|---|---|---|
| sql-gateway.endpoint.rest.address | (none) | String | 클라이언트가 sql gateway 서버에 연결할 때 사용해야 하는 주소. |
| sql-gateway.endpoint.rest.bind-address | (none) | String | sql gateway 서버가 자신을 바인딩하는 주소. |
| sql-gateway.endpoint.rest.bind-port | "8083" | String | sql gateway 서버가 자신을 바인딩하는 포트. 포트 목록("50100,50101"), 범위("50100-50200") 또는 둘의 조합을 받아들여요. 같은 머신에서 여러 sql gateway 서버가 실행 중일 때 충돌을 피하려면 포트 범위를 설정하는 것이 좋아요. |
| sql-gateway.endpoint.rest.port | 8083 | Integer | 클라이언트가 연결하는 포트. bind-port가 지정되지 않은 경우 sql gateway 서버는 이 포트에 바인딩해요. |
REST API
사용 가능한 OpenAPI 사양은 다음과 같아요. 기본 버전은 v3이에요.
| Version | Description |
|---|---|
| Open API v1 specification | 사용자가 게이트웨이에 구문(statement)을 제출하고 실행할 수 있게 함. |
| Open API v2 specification | SQL Client가 게이트웨이에 연결하는 것을 지원. |
| Open API v3 specification | Materialized Table refresh 작업을 지원. |
| Open API v4 specification | 애플리케이션 모드에서 스크립트를 배포하는 것을 지원. |
경고: OpenAPI 사양은 여전히 실험적이에요.
API reference
API 참조는 v4, v3, v2, v1 탭으로 제공되며, 각각 rest_v4_sql_gateway, rest_v3_sql_gateway, rest_v2_sql_gateway, rest_v1_sql_gateway의 생성된 OpenAPI 사양에 해당해요.
Data Type Mapping
현재 REST 엔드포인트는 rowFormat 쿼리 파라미터로 RowData를 직렬화하는 것을 지원해요. REST 엔드포인트는 Table Objects를 직렬화할 때 JSON 형식을 사용해요. 매핑에 대해서는 JSON format을 참고하세요.
REST 엔드포인트는 모든 컬럼을 String으로 자동 캐스팅하는 PLAIN_TEXT 형식으로 RowData를 직렬화하는 것도 지원해요.