Trino 클라이언트 REST API

Trino 클라이언트 REST API

REST API는 클라이언트가 Trino에 SQL 쿼리를 제출하고 결과를 받을 수 있게 해줘요. CLI, JDBC 드라이버, 커뮤니티 제공 클라이언트 등이 이 API를 사용해요. Trino와 상호작용하는 선호 방법은 기존 클라이언트를 사용하는 거예요. 이 문서는 참조용으로 API 상세를 제공해요. 필요하다면 자체 클라이언트를 구현하는 데도 쓸 수 있어요.

출처: 문서

본문

클라이언트 드라이버, 클라이언트 애플리케이션, 클라이언트 프로토콜 설정에 대한 더 자세한 정보는 클라이언트 문서에서 확인할 수 있어요.

HTTP 메서드 (HTTP methods)

  • /v1/statement에 POST하면 POST 본문의 쿼리 문자열을 실행하고 쿼리 결과를 담은 JSON 문서를 반환해요. 결과가 더 있으면 JSON 문서에 nextUri URL 속성이 포함돼요.
  • nextUri 속성에 GET하면 다음 배치의 쿼리 결과를 반환해요.
  • nextUri에 DELETE하면 실행 중인 쿼리를 종료해요.

쿼리 처리 개요 (Overview of query processing)

Trino 클라이언트 요청은 /v1/statement 엔드포인트에 SQL 쿼리 문자열로 구성된 POST 본문과 함께 HTTP POST를 보내면서 시작돼요. 호출자는 다양한 클라이언트 요청 헤더를 설정할 수 있어요. 헤더는 최초 POST 요청에서만 필요하며, nextUri 링크를 따라갈 때는 필요하지 않아요.

클라이언트 요청이 HTTP 502, 503, 504를 반환하면 요청 처리에 일시적인 문제가 있었다는 뜻이므로, 클라이언트는 50-100ms 후 다시 시도해야 해요. Trino는 이런 코드를 스스로 생성하지 않고, Trino 앞에 있는 로드 밸런서가 생성할 수 있어요.

또한 요청이 429 상태 코드를 반환하면 클라이언트는 제공된 Retry-After 헤더 값을 사용해 재시도해야 해요.

502, 503, 504, 200 외의 HTTP 상태는 쿼리 처리가 실패했음을 의미해요.

/v1/statement POST 요청은 QueryResults 타입의 JSON 문서와 응답 헤더 컬렉션을 반환해요. QueryResults 문서에는 쿼리가 실패한 경우 QueryError 타입의 error 필드가 있고, 그 객체가 없으면 쿼리는 성공한 거예요. QueryResults의 중요한 측면은 다음 섹션들에 문서화돼 있어요.

JSON 문서의 data 필드가 설정되면 데이터 행 목록을 담아요. columns 필드는 쿼리가 반환한 컬럼의 이름과 타입 목록으로 설정돼요. 대부분의 응답 헤더는 클라이언트가 브라우저 쿠키처럼 취급하고, 아래 문서화된 대로 이후 클라이언트 요청의 요청 헤더로 다시 에코돼요.

/v1/statement POST가 반환한 JSON 문서에 nextUri 링크가 없으면 쿼리는 성공이든 실패든 완료된 거라 추가 요청이 필요 없어요. 문서에 nextUri 링크가 있으면 더 가져올 쿼리 결과가 있는 거예요. 클라이언트는 QueryResults 응답 객체에 반환된 nextUri에 GET 요청을 실행하는 루프를 응답에 nextUri가 없을 때까지 반복해야 해요.

JSON 문서의 status 필드는 사람이 읽는 용도로만 제공되며 쿼리 상태에 대한 힌트를 줘요. 쿼리가 끝났는지 판별하는 데는 쓸 수 없어요.

중요한 QueryResults 속성 (Important QueryResults attributes)

REST API 엔드포인트가 반환하는 QueryResults JSON 문서의 가장 중요한 속성이 이 표에 나열돼요. 자세한 내용은 Trino 소스 코드 client 디렉터리의 trino-client 모듈에 있는 io.trino.client.QueryResults 클래스를 참조하세요.

