본문으로 건너뛰기

Catalog

Trino 카탈로그, 스키마, 테이블, 컬럼 메타데이터를 탐색하는 API입니다. 계층적 구조(카탈로그 > 스키마 > 테이블 > 컬럼)로 데이터 소스를 브라우징합니다.

엔드포인트​

GET /api/v1/catalog/catalogs​

설명: 등록된 모든 Trino 카탈로그 목록을 반환합니다.

응답:

{
  "catalogs": ["hive", "iceberg", "postgresql"]
}

GET /api/v1/catalog/{catalog}/schemas​

설명: 지정된 카탈로그 내 스키마 목록을 반환합니다.

POST /api/v1/catalog/{catalog}/schemas (신규 #836)​

설명: 카탈로그에 신규 스키마(namespace)를 생성합니다.

요청 본문:

{
  "schema_name": "temp_1",
  "location": "s3://bucket/path"
}
필드타입필수설명
schema_namestringY신규 스키마 이름. [A-Za-z_][A-Za-z0-9_]* 패턴만 허용 (공백/점/따옴표 불가).
locationstringNIceberg/Hive 스토리지 경로. admin 전용 — 일반 사용자가 입력 시 403.

응답 (201):

{
  "catalog": "iceberg",
  "schema_name": "temp_1",
  "already_existed": false,
  "location": null
}
필드설명
already_existedtrue 면 스키마가 이미 존재해 DDL 이 실행되지 않음 (idempotent). UI는 "이미 존재합니다" 토스트로 안내.

ABAC 권한: admin 또는 해당 catalog에 INSERT/ALL DataGrant 보유자만 허용. 스키마-레벨 grant 는 신규 스키마 생성 권한 없음 (WRITE on a.b ≠ 권한 to mint sibling of a.b).

차단 카탈로그: information_schema, system, jmx — 400.

에러:

  • 400 — 잘못된 식별자 또는 차단 카탈로그
  • 403 — ABAC 미통과 또는 비-admin이 location 사용
  • 502 — Trino DDL 실패

GET /api/v1/catalog/{catalog}/{schema}/tables​

설명: 지정된 스키마 내 테이블 목록을 반환합니다.

GET /api/v1/catalog/{catalog}/{schema}/{table}/columns​

설명: 테이블의 컬럼 메타데이터(이름, 타입, nullable, comment 등)를 반환합니다.

응답 (200) (#849 Phase 1: comment 필드 추가):

{
  "catalog": "iceberg",
  "schema_name": "default",
  "table": "customers",
  "columns": [
    {"name": "id", "type": "bigint", "nullable": false, "comment": null},
    {"name": "age", "type": "integer", "nullable": true, "comment": "사용자 나이 (만 나이)"}
  ]
}

comment 는 PG column_metadata 테이블에 등록된 컬럼 설명입니다. Trino column listing 이 connector별로 COMMENT 라운드트립을 지원하지 않으므로, PG 를 source-of-truth 로 두고 응답 시점에 join 합니다. 등록 전이면 null 입니다.

응답 (409) — 커넥터 불일치 (v1.2+):

Hive 메타스토어를 공유하기 때문에 hive 카탈로그의 테이블 목록에는 Iceberg 테이블도 함께 나타납니다. 그러나 Hive 커넥터는 그 테이블을 읽지 못합니다(반대 방향도 동일). 이 경우 409 와 함께 읽을 수 있는 카탈로그를 안내합니다.

{
  "status": 409,
  "detail": "`hive.bronze.intel_articles_raw` 은 `hive` 커넥터로 읽을 수 없는 테이블입니다 — 메타스토어를 공유해 목록에는 보이지만 형식이 다릅니다. `iceberg.bronze.intel_articles_raw` 로 조회하세요."
}

같은 테이블을 iceberg 카탈로그로 요청하면 정상적으로 200 을 반환합니다. Trino 자체의 장애는 종전대로 502 입니다 — 409 와 502 는 원인이 다릅니다.

GET /api/v1/catalog/{catalog}/{schema}/{table}/sample​

설명: 테이블에서 샘플 데이터를 조회합니다.

쿼리 파라미터:

파라미터타입필수설명
limitintN샘플 행 수 (기본값: 100)

인증​

JWT Bearer 토큰이 필요합니다.

에러 코드​

코드설명
400잘못된 카탈로그/스키마/테이블 이름
404카탈로그, 스키마 또는 테이블을 찾을 수 없음
500Trino 메타데이터 조회 실패