> For the complete documentation index, see [llms.txt](https://kopens.gitbook.io/plantpulse-platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kopens.gitbook.io/plantpulse-platform/admin/modules/warehouse.md).

# warehouse (레이크하우스)

## 역할

Cassandra 의 시계열 데이터를 **Apache Iceberg** 형식으로 MinIO 에 아카이빙하는 **레이크하우스** 모듈. 장기 보관, 분석 쿼리 성능, 다른 BI 도구 연동을 위해 사용합니다.

| 항목    | 값                                                       |
| ----- | ------------------------------------------------------- |
| 모듈명   | `plantpulse-warehouse`                                  |
| 설치 경로 | `/opt/kopens/plantpulse-platform/plantpulse-warehouse/` |
| 포트    | **9600**                                                |
| 형식    | Apache Iceberg V2                                       |
| 저장    | MinIO (S3)                                              |

## 구성

```mermaid
graph LR
  CASS[(Cassandra<br/>시계열)] --> SPARK[Spark Submit<br/>archive.sh]
  SPARK --> ICEBERG[Iceberg 테이블]
  ICEBERG --> MINIO[(MinIO<br/>plantpulse-iceberg)]

  KYUUBI[Kyuubi SQL] --> ICEBERG
  BI[BI Tools<br/>Tableau / Superset] --> KYUUBI
```

## 디렉토리 구조

```
plantpulse-warehouse/
├── app/                          # 웨어하우스 서비스
├── bin/start.sh stop.sh log-viewer.sh
├── config/
├── etc/                          # PID 관리
├── lib/                          # Spark JAR
├── logs/system.log
└── s3/
    ├── archive.sh                # 아카이빙
    └── optimize.sh               # 테이블 최적화
```

## 아카이빙 (archive.sh)

```bash
# 전일 데이터 아카이빙 (기본)
/opt/kopens/plantpulse-platform/plantpulse-warehouse/s3/archive.sh

# 특정 날짜
/opt/kopens/plantpulse-platform/plantpulse-warehouse/s3/archive.sh 2026-05-29
```

* 1,000,000건 기준 약 60초
* 대상: Cassandra `tm_tag_point` → MinIO `plantpulse-iceberg/warehouse/tag_point/`
* 파티션: `dt=YYYY-MM-DD/hh=HH/`

## Iceberg 테이블 최적화 (optimize.sh)

작은 파일 병합, 만료된 스냅샷 삭제, 메타데이터 정리.

```bash
/opt/kopens/plantpulse-platform/plantpulse-warehouse/s3/optimize.sh
```

권장 주기: **주 1회 야간**. Kestra 워크플로우로 자동화 가능.

## 운영 명령

```bash
cd /opt/kopens/plantpulse-platform/plantpulse-startup

./restart-warehouse.sh
./status.sh                # 9600 RUNNING 확인
```

## 자주 발생하는 문제

| 증상            | 원인               | 조치                                   |
| ------------- | ---------------- | ------------------------------------ |
| 아카이빙 Job 실패   | Spark / Hive 미준비 | `restart-analytics.sh` 후 재시도         |
| 작은 파일 폭증      | optimize.sh 미실행  | 주 1회 정기 실행                           |
| MinIO 디스크 부족  | retention 미설정    | Iceberg expire snapshots + 라이프사이클 정책 |
| Kyuubi 쿼리 OOM | 큰 테이블 / 파티션 누락   | `WHERE dt = '...'` 명시                |

## SQL 조회 예제

```sql
USE iceberg;

-- 메타데이터
DESCRIBE TABLE EXTENDED tag_point;

-- 5월 집계
SELECT tag_id, count(*) AS rows, min(time), max(time)
FROM tag_point
WHERE dt BETWEEN '2026-05-01' AND '2026-05-31'
GROUP BY tag_id
ORDER BY rows DESC
LIMIT 100;

-- 스냅샷 이력
SELECT * FROM tag_point.snapshots;
SELECT * FROM tag_point.history;
```

## 관련 문서

* [모듈 인덱스](/plantpulse-platform/admin/modules.md)
* [analytics 모듈](/plantpulse-platform/admin/modules/analytics.md)
* [storage 모듈](/plantpulse-platform/admin/modules/storage.md)
* [백업 및 복구](/plantpulse-platform/admin/backup-recovery.md)