마트 생성
데이터 마트를 생성하려면 Trino SQL 쿼리를 작성하고 마트의 이름, 대상 카탈로그/스키마/테이블, 새로고침 전략을 설정합니다.
생성 절차
- 데이터 마트 메뉴에서 마트 생성 버튼을 클릭합니다
- 마트 이름을 입력합니다
- 대상 카탈로그·스키마·테이블을 드롭다운에서 선택합니다 (아래 §대상 위치 선택 참조)
- 마트 유형(materialized / view)과 새로고침 전략(full / incremental / append)을 선택합니다
- (선택) 템플릿 적용… 드롭다운에서 SQL 스니펫을 선택해 소스 SQL textarea를 자동 채울 수 있습니다 (아래 §SQL 스니펫 템플릿 참조)
- SQL 에디터에서 마트를 정의하는 SELECT 쿼리를 작성하거나 편집합니다
- SQL 검증 버튼으로 쿼리 유효성을 확인합니다
- 생성 버튼을 클릭하여 마트를 생성합니다
대상 위치 선택 — 캐스케이딩 드롭다운
target_catalog → target_schema → target_table 은 자유 입력이 아닌 드롭다운으로 선택합니다. 카탈로그를 선택하면 그 카탈로그의 스키마가, 스키마를 선택하면 그 스키마의 테이블이 차례로 자동 로드됩니다 (/api/v1/catalog/* 호출).
각 단계 마지막에는 직접 입력…(또는 테이블 단계의 새로 생성…) 옵션이 있습니다. 아직 Trino에 존재하지 않는 새 식별자를 만들 때 선택하면 해당 단계와 그 하위 단계가 자유 입력 <Input> 으로 전환됩니다. 잘못 선택했다면 라벨 옆의 목록에서 선택… 버튼으로 드롭다운으로 되돌릴 수 있습니다.
상위 단계가 자유 입력으로 바뀌면 하위 단계도 자유 입력이 됩니다. 예: 새 스키마를 만드는 경우, 그 스키마의 테이블 목록은 아직 열거(조회)할 수 없으므로 테이블도 직접 입력해야 합니다.
⚠️ 대상 카탈로그는 allowlist 로 제한됩니다 —
target_catalog는 서버 설정GEND_DATA_MART_TARGET_CATALOGS(기본["iceberg"])에 포함된 카탈로그만 허용됩니다.sourcedb·tpch·tpcds·gendpg(읽기전용 federation 소스)나nessie(CDC Bronze 적재)로는 마트를 쓸 수 없습니다 — 소스 테이블 덮어쓰기(clobber)를 막기 위한 가드레일(#2319). "직접 입력…" 으로 임의 카탈로그명을 넣어도 allowlist 에 없으면 서버가 생성을 거부하며(HTTP 400), 드롭다운에도 허용된 카탈로그만 표시됩니다. (스키마·테이블은 허용 카탈로그 내에서 새로 만들 수 있습니다.)
SQL 스니펫 템플릿
소스 SQL 영역 옆의 템플릿 적용… 드롭다운에서 4가지 기본 패턴 중 하나를 선택하면 textarea가 즉시 채워집니다 (기존 입력은 덮어씁니다). 빈 화면에서 처음부터 작성하지 않고 표준 패턴을 시작점으로 빠르게 사용할 수 있습니다.
| 템플릿 | 용도 | placeholder |
|---|---|---|
| Full refresh — 단순 집계 | GROUP BY 기반 집계 마트 | <catalog>.<schema>.<table> |
| Incremental — 시간 기반 증분 | updated_at 같은 timestamp 컬럼 기준 증분 | $last_run_time |
| Incremental — 수치 기반 증분 | id 같은 단조 증가 정수 키 기준 증분 | $last_max_id |
| Append — 로그/이벤트 누적 | 일자/이벤트 기준 누적 적재 | CURRENT_DATE |
<catalog>.<schema>.<table> placeholder는 위에서 선택한 대상 위치와 별개로 작성자가 직접 채워야 합니다. 일반적으로는 source 위치(읽기)와 target 위치(쓰기)가 다르기 때문입니다.
$last_run_time / $last_max_id 는 향후 서버 측 substitution을 위해 예약된 placeholder 입니다. 현재는 단순 SQL 저장만 되며 자동 치환되지 않습니다 — 별도 후속 작업으로 Dagster pipeline 연동 시점에 실제 값으로 치환할 계획입니다. 그 전까지는 사용자가 직접 실제 값으로 바꿔 작성해야 마트 새로고침이 동작합니다.
SQL 유효성 검증
마트 생성 전에 SQL 구문을 사전 검증할 수 있습니다. 검증 API는 Trino에 EXPLAIN 쿼리를 전송하여 구문 오류, 존재하지 않는 테이블/컬럼 참조 등을 확인합니다.
새로고침 전략
| 전략 | 설명 | 추가 입력 |
|---|---|---|
full | 매 실행마다 마트 전체를 재계산하여 덮어씀 | 없음 |
incremental | 증분 키 기준으로 최근 구간만 재적재 (DELETE → INSERT) | Incremental Key (필수) |
append | 결과를 누적 적재 | 없음 |
Incremental 전략 — Incremental Key 필수
incremental 전략을 선택하면 Incremental Key 필드가 나타나며 반드시 입력해야 합니다. 이 키는 서버가 증분 새로고침 시 기준으로 삼는 컬럼명(예: updated_at, id)입니다. 값이 비어 있거나 공백만 입력된 경우 "생성" 버튼이 자동으로 비활성화되어 잘못된 설정이 서버로 전송되는 것을 방지합니다.
주의 — Incremental Key 컬럼은 SQL 결과에 포함되어야 합니다
서버는 증분 새로고침 시 내부적으로
SELECT MAX(incremental_key) FROM target로 기준값을 구한 뒤,DELETE FROM target WHERE incremental_key >= last_key로 최근 구간을 삭제하고INSERT INTO target <source_sql>로 재적재합니다. 따라서 Incremental Key 로 지정한 컬럼이 source SQL 의 SELECT 결과에 반드시 포함되어 있어야 합니다. 포함되지 않으면 새로고침이 실패합니다.또한
incremental은 "신규 레코드만 추가"가 아니라 증분 구간을 삭제 후 재적재하는 방식이므로, source SQL 은 증분 구간만 반환하도록 작성하거나(권장), 전체를 반환하더라도 idempotent 해야 합니다.
Incremental Key를 입력하면 "생성" 버튼이 활성화됩니다.
마트 설정 항목
| 항목 | 필수 | 설명 |
|---|---|---|
| 이름 | O | 마트 고유 식별명 |
| 대상 카탈로그 | O | 마트가 저장될 Trino 카탈로그 (allowlist 제한 — 기본 iceberg, §대상 위치 선택 참조) |
| 대상 스키마 | O | 마트가 저장될 스키마 |
| 대상 테이블 | O | 생성될 마트 테이블 이름 |
| 마트 유형 | O | materialized 또는 view |
| 새로고침 전략 | O | full, incremental, append 중 하나 |
| Incremental Key | 조건부 | incremental 전략 선택 시 필수 |
| 소스 SQL | O | 마트 데이터를 정의하는 SELECT 문 |
Medallion layer | 선택 | bronze / silver / gold (기본값 gold). 마트는 일반적으로 비즈니스 소비 단계라 Gold가 자연스럽습니다 |
Medallion 계층 (layer)
모든 데이터 마트는 layer 컬럼을 가지며, 마트 목록의 행마다 Medallion 색상 배지로 표시됩니다 (Bronze=갈색, Silver=회색, Gold=노랑). 기본값은 gold이며, 다른 값을 지정하려면 생성·수정 API의 layer 필드를 사용하세요.
POST /api/v1/data-marts
{
"name": "daily-revenue",
"mart_type": "materialized",
"target_catalog": "iceberg", "target_schema": "datax_analytics", "target_table": "daily_revenue",
"refresh_strategy": "full",
"source_sql": "SELECT date, SUM(amount) revenue FROM ...",
"layer": "gold"
}
PUT으로 layer만 변경할 때는 다른 필드를 생략해도 됩니다 (Pydantic optional). 잘못된 값(예: "platinum")은 422로 거부됩니다. 계층 의미와 페르소나별 사용 가이드는 Medallion 데이터 레이어를 참조하세요.
참고: 모든 필수 텍스트 필드는 공백(
)만 입력된 경우도 비어 있는 것으로 취급되어 "생성" 버튼이 비활성화됩니다.
API 엔드포인트
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/data-marts | 데이터 마트 생성 |
| POST | /api/v1/data-marts/validate-sql | SQL 유효성 검증 |
서버는 incremental 전략 요청에 incremental_key 가 없으면 HTTP 400 "incremental 전략에는 incremental_key가 필수입니다" 를 반환합니다. UI는 사전에 "생성" 버튼을 비활성화해 이 서버 왕복을 방지합니다.