속성 설명
id 쿼리의 ID.
nextUri 있으면 이후 GET 또는 DELETE 요청에 사용할 URL. 없으면 쿼리가 완료되었거나 오류로 끝났음을 의미.
columns 쿼리가 반환한 컬럼 이름과 타입 목록.
data 쿼리 요청이 반환한 행 목록. 각 행은 columns 속성이 지정한 순서대로 해당 행의 컬럼 값을 담은 목록 자체.
updateType 연산을 나타내는 사람이 읽는 문자열. CREATE TABLE 요청이면 updateType은 "CREATE TABLE", SET SESSION이면 "SET SESSION" 등.
error 쿼리가 실패하면 error 속성은 QueryError 객체를 담음. 이 객체는 message, errorCode 및 기타 오류 정보를 담음. 자세한 내용은 client 디렉터리의 trino-client 모듈에 있는 io.trino.client.QueryError 클래스 참조.

QueryResults 진단 속성 (QueryResults diagnostic attributes)

이 QueryResults 데이터 멤버는 문제를 추적하는 데 유용할 수 있어요.

속성 타입 설명
queryError QueryError 쿼리가 오류를 일으킨 경우에만 null이 아님.
failureInfo FailureInfo failureInfo는 실패 원인에 대한 상세(스택 트레이스 포함)와 실패가 감지된 쿼리 줄 번호·컬럼 번호를 제공하는 FailureInfo.errorLocation을 담음.
warnings List 보통 비어 있는 경고 목록.
statementStats StatementStats 쿼리 실행에 대한 통계를 담은 클래스. 특히 StatementStats.rootStage(StageStats 타입)가 쿼리 처리 각 단계의 실행 통계를 제공.

클라이언트 요청 헤더 (Client request headers)

이 표는 지원되는 모든 클라이언트 요청 헤더를 나열해요. 많은 헤더는 응답 헤더로 클라이언트에 업데이트되어, 브라우저 쿠키처럼 이후 요청에 제공될 수 있어요.

헤더 이름 설명
X-Trino-User 세션 사용자를 지정. 제공하지 않으면 세션 사용자는 사용자 매핑으로 자동 결정.
X-Trino-Original-User 세션의 원래 사용자를 지정.
X-Trino-Source 보고 목적으로 쿼리를 제출한 소프트웨어 이름을 제공.
X-Trino-Catalog 쿼리 처리용 카탈로그 컨텍스트. 응답 헤더 X-Trino-Set-Catalog로 설정.
X-Trino-Schema 쿼리 처리용 스키마 컨텍스트. 응답 헤더 X-Trino-Set-Schema로 설정.
X-Trino-Time-Zone 쿼리 처리용 타임존. 기본값은 클라이언트가 아닌 Trino 클러스터의 타임존.
X-Trino-Language 쿼리 처리와 결과 포맷팅에 사용할 언어. Java Locale 문자열(예: 미국 영어는 en-US)로 포맷. 세션 언어는 X-Trino-Language HTTP 헤더로 쿼리별로 설정 가능.
X-Trino-Trace-Token Trino 엔진에 이 쿼리 요청에서 시작된 로그 줄을 식별하는 데 도움이 되는 트레이스 토큰을 제공.
X-Trino-Session 세션 속성으로 name=value 쌍의 쉼표 구분 목록을 제공. Trino 클라이언트가 SET SESSION name=value 쿼리를 실행하면 name=value 쌍이 X-Set-Trino-Session 응답 헤더로 반환되어 클라이언트의 세션 속성 목록에 추가. 응답 헤더 X-Trino-Clear-Session이 반환되면 그 값은 클라이언트의 누적 목록에서 제거되는 세션 속성 이름.
X-Trino-Role 쿼리 처리용 "역할(role)"을 설정. "역할"은 권한 컬렉션을 나타냄. 응답 헤더 X-Trino-Set-Role로 설정. 역할을 이해하려면 CREATE ROLE 참조.
X-Trino-Prepared-Statement name=value 쌍의 쉼표 구분 목록. 이름은 이전에 준비된 SQL 문 이름, 값은 명명된 준비 문의 실행 가능한 형태를 식별하는 키.
X-Trino-Transaction-Id 쿼리 처리용 트랜잭션 ID. 응답 헤더 X-Trino-Started-Transaction-Id로 설정되고 X-Trino-Clear-Transaction-Id로 해제.
X-Trino-Client-Info 쿼리를 제출하는 클라이언트 프로그램에 대한 임의 정보를 담음.
X-Trino-Client-Tags Trino 리소스 그룹을 식별하는 데 사용하는 "태그" 문자열의 쉼표 구분 목록.
X-Trino-Client-Capabilities 클라이언트가 지원하는 선택적 프로토콜 기능의 쉼표 구분 목록. 지원 값은 PATH, PARAMETRIC_DATETIME, NUMBER, VARIANT, VARIANT_BINARY, SESSION_AUTHORIZATION을 포함.
X-Trino-Resource-Estimate resource=value 유형 할당의 쉼표 구분 목록. resource의 가능한 선택은 EXECUTION_TIME, CPU_TIME, PEAK_MEMORY, PEAK_TASK_MEMORY. EXECUTION_TIME과 CPU_TIME은 airlift Duration 문자열로 값이 지정되며, 이중 정밀도 숫자 뒤에 TimeUnit 문자열(예: 초는 s, 분은 m, 시간은 h)이 오는 형식. PEAK_MEMORY와 PEAK_TASK_MEMORY는 airlift DataSize 문자열로 지정되며, 정수 뒤에 바이트는 B, 킬로바이트는 kB, 메가바이트는 mB, 기가바이트는 gB 등이 오는 형식.
X-Trino-Extra-Credential 커넥터에 추가 자격 증명을 제공. 헤더는 세션 Identity 객체에 저장되는 name=value 문자열. 이름과 값은 커넥터에만 의미가 있음.

