> 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/sql.md).

# sql (SQL 서비스)

## 역할

플랫폼 데이터에 대한 ad-hoc SQL 쿼리 서비스. 콘솔의 **DATA > SQL 도구** 메뉴에서 사용자가 입력한 SQL 을 실행하고 결과를 반환합니다.

| 항목    | 값                                                 |
| ----- | ------------------------------------------------- |
| 모듈명   | `plantpulse-sql`                                  |
| 설치 경로 | `/opt/kopens/plantpulse-platform/plantpulse-sql/` |
| 포트    | **4000**                                          |
| 백엔드   | Kyuubi (`PP_KYUUBI_PORT`)                         |

## 구성

```mermaid
graph LR
  CONSOLE[콘솔 SQL 에디터] --> SQLM[plantpulse-sql :4000]
  SQLM --> KY[Kyuubi :10000]
  KY --> SPARK[Spark]
  SPARK --> ICEBERG[(Iceberg)]
  SPARK --> CASS[(Cassandra)]
  SPARK --> PG[(PostgreSQL)]
```

## 주요 책임

* SQL 요청 큐잉 + 동시성 제한
* 쿼리 실행 / 취소
* 결과 페이지네이션
* 쿼리 이력 저장

## 디렉토리 구조

```
plantpulse-sql/
├── app/
├── bin/start.sh stop.sh log-viewer.sh
├── logs/system.log
└── server/conf/server.xml
```

## 운영 명령

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

./restart-sql.sh
./status.sh                # 4000 RUNNING 확인
```

## 자주 발생하는 문제

| 증상           | 원인                | 조치                            |
| ------------ | ----------------- | ----------------------------- |
| 쿼리 영구 대기     | Kyuubi / Spark 다운 | analytics 모듈 점검               |
| 큰 결과 OOM     | LIMIT 미사용         | 콘솔에서 `LIMIT` 강제 또는 결과 파일 다운로드 |
| 동시 사용자 응답 지연 | Spark executor 부족 | `spark.cores.max` 상향          |

## 관련 문서

* [모듈 인덱스](/plantpulse-platform/admin/modules.md)
* [analytics 모듈](/plantpulse-platform/admin/modules/analytics.md)
* [warehouse 모듈](/plantpulse-platform/admin/modules/warehouse.md)