코드 모듈과 구성

코드 모듈과 구성 (Code Modules and Organization)

Apache Pinot Maven 모듈의 개요와 코드베이스가 어떻게 구성되어 있는지 다루는 문서예요. Apache Pinot는 다중 모듈 Maven 프로젝트예요. 각 모듈은 특정 기능을 제공하며 개별적으로 배포 가능한 서비스로 조합될 수 있어요.

출처: 문서

본문

Apache Pinot는 다중 모듈 Maven 프로젝트예요. 각 모듈은 특정 기능을 제공하며 개별적으로 배포 가능한 서비스로 조합될 수 있어요. 이 페이지는 저장소의 모든 최상위 모듈을 아키텍처 계층별로 그룹화해 설명해요.

소스 코드는 각 모듈의 src/main/java에 있고, 해당 단위 테스트는 src/test/java 아래에 있어요.

SPI / 기초 (SPI / Foundation)

이 모듈들은 나머지 Pinot가 의존하는 인터페이스, 데이터 타입, 공유 유틸리티를 정의해요. 의도적으로 최소한의 의존성 풋프린트를 가져요.

모듈	설명
`pinot-spi`	서비스 제공자 인터페이스 -- 파일 시스템, 스트림 수집, 입력 형식, 메트릭, 인증 등에 대한 플러그인 계약을 정의. 모든 플러그인 구현이 이 모듈에 의존.
`pinot-segment-spi`	세그먼트 수준 SPI -- 로컬·원격 세그먼트 구현 모두가 사용하는 컬럼 데이터 소스, 리더, 세그먼트 메타데이터에 대한 추상화. 이 인터페이스 중 다수는 `@InterfaceAudience.Private`이므로 이를 대상으로 컴파일하는 커스텀 구현은 매 Pinot 업그레이드마다 재검증해야 함.
`pinot-common`	테이블 구성 정의, 메트릭 헬퍼, Zookeeper 메타데이터 모델, 요청/응답 형식, 공통 유틸리티를 포함해 Pinot 컴포넌트 전반에 걸쳐 사용되는 공유 클래스.

세그먼트 저장소 (Segment Storage)

모듈	설명
`pinot-segment-local`	로컬(서버 내) 세그먼트 구현 -- 컬럼 인덱스 구조(포워드 인덱스, 역인덱스, 범위 인덱스, 텍스트 인덱스 등), 세그먼트 생성, 세그먼트 로딩 로직.

핵심 (Core)

모듈	설명
`pinot-core`	단일 스테이지 쿼리 실행(필터, 집계, 변환, group-by), 실시간 세그먼트 수집, upsert 처리, Broker·Server가 공유하는 데이터 플레인 유틸리티를 포함하는 중앙 모듈.

쿼리 엔진 (다중 스테이지) (Query Engine (Multi-Stage))

이 모듈들은 분산 조인과 기타 고급 SQL 연산을 가능하게 하는 다중 스테이지 엔진(MSE)을 구동해요.

모듈	설명
`pinot-query-planner`	Apache Calcite를 사용한 SQL 쿼리 파싱, 검증, 논리적/물리적 계획 생성. Broker와 Server 스테이지로 분할되는 분산 쿼리 계획을 생성.
`pinot-query-runtime`	다중 스테이지 쿼리 계획의 실행 런타임 -- 운영자 구현, 스테이지 간 데이터 전송(메일박스), Broker·Server에서의 쿼리 스테이지 스케줄링.

서비스 (Services)

각 Pinot 서비스는 별도 프로세스로 실행되며 Maven 모듈에 해당해요.

모듈	설명
`pinot-broker`	Broker 서비스 -- SQL 쿼리 수용, 라우팅 테이블을 사용한 쿼리 라우팅 수행, Server에 요청 분산, 부분 결과 수집·병합, 최종 응답 반환.
`pinot-controller`	Controller 서비스 -- 클러스터 관리 API, 세그먼트 관리(업로드, 할당, 보존, 리밸런스), 스키마·테이블 구성, Helix를 통한 태스크 스케줄링.
`pinot-server`	Server 서비스 -- 세그먼트 호스팅, 로컬 데이터에서 쿼리 계획 실행, 실시간·오프라인 세그먼트 서빙, 관리 REST API 노출.
`pinot-minion`	Minion 서비스 -- 세그먼트 병합, 세그먼트 purge(예: GDPR 컴플라이언스), 세그먼트 변환 같은 비동기 분산 태스크 실행. 태스크 타입은 플러그 가능.

시계열 (Time Series)

모듈	설명
`pinot-timeseries/pinot-timeseries-spi`	시계열 쿼리 엔진용 SPI -- 언어에 구애받지 않는 시계열 쿼리 계획·실행 인터페이스를 정의.
`pinot-timeseries/pinot-timeseries-planner`	시계열 쿼리용 플래너 -- 시계열 언어 표현식을 Pinot 세그먼트 위에서 실행되는 실행 가능한 쿼리 계획으로 변환.

시계열 언어 구현(예: M3QL)은 pinot-plugins/pinot-timeseries-lang 아래에 플러그인으로 제공돼요.

커넥터 (Connectors)

pinot-connectors 모듈은 외부 컴퓨팅 프레임워크에서 데이터를 수집하기 위한 통합을 포함해요.

모듈	설명
`pinot-spark-common`	Spark 기반 세그먼트 생성용 공유 코드
`pinot-spark-3-connector`	Apache Spark 3.x 배치 세그먼트 생성용 커넥터
`pinot-flink-connector`	Apache Flink 세그먼트 생성·실시간 수집용 커넥터

