데이터셋

데이터셋은 D.Hub에서 구조화된 테이블 데이터를 관리하는 핵심 리소스입니다. 내부적으로 Delta Lake 포맷을 사용하여 스키마 관리, 버전 추적, 트랜잭션 지원을 제공합니다.

데이터셋 개요

데이터셋은 컬렉션에 포함되는 주요 아이템 유형 중 하나로, 다음과 같은 특징을 가집니다.

• 스키마 기반 관리: 각 컬럼의 이름, 데이터 타입, 설명을 명확히 정의합니다.
• 버전 관리: 데이터가 변경될 때마다 새 버전이 자동으로 기록됩니다.
• Delta Lake 기반: ACID 트랜잭션, 타임 트래블(Time Travel), 스키마 진화(Schema Evolution)를 지원합니다.
• S3 호환 스토리지: 오브젝트 스토리지에 데이터가 저장됩니다.

데이터셋 유형 (서브타입)

D.Hub 데이터셋은 백엔드 저장 방식에 따라 다음 4개의 서브타입(type)으로 구분됩니다. 이 값은 생성 시 명시적으로 선택해야 하며, 임의 문자열을 보내면 API가 422로 거부합니다.

서브타입 (type)	설명
delta	파일 업로드 및 파이프라인 기반의 Delta Lake 테이블 (기본 사용 케이스)
kafka	실시간 메시지 스트림에서 데이터를 수집하는 스트리밍 데이터셋
rest	외부 REST 엔드포인트를 데이터 소스로 노출
object	파일/객체 스토리지 자체를 데이터 단위로 등록

이전 버전의 table 서브타입은 폐기되었으며, 매니페스트 레벨 마이그레이션 후에만 신규 생성/수정이 가능합니다.

데이터셋 상세 화면

컬렉션 트리에서 데이터셋을 선택하면 오른쪽 패널에 상세 정보가 표시됩니다.

스키마 탭 (Schema)

스키마 탭에서는 데이터셋의 구조를 확인하고 편집할 수 있습니다.

• 컬럼 목록: 각 컬럼의 이름, 데이터 타입, 설명이 테이블 형태로 표시됩니다.
• 타입 정보: Arrow 기반의 정확한 데이터 타입이 표시됩니다 (예: int64, string, timestamp).
• Nullable 여부: 각 컬럼이 NULL 값을 허용하는지 확인할 수 있습니다.
• 스키마 편집: 편집 모드에서 컬럼 이름, 타입, 설명을 수정할 수 있습니다.

정보

스키마는 CSV 업로드 시 자동으로 추론되며, 필요한 경우 수동으로 수정할 수 있습니다.

데이터 탭 (Data)

데이터 탭에서는 실제 저장된 데이터를 테이블 형태로 조회하고 분석할 수 있습니다.

• 페이지네이션: 대량의 데이터를 페이지 단위로 탐색합니다.
• SQL Scratch Pad: 접을 수 있는 SQL 편집기가 내장되어 있어, 직접 쿼리를 작성하여 데이터를 검색하고 필터링할 수 있습니다.
• Map View: 지리(위도/경도) 데이터가 포함된 경우 자동으로 지도 시각화 뷰가 활성화됩니다.
• Chart View: 시계열 데이터가 감지되면 자동으로 차트 시각화 뷰가 활성화됩니다.

버전 탭 (Versions)

데이터셋의 버전 이력을 타임라인 형태로 확인할 수 있습니다.

• 버전 목록: 각 버전의 수정 시각과 Latest 여부를 표시합니다. 작성자(author) 셀에는 소유자 호버 미리보기가 적용됩니다.
• 버전 미리보기: 특정 버전을 선택하여 해당 시점의 데이터를 조회합니다.
• 버전 복원(Restore): 이전 버전을 현재 버전으로 복원할 수 있습니다.

References 탭 (참조)

데이터셋을 backing dataset으로 사용하는 온톨로지 자원(엔티티 타입·관계 타입)을 한눈에 확인할 수 있는 탭입니다.

스크린샷 TODO

Dataset Detail의 References 탭. backing dataset으로 이 데이터셋을 사용하는 EntityType/RelationType 카드가 나열되어야 합니다.

• 표시 항목: 참조 자원의 종류(엔티티/관계), 별칭, 소속 컬렉션, 소유자, 별칭 ↔ 시스템 이름.
• 카드 클릭 시 해당 온톨로지 모델·자원 편집 화면으로 이동합니다.
• 참조가 없으면 빈 상태 안내가 나타납니다.

References 탭은 온톨로지 정의가 변경될 때 영향 범위를 빠르게 파악하는 용도입니다.

메타데이터

상세 화면 상단에서 데이터셋의 메타데이터를 확인하고 편집할 수 있습니다.

