336 lines
7.7 KiB
Markdown
336 lines
7.7 KiB
Markdown
# 컬럼 매핑 기능 사용 가이드
|
||
|
||
## 📋 개요
|
||
|
||
**컬럼 매핑**은 여러 데이터 소스의 서로 다른 컬럼명을 통일된 이름으로 변환하여 데이터를 통합할 수 있게 해주는 기능입니다.
|
||
|
||
## 🎯 사용 시나리오
|
||
|
||
### 시나리오 1: 여러 데이터베이스 통합
|
||
|
||
```
|
||
데이터 소스 1 (PostgreSQL):
|
||
SELECT name, amount, created_at FROM orders
|
||
|
||
데이터 소스 2 (MySQL):
|
||
SELECT product_name, total, order_date FROM sales
|
||
|
||
데이터 소스 3 (Oracle):
|
||
SELECT item, price, timestamp FROM transactions
|
||
```
|
||
|
||
**문제**: 각 데이터베이스의 컬럼명이 달라서 통합이 어렵습니다.
|
||
|
||
**해결**: 컬럼 매핑으로 통일!
|
||
|
||
```
|
||
데이터 소스 1 매핑:
|
||
name → product
|
||
amount → value
|
||
created_at → date
|
||
|
||
데이터 소스 2 매핑:
|
||
product_name → product
|
||
total → value
|
||
order_date → date
|
||
|
||
데이터 소스 3 매핑:
|
||
item → product
|
||
price → value
|
||
timestamp → date
|
||
```
|
||
|
||
**결과**: 모든 데이터가 `product`, `value`, `date` 컬럼으로 통합됩니다!
|
||
|
||
---
|
||
|
||
## 🔧 사용 방법
|
||
|
||
### 1️⃣ 데이터 소스 추가
|
||
|
||
대시보드 편집 모드에서 위젯의 "데이터 소스 관리" 섹션으로 이동합니다.
|
||
|
||
### 2️⃣ 쿼리/API 테스트
|
||
|
||
- **Database**: SQL 쿼리 입력 후 "쿼리 테스트" 클릭
|
||
- **REST API**: API 설정 후 "API 테스트" 클릭
|
||
|
||
### 3️⃣ 컬럼 매핑 설정
|
||
|
||
테스트 성공 후 **"🔄 컬럼 매핑 (선택사항)"** 섹션이 나타납니다.
|
||
|
||
#### 매핑 추가:
|
||
1. 드롭다운에서 원본 컬럼 선택
|
||
2. 표시 이름 입력 (예: `name` → `product`)
|
||
3. 자동으로 매핑 추가됨
|
||
|
||
#### 매핑 수정:
|
||
- 오른쪽 입력 필드에서 표시 이름 변경
|
||
|
||
#### 매핑 삭제:
|
||
- 각 매핑 행의 ❌ 버튼 클릭
|
||
- 또는 "초기화" 버튼으로 전체 삭제
|
||
|
||
### 4️⃣ 적용 및 저장
|
||
|
||
1. "적용" 버튼 클릭
|
||
2. 대시보드 저장
|
||
|
||
---
|
||
|
||
## 📊 지원 위젯
|
||
|
||
컬럼 매핑은 다음 **모든 다중 데이터 소스 위젯**에서 사용 가능합니다:
|
||
|
||
- ✅ **지도 위젯** (`map-summary-v2`)
|
||
- ✅ **통계 카드** (`custom-metric-v2`)
|
||
- ✅ **리스트 위젯** (`list-v2`)
|
||
- ✅ **리스크/알림 위젯** (`risk-alert-v2`)
|
||
- ✅ **차트 위젯** (`chart`)
|
||
|
||
---
|
||
|
||
## 💡 실전 예시
|
||
|
||
### 예시 1: 주문 데이터 통합
|
||
|
||
**데이터 소스 1 (내부 DB)**
|
||
```sql
|
||
SELECT
|
||
customer_name,
|
||
order_amount,
|
||
order_date
|
||
FROM orders
|
||
```
|
||
|
||
**컬럼 매핑:**
|
||
- `customer_name` → `name`
|
||
- `order_amount` → `amount`
|
||
- `order_date` → `date`
|
||
|
||
---
|
||
|
||
**데이터 소스 2 (외부 API)**
|
||
|
||
API 응답:
|
||
```json
|
||
[
|
||
{ "clientName": "홍길동", "totalPrice": 50000, "timestamp": "2025-01-01" }
|
||
]
|
||
```
|
||
|
||
**컬럼 매핑:**
|
||
- `clientName` → `name`
|
||
- `totalPrice` → `amount`
|
||
- `timestamp` → `date`
|
||
|
||
---
|
||
|
||
**결과 (통합된 데이터):**
|
||
```json
|
||
[
|
||
{ "name": "홍길동", "amount": 50000, "date": "2025-01-01", "_source": "내부 DB" },
|
||
{ "name": "홍길동", "amount": 50000, "date": "2025-01-01", "_source": "외부 API" }
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### 예시 2: 지도 위젯 - 위치 데이터 통합
|
||
|
||
**데이터 소스 1 (기상청 API)**
|
||
```json
|
||
[
|
||
{ "location": "서울", "lat": 37.5665, "lon": 126.9780, "temp": 15 }
|
||
]
|
||
```
|
||
|
||
**컬럼 매핑:**
|
||
- `lat` → `latitude`
|
||
- `lon` → `longitude`
|
||
- `location` → `name`
|
||
|
||
---
|
||
|
||
**데이터 소스 2 (교통정보 DB)**
|
||
```sql
|
||
SELECT
|
||
address,
|
||
y_coord AS latitude,
|
||
x_coord AS longitude,
|
||
status
|
||
FROM traffic_info
|
||
```
|
||
|
||
**컬럼 매핑:**
|
||
- `address` → `name`
|
||
- (latitude, longitude는 이미 올바른 이름)
|
||
|
||
---
|
||
|
||
**결과**: 모든 데이터가 `name`, `latitude`, `longitude`로 통일되어 지도에 표시됩니다!
|
||
|
||
---
|
||
|
||
## 🔍 SQL Alias vs 컬럼 매핑
|
||
|
||
### SQL Alias (방법 1)
|
||
|
||
```sql
|
||
SELECT
|
||
name AS product,
|
||
amount AS value,
|
||
created_at AS date
|
||
FROM orders
|
||
```
|
||
|
||
**장점:**
|
||
- SQL 쿼리에서 직접 처리
|
||
- 백엔드에서 이미 변환됨
|
||
|
||
**단점:**
|
||
- SQL 지식 필요
|
||
- REST API에는 사용 불가
|
||
|
||
---
|
||
|
||
### 컬럼 매핑 (방법 2)
|
||
|
||
UI에서 클릭만으로 설정:
|
||
- `name` → `product`
|
||
- `amount` → `value`
|
||
- `created_at` → `date`
|
||
|
||
**장점:**
|
||
- SQL 지식 불필요
|
||
- REST API에도 사용 가능
|
||
- 언제든지 수정 가능
|
||
- 실시간 미리보기
|
||
|
||
**단점:**
|
||
- 프론트엔드에서 처리 (약간의 오버헤드)
|
||
|
||
---
|
||
|
||
## ✨ 권장 사항
|
||
|
||
### 언제 SQL Alias를 사용할까?
|
||
- SQL에 익숙한 경우
|
||
- 백엔드에서 처리하고 싶은 경우
|
||
- 복잡한 변환 로직이 필요한 경우
|
||
|
||
### 언제 컬럼 매핑을 사용할까?
|
||
- SQL을 모르는 경우
|
||
- REST API 데이터를 다룰 때
|
||
- 빠르게 테스트하고 싶을 때
|
||
- 여러 데이터 소스를 통합할 때
|
||
|
||
### 두 가지 모두 사용 가능!
|
||
- SQL Alias로 일차 변환
|
||
- 컬럼 매핑으로 추가 변환
|
||
- 예: `SELECT name AS product_name` → 컬럼 매핑: `product_name` → `product`
|
||
|
||
---
|
||
|
||
## 🚨 주의사항
|
||
|
||
### 1. 매핑하지 않은 컬럼은 원본 이름 유지
|
||
```
|
||
원본: { name: "A", amount: 100, status: "active" }
|
||
매핑: { name: "product" }
|
||
결과: { product: "A", amount: 100, status: "active" }
|
||
```
|
||
|
||
### 2. 중복 컬럼명 주의
|
||
```
|
||
원본: { name: "A", product: "B" }
|
||
매핑: { name: "product" }
|
||
결과: { product: "A" } // 기존 product 컬럼이 덮어씌워짐!
|
||
```
|
||
|
||
### 3. 대소문자 구분
|
||
- PostgreSQL: 소문자 권장 (`user_name`)
|
||
- JavaScript: 카멜케이스 권장 (`userName`)
|
||
- 매핑으로 통일 가능!
|
||
|
||
---
|
||
|
||
## 🔄 데이터 흐름
|
||
|
||
```
|
||
1. 데이터 소스에서 원본 데이터 로드
|
||
↓
|
||
2. 컬럼 매핑 적용 (applyColumnMapping)
|
||
↓
|
||
3. 통일된 컬럼명으로 변환된 데이터
|
||
↓
|
||
4. 위젯에서 표시/처리
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 기술 세부사항
|
||
|
||
### 유틸리티 함수
|
||
|
||
**파일**: `frontend/lib/utils/columnMapping.ts`
|
||
|
||
#### `applyColumnMapping(data, columnMapping)`
|
||
- 데이터 배열에 컬럼 매핑 적용
|
||
- 매핑이 없으면 원본 그대로 반환
|
||
|
||
#### `mergeDataSources(dataSets)`
|
||
- 여러 데이터 소스를 병합
|
||
- 각 데이터 소스의 매핑을 자동 적용
|
||
- `_source` 필드로 출처 표시
|
||
|
||
---
|
||
|
||
## 🎓 학습 자료
|
||
|
||
### 관련 파일
|
||
- 타입 정의: `frontend/components/admin/dashboard/types.ts`
|
||
- UI 컴포넌트: `frontend/components/admin/dashboard/data-sources/MultiApiConfig.tsx`
|
||
- UI 컴포넌트: `frontend/components/admin/dashboard/data-sources/MultiDatabaseConfig.tsx`
|
||
- 유틸리티: `frontend/lib/utils/columnMapping.ts`
|
||
|
||
### 위젯 구현 예시
|
||
- 지도: `frontend/components/dashboard/widgets/MapTestWidgetV2.tsx` (subtype: `map-summary-v2`)
|
||
- 통계 카드: `frontend/components/dashboard/widgets/CustomMetricTestWidget.tsx` (subtype: `custom-metric-v2`)
|
||
- 리스트: `frontend/components/dashboard/widgets/ListTestWidget.tsx` (subtype: `list-v2`)
|
||
- 알림: `frontend/components/dashboard/widgets/RiskAlertTestWidget.tsx` (subtype: `risk-alert-v2`)
|
||
- 차트: `frontend/components/dashboard/widgets/ChartTestWidget.tsx` (subtype: `chart`)
|
||
|
||
---
|
||
|
||
## ❓ FAQ
|
||
|
||
### Q1: 컬럼 매핑이 저장되나요?
|
||
**A**: 네! 대시보드 저장 시 함께 저장됩니다.
|
||
|
||
### Q2: 매핑 후 원본 컬럼명으로 되돌릴 수 있나요?
|
||
**A**: 네! 해당 매핑을 삭제하면 원본 이름으로 돌아갑니다.
|
||
|
||
### Q3: REST API와 Database를 동시에 매핑할 수 있나요?
|
||
**A**: 네! 각 데이터 소스마다 독립적으로 매핑할 수 있습니다.
|
||
|
||
### Q4: 성능에 영향이 있나요?
|
||
**A**: 매우 적습니다. 단순 객체 키 변환이므로 빠릅니다.
|
||
|
||
### Q5: 컬럼 타입이 변경되나요?
|
||
**A**: 아니요! 컬럼 이름만 변경되고, 값과 타입은 그대로 유지됩니다.
|
||
|
||
---
|
||
|
||
## 🎉 마무리
|
||
|
||
컬럼 매핑 기능을 사용하면:
|
||
- ✅ 여러 데이터 소스를 쉽게 통합
|
||
- ✅ SQL 지식 없이도 데이터 변환
|
||
- ✅ REST API와 Database 모두 지원
|
||
- ✅ 실시간으로 결과 확인
|
||
- ✅ 언제든지 수정 가능
|
||
|
||
**지금 바로 사용해보세요!** 🚀
|
||
|