클라이언트 (Clients)

pinot-clients 모듈은 애플리케이션에서 Pinot를 쿼리하기 위한 클라이언트 라이브러리를 제공해요.

모듈	설명
`pinot-java-client`	Broker에 SQL 쿼리를 보내고 결과를 읽는 네이티브 Java 클라이언트
`pinot-jdbc-client`	JDBC 드라이버 구현 -- 표준 JDBC 도구·BI 애플리케이션에서 Pinot를 사용할 수 있게 함
`pinot-cli`	인터랙티브 쿼리용 명령줄 인터페이스 클라이언트

플러그인 (Plugins)

pinot-plugins 모듈은 모든 퍼스트파티 플러그인 구현의 우산이에요. 플러그인은 pinot-spi에 정의된 SPI 메커니즘을 통해 런타임에 로드돼요. 플러그인 아키텍처의 자세한 내용은 플러그인 아키텍처 섹션을 보세요.

플러그인 그룹	하위 모듈	설명
`pinot-stream-ingestion`	`pinot-kafka-base`, `pinot-kafka-3.0`, `pinot-kafka-4.0`, `pinot-kinesis`, `pinot-pulsar`	Kafka, Kinesis, Pulsar에서 실시간 수집용 스트림 커넥터
`pinot-file-system`	`pinot-s3`, `pinot-gcs`, `pinot-hdfs`, `pinot-adls`	S3, GCS, HDFS, Azure Data Lake 딥 스토어용 PinotFS 구현
`pinot-input-format`	`pinot-avro`, `pinot-json`, `pinot-csv`, `pinot-parquet`, `pinot-orc`, `pinot-thrift`, `pinot-protobuf`, `pinot-arrow`, `pinot-clp-log`, Confluent schema-registry 변형	다양한 데이터 직렬화 형식용 레코드 리더/디코더
`pinot-batch-ingestion`	`pinot-batch-ingestion-standalone`, `pinot-batch-ingestion-hadoop`, `pinot-batch-ingestion-spark-*`	Standalone, Hadoop MapReduce, Spark 기반 오프라인 세그먼트 생성용 수집 잡 러너
`pinot-metrics`	`pinot-yammer`, `pinot-dropwizard`, `pinot-compound-metrics`	메트릭 리포터 구현(Yammer, Dropwizard) 및 compound 메트릭 지원
`pinot-minion-tasks`	`pinot-minion-builtin-tasks`	내장 미니언 태스크 타입(merge/rollup, purge, 세그먼트 변환 등)
`pinot-segment-uploader`	`pinot-segment-uploader-default`	완성된 세그먼트를 Controller에 푸시하는 기본 세그먼트 업로더
`pinot-segment-writer`	`pinot-segment-writer-file-based`	수집 중 사용되는 파일 기반 세그먼트 라이터 구현
`pinot-environment`	`pinot-azure`	Azure 배포용 환경별 구성 제공자
`pinot-timeseries-lang`	`pinot-timeseries-m3ql`	시계열 쿼리 언어 플러그인(M3QL)

도구와 배포 (Tools and Distribution)

모듈	설명
`pinot-tools`	클러스터 설정, 세그먼트 관리, 데이터 생성, Pinot quick-start 런처용 명령줄 도구 모음
`pinot-distribution`	모든 모듈을 최종 Pinot 바이너리 배포판(tar.gz)으로 패키징하는 어셈블리 모듈

테스트와 검증 (Testing and Verification)

모듈	설명
`pinot-integration-test-base`	통합 테스트가 공유하는 기본 프레임워크·유틸리티(클러스터 설정 헬퍼, 테스트 테이블 구성 등)
`pinot-integration-tests`	mocking 없이 여러 컴포넌트 Pinot 클러스터를 띄우고 크로스 모듈 동작을 검증하는 End-to-End 통합 테스트
`pinot-perf`	핵심 코드 경로(인덱스 읽기, 집계, 인코딩)의 성능 평가를 위한 JMH 기반 마이크로 벤치마크
`pinot-compatibility-verifier`	Pinot 버전 간 롤링 업그레이드가 동작하는지 검증하는 하위·상위 호환성 테스트
`pinot-udf-test`	사용자 정의 스칼라·집계 함수 검증용 테스트 하네스
`pinot-dependency-verifier`	의존성 충돌 검출·의존성 수렴을 강제하는 빌드 시간 검사

배포 (Deployment)

이 디렉토리들은 Maven 모듈이 아니라 배포 아티팩트를 포함해요.

디렉토리	설명
`docker/`	Pinot 컨테이너 이미지 구축용 Dockerfile과 지원 스크립트
`helm/`	Broker, Controller, Server, Minion, Zookeeper 템플릿을 포함한 Kubernetes에 Pinot 배포용 Helm 차트

주요 외부 의존성 (Key External Dependencies)

Pinot는 여러 중요한 외부 프로젝트 위에 구축돼요:

Apache Helix / ZooKeeper -- 클러스터 관리, 리소스 할당, 분산 상태 조정
Apache Calcite -- 다중 스테이지 쿼리 엔진용 SQL 파싱·쿼리 계획
Apache Kafka -- 실시간 수집용 기본 스트림 제공자(SPI를 통해 플러그 가능)
Netty -- Broker와 Server 사이의 논블로킹 네트워크 전송
Google Guava -- 캐시, 속도 제한기, 범용 유틸리티
RoaringBitmap -- 역인덱스·필터링에 사용되는 압축 비트맵 라이브러리
T-Digest -- 백분위수 집계 함수용 분위수 추정

코드 모듈과 구성