본문으로 건너뛰기

CSV/Excel → Iceberg 적재 (Bronze)

CSV 또는 Excel 파일을 Iceberg 테이블에 적재하는 가이드입니다. RAG/문서 적재(데이터 인제스천)와 달리, 이 워크플로우는 구조화된 행/열 데이터를 Trino 카탈로그의 분석용 테이블로 만듭니다. 적재된 테이블은 자동으로 Medallion Bronze 레이어로 태깅되어 SQL 편집기·BI·파이프라인 어디서든 즉시 사용할 수 있습니다.

언제 이 가이드를 쓰나
  • 사내 부서가 던져준 정산/거래 CSV 를 일회성으로 분석 테이블로 올리고 싶을 때
  • Excel 보고서 한 시트를 그대로 데이터 마트 입력으로 쓰고 싶을 때
  • 5만 행 이하의 경량 데이터를 빠르게 Iceberg 로 옮기고 싶을 때
  • 5만 행을 넘는 데이터 — Phase 2-A 의 external_ctas 라우팅으로 자동 처리(아래 대용량 파일 참조)

빠른 시작​

사이드바 → 데이터 엔지니어링 → 파일·문서 수집 으로 이동한 뒤 CSV → Table 탭을 선택하세요. 3-step 마법사가 시작됩니다.

1. 업로드  →  2. 스키마 매핑  →  3. 적재
Step무엇을 하나자동 추론 항목
1. 업로드파일 드롭 + 옵션 확인인코딩, 구분자, 헤더 유무
2. 스키마 매핑컬럼 이름/타입/제외 결정컬럼명 정규화, 타입 (VARCHAR/BIGINT/DOUBLE/BOOLEAN)
3. 적재Catalog/Schema 선택 + Table 입력 + commitDataGrant 필터링 드롭다운 (#835), 호환성 미리보기 (append 모드)

Step 1 — 업로드​

CSV → Table 탭은 드롭존 한 줄로 시작합니다. 파일을 드래그하거나 영역을 클릭해 선택하세요.

업로드 단계

옵션기본값설명
구분자자동 감지, \t ; | 후보 중 가장 일관된 토큰 수를 선택
인코딩자동 감지UTF-8 / EUC-KR / CP949 — confidence < 0.7 이면 명시 선택 강제
첫 행이 헤더사용끄면 컬럼명이 col_0, col_1… 로 자동 부여

제약

  • 파일 한도: 100 MB (Phase 1 권장 ≤ 50 MB / ≤ 5 만 행)
  • 같은 파일을 두 번 올리면 staging hash 중복으로 거부됩니다 — 같은 데이터를 다시 적재하려면 staging 정리 후 재시도

Step 2 — 스키마 미리보기 & 매핑​

미리보기 를 누르면 파일 메타와 컬럼 추론 결과가 표로 나타납니다.

스키마 미리보기

표시 항목의미
원본 이름CSV 헤더 그대로
정규화 이름snake_case + 한글/특수문자 → col_{idx} 자동 변환. 직접 수정 가능
타입VARCHAR / BIGINT / DOUBLE / BOOLEAN / DATE / TIMESTAMP 자동 추론. dropdown 으로 변경 가능
NullableNULL 허용 토글
제외컬럼을 적재 대상에서 빼기
샘플 (앞 5개)첫 5 행 미리보기
컬럼명 충돌 회피

한글 헤더(상품명, 금액)는 자동으로 col_0, col_1 형태로 정규화됩니다. 가독성을 위해 product_name, amount 처럼 직접 입력해 두면 BI/모델 단계에서 훨씬 편합니다.

Step 3 — 대상 테이블 설정 & 적재​

마지막 단계에서 모드 와 대상 테이블 좌표 를 정합니다.

적재 단계 (모드 + Catalog/Schema 드롭다운)

모드​

모드동작사용 시점
새 테이블 생성CREATE TABLE … AS 실행 후 INSERT처음 올리는 데이터
기존 테이블에 추가INSERT 만 실행 (스키마 호환 검증 필수)일·주 단위 누적 적재

Catalog / Schema / Table​

Catalog/Schema 는 드롭다운 으로 표시됩니다 (#835). 백엔드의 DataGrant 필터링이 자동 적용되어 본인이 접근 권한을 가진 카탈로그·스키마만 노출됩니다. 카탈로그를 선택하면 그 하위 스키마 목록이 자동으로 채워집니다 (cascade).

Catalog 드롭다운 열린 상태

항목권장값 (예시)비고
Catalogiceberg드롭다운에서 선택. 차단 목록: information_schema, system, jmx
Schemadefault, bronze카탈로그 선택 후 활성화. 부서/도메인별 분리 권장
Table<도메인>_<엔터티>_<날짜>신규 테이블명 — 자유 입력. 예: sales_daily_2026_q1
신규 식별자 입력

드롭다운 맨 아래 "직접 입력…" 옵션을 고르면 자유 텍스트 입력 모드로 전환됩니다. 카탈로그/스키마가 아직 Trino 에 존재하지 않거나(예: 신규 도메인) 드롭다운 옵션이 비어 있을 때 사용하세요.

신규 스키마(namespace) 생성 (#836 완료): 카탈로그 페이지 사이드바 헤더의 + 액션으로 iceberg.temp_1 같은 새 namespace 를 만들 수 있습니다. 권한: admin 또는 catalog INSERT/ALL grant. 자세한 절차는 카탈로그 — 새 스키마 만들기 참조.

"목록으로" 링크로 언제든 드롭다운으로 복귀할 수 있습니다.

Catalog 변경 시 하위 값 초기화

Catalog 를 다른 값으로 바꾸면 Schema 와 Table 입력값이 자동으로 비워집니다 — 이전 테이블명을 다른 카탈로그에 잘못 커밋하는 사고를 막기 위함입니다.

테이블 생성 + 적재 를 누르면 commit 이 실행되고, 마법사가 Step 1 로 reset 됩니다 (성공 신호). SQL 편집기에서 바로 검증할 수 있습니다.

SQL 편집기에서 테이블 검증

Append 모드 — 기존 테이블에 누적​

같은 스키마의 추가 데이터를 일·주 단위로 누적할 때 사용합니다. Step 3 에서 모드를 기존 테이블에 추가 로 바꾸면 호환성 미리보기가 즉시 표시됩니다.

Append 모드 + 호환성 미리보기

기존 테이블 스키마 호환성
기존 컬럼 4개 / 매칭 4개 / 신규 0개
호환성 패턴의미결과
신규 0 / 매칭 N완전 호환INSERT 정상
신규 > 0CSV 에 기존 테이블에 없는 컬럼 존재UI 가 경고, commit 차단
매칭 < 기존CSV 에서 빠진 컬럼 존재빠진 컬럼은 NULL 채움 (기존 컬럼이 nullable 일 때만)
컬럼 타입 불일치

원본 CSV 의 price 가 BIGINT 로 추론되었는데 기존 테이블이 DOUBLE 이면 commit 이 거부됩니다. Step 2 에서 dropdown 으로 타입을 일치시키세요.

Excel(.xlsx) 시트 선택​

다중 시트 Excel 파일을 올리면 Step 2 상단에 시트 선택 dropdown 이 추가됩니다.

xlsx Sales 시트

다른 시트로 전환하면 컬럼/타입/샘플이 자동으로 재추론 됩니다. 시트마다 별도의 적재가 필요하면 시트별로 Step 3 까지 진행하세요.

xlsx Inventory 시트로 전환 — 컬럼 재추론

시트 패턴권장 적재 전략
시트 = 도메인 분리 (Sales / Inventory)시트별로 별도 테이블
시트 = 월별 분리 (2026-01 / 2026-02 …)첫 시트로 새 테이블 생성 → 나머지를 append
시트 = 메타 + 데이터 혼재데이터 시트만 선택, 메타 시트는 패스
인코딩 표시

xlsx 파일은 인코딩이 binary(100%) 로 표시됩니다 — Excel 의 ZIP 컨테이너이기 때문에 정상 표시입니다.

카탈로그에서 빠른 append 진입​

카탈로그 트리에서 기존 테이블에 데이터를 더하고 싶을 때, 트리 노드를 우클릭 하면 단축 메뉴가 열립니다.

카탈로그 우클릭 → CSV 데이터 추가

CSV 데이터 추가 를 누르면 데이터 수집 → CSV → Table 탭으로 이동합니다. Step 3 에서 카탈로그/스키마/테이블이 자동으로 채워져, 업로드 → 미리보기 → 적재만 하면 됩니다.

Lineage — 파일에서 테이블까지​

적재가 끝나면 자동으로 file → table 리니지 엣지 가 기록됩니다. 거버넌스 → 데이터 리니지 에서 적재한 테이블을 조회하면 다음과 같은 카운트를 볼 수 있습니다.

Lineage 카운트

upstream_count: 1     ← 원본 CSV 파일 노드
downstream_count: 0   ← 아직 파생 테이블 없음
total_nodes: 1
total_edges: 1

Bronze 테이블을 Silver/Gold 로 변환하면 downstream 이 자동으로 늘어납니다. 영향도 분석을 누르면 source 컬럼 → target 컬럼 매핑까지 추적 가능합니다.

대용량 파일 (5 만 행 이상)​

5 만 행 또는 50 MB 임계 초과 파일은 commit 단계에서 Phase 2-A 자동 라우팅 이 동작합니다.

commit_path트리거내부 동작
batch_insert≤ 5 만 행 / ≤ 50 MB배치 INSERT (Trino values)
external_ctas> 5 만 행 / > 50 MBobject storage 에 staging upload → CTAS → external table 생성

external_ctas 라우팅은 hive 카탈로그(staging) 가 활성화되어야 합니다. 미설정 환경에서는 다음과 같이 명확한 에러를 반환합니다.

대용량 파일 commit — hive 미설정 에러

staging 스키마 생성 실패 (hive 카탈로그 확인)
대안

대용량 파일을 정기적으로 다뤄야 한다면, 관리자에게 Trino hive 카탈로그 추가를 요청하거나 파일·문서 수집 파이프라인 (SFTP/S3 소스)으로 옮기는 것을 권장합니다.

제약 / 주의사항​

  • 파일 한도: 100 MB
  • Phase 1 임계: 5 만 행 / 50 MB — 초과 시 external_ctas 라우팅 (hive 카탈로그 필요)
  • Catalog 차단 목록: information_schema, system, jmx — 적재 대상으로 지정 불가
  • 인코딩 confidence < 0.7: 자동 감지 실패로 간주되어 명시 선택 강제
  • 한글 컬럼명: col_{idx} 로 자동 정규화. 가독성 위해 직접 입력 권장
  • staging 중복: 동일 content hash 의 파일은 staging 정리 전까지 재업로드 거부

참고​