클라이언트 응답 헤더 (Client response headers)

이 표는 지원되는 클라이언트 응답 헤더를 나열해요. 응답을 받은 후 클라이언트는 받은 응답 헤더와 일치하도록 이후 요청에 사용하는 요청 헤더를 업데이트해야 해요.

헤더 이름 설명
X-Trino-Set-Catalog 클라이언트가 이후 요청의 X-Trino-Catalog 요청 헤더에 카탈로그를 설정하도록 지시.
X-Trino-Set-Schema 클라이언트가 이후 요청의 X-Trino-Schema 요청 헤더에 스키마를 설정하도록 지시.
X-Trino-Set-Authorization-User 클라이언트가 이후 요청의 X-Trino-User 요청 헤더에 세션 인가 사용자를 설정하도록 지시. X-Trino-Original-User도 설정되어야 함.
X-Trino-Reset-Authorization-User 클라이언트가 이후 요청의 X-Trino-User 요청 헤더를 원래 값으로 재설정하고 X-Trino-Original-User를 제거해 인가 사용자를 원래 사용자로 되돌리도록 지시.
X-Trino-Set-Original-Roles 클라이언트가 이후 요청의 X-Trino-Original-Roles 요청 헤더에 원래 사용자의 역할을 설정하도록 지시.
X-Trino-Set-Session 응답 헤더 값은 property = value 형태의 문자열. 클라이언트가 이후 요청의 X-Trino-Session 헤더에 세션 속성 property를 값 value로 포함하도록 지시.
X-Trino-Clear-Session 클라이언트가 이후 요청의 X-Trino-Session 헤더의 세션 속성 목록에서 해당 헤더의 값인 이름의 세션 속성을 제거하도록 지시.
X-Trino-Set-Role 클라이언트가 이후 요청의 X-Trino-Role 요청 헤더를 헤더가 제공하는 카탈로그 역할로 설정하도록 지시.
X-Trino-Added-Prepare 클라이언트가 이후 요청의 X-Trino-Prepared-Statement 요청 헤더의 준비된 문 집합에 name=value 쌍을 추가하도록 지시.
X-Trino-Deallocated-Prepare 클라이언트가 이후 요청의 X-Trino-Prepared-Statement 요청 헤더로 보내는 준비된 문 목록에서 해당 헤더의 값인 이름의 준비된 문을 제거하도록 지시.
X-Trino-Started-Transaction-Id 클라이언트가 이후 요청의 X-Trino-Transaction-Id 요청 헤더에 다시 전달해야 하는 트랜잭션 ID를 제공.
X-Trino-Clear-Transaction-Id 클라이언트가 이후 요청의 X-Trino-Transaction-Id 요청 헤더를 해제하도록 지시.

ProtocolHeaders

Trino 소스 client 디렉터리의 trino-client 모듈에 있는 io.trino.client.ProtocolHeaders 클래스는 Trino 클라이언트 REST API가 허용하는 모든 HTTP 요청·응답 헤더를 열거해요.

더 알아보기 (Learn more)

클라이언트 드라이버와 애플리케이션의 실제 사용법은 클라이언트 문서를 참고해 보세요.