필드	설명
Name	데이터셋의 고유 식별자 (영문 소문자, 숫자, 언더스코어)
Alias	사용자에게 표시될 별칭
Category	리소스 분류 (dataset 고정)
Type	서브타입: delta / kafka / rest / object 중 하나
Tags	검색 및 분류를 위한 태그 목록
Description	데이터셋에 대한 설명

CSV / JSON 업로드 — 미리보기 + AI 컬럼 명명

D.Hub은 CSV/JSON 파일을 통한 간편한 데이터 업로드를 지원합니다. 업로드 흐름은 미리보기 → 검토 → 적용의 3단계입니다.

업로드 절차

1. 파일 선택: 데이터셋 상세 화면에서 Upload 버튼을 클릭하거나, 컬렉션 트리/폴더 위에 파일을 드래그 앤 드롭합니다.
2. 헤더 편집 가능한 미리보기: 시스템이 헤더와 데이터를 분석하여 컬럼 타입을 추론하고, 첫 N행 프리뷰를 보여줍니다. 컬럼명/타입은 즉시 수정 가능합니다.
3. AI 컬럼 명명: 헤더가 모호하거나 비어 있을 때 AI로 컬럼명 생성 버튼을 누르면 LLM이 데이터를 분석해 컬럼명을 제안합니다.
4. append 검토 단계: 기존 데이터셋에 추가(append)하는 경우, 기존 스키마와 새 파일의 컬럼/타입 차이가 별도 단계에서 표시됩니다. 충돌 컬럼은 빨간색으로, 새 컬럼은 파란색으로 강조됩니다.
5. 업로드 실행: 확인 후 업로드 버튼을 누르면 데이터가 Delta Lake 테이블로 변환되어 저장됩니다.

팁

CSV 파일의 첫 번째 행은 반드시 컬럼 헤더여야 합니다. 헤더가 없는 파일은 업로드 시 자동으로 column_0, column_1과 같은 기본 이름이 부여되며, 미리보기 단계에서 AI 명명으로 의미 있는 이름을 받을 수 있습니다.

컬럼명 규칙

컬럼명은 다음 규칙을 통과해야 합니다(통과하지 않으면 빨간 인라인 에러로 표시됨).

• 빈 이름 금지
• 영문/숫자/언더스코어/한글 허용. /, \ 등 경로 문자와 제어 문자는 거부
• SQL 예약어와 충돌하지 않음 (예약어를 사용하려면 별칭으로만 사용 권장)
• 같은 스키마 안에서 컬럼명 중복 금지

플레이스홀더 헤더(예: Column 1, Untitled)는 그대로 두면 안내 가이드 메시지가 유지되어 사용자가 잊지 않도록 합니다.

업로드 시 주의사항

• 파일 인코딩: UTF-8 인코딩을 권장합니다.
• 구분자: 쉼표(,)가 기본 구분자이며, 파일 내용에 따라 자동 감지됩니다.
• 데이터 크기: 대용량 파일의 경우 업로드 시간이 길어질 수 있습니다.

경고

업로드 중 브라우저를 닫거나 페이지를 이동하면 업로드가 중단될 수 있습니다. 업로드 완료 메시지를 확인한 후 다른 작업을 수행하세요.

지원 데이터 타입

D.Hub 데이터셋은 Apache Arrow 기반의 다양한 데이터 타입을 지원합니다.

기본 타입

타입	설명	예시
string	문자열 (UTF-8)	"Hello", "서울"
large_string	대용량 문자열	긴 텍스트 데이터
boolean	참/거짓	true, false

정수 타입

타입	범위	설명
int8	-128 ~ 127	8비트 정수
int16	-32,768 ~ 32,767	16비트 정수
int32	-2^31 ~ 2^31-1	32비트 정수
int64	-2^63 ~ 2^63-1	64비트 정수
uint8	0 ~ 255	부호 없는 8비트 정수
uint16	0 ~ 65,535	부호 없는 16비트 정수
uint32	0 ~ 2^32-1	부호 없는 32비트 정수
uint64	0 ~ 2^64-1	부호 없는 64비트 정수

실수 타입

타입	정밀도	설명
float16	반정밀도	16비트 부동소수점
float32	단정밀도	32비트 부동소수점
float64	배정밀도	64비트 부동소수점

날짜/시간 타입

타입	설명	예시
date32	날짜 (일 단위)	2025-01-15
date64	날짜 (밀리초 단위)	2025-01-15
time32	시간 (초/밀리초)	14:30:00
time64	시간 (마이크로/나노초)	14:30:00.123456
timestamp	타임스탬프 (타임존 지원)	2025-01-15T14:30:00+09:00
duration	시간 간격	경과 시간

복합 타입

타입	설명
list	동일 타입 요소의 배열
struct	여러 필드를 가진 구조체
binary	바이너리 데이터
large_binary	대용량 바이너리 데이터

다음 단계

• 코드 관리 — 컬렉션 내 코드 아티팩트 관리
• 버전 관리 — 리소스 버전 관리 시스템
• 아이템 추가 — 컬렉션에 데이터셋 추가하기