파일 시스템 플러그인

파일 시스템 플러그인 (Filesystem Plugin)

Pinot 사용자가 실시간·오프라인 세그먼트용 데이터 저장소를 원하는 곳에 저장할 수 있는 PinotFS 추상화 계층을 작성하는 방법을 다루는 문서예요.

출처: 문서

본문

Pinot는 사용자가 실시간·오프라인 세그먼트용 데이터를 원하는 데이터 계층에 저장할 수 있게 PinotFS 추상화 계층을 작성할 수 있게 해줘요.

현재 지원되는 저장소 백엔드(로컬 저장소 외)의 일부 예시는 다음과 같아요:

위 두 파일 시스템이 요구를 충족하지 못하면 현재 PinotFS를 확장해 요구에 맞게 커스터마이즈할 수 있어요.

새 저장소 타입 구현 (New Storage Type implementation)

Amazon S3 같은 새 저장소 백엔드 타입을 추가하려면 PinotFS 클래스를 구현해야 해요. 인터페이스는 mkdir, list 같은 파일 시스템 접근 관련 공통 메서드를 기대해요.

클래스가 준비되면 컴파일해 pinot의 /plugins 디렉토리에 넣으면 돼요.

효율적인 대형 버킷 파일 나열 (Efficient Large-Bucket File Listing)

PinotFS SPI에는 많은 수의 객체가 있는 클라우드 저장소 백엔드를 위한 listFilesWithMetadata의 최적화된 오버로드가 포함돼요:

List<FileMetadata> listFilesWithMetadata(
    URI fileUri,
    boolean recursive,
    Predicate<String> pathFilter,
    int maxResults) throws IOException

파라미터:

  • pathFilter — 결과 페이지마다 적용되어, 반환되기 전에 일치하지 않는 객체를 건너뜀
  • maxResults — 이만큼 결과가 누적되면 즉시 나열을 중단 (조기 종료)

왜 오버라이드하나요? 기본 구현은 모든 객체를 먼저 가져온 뒤 메모리에서 필터링하는데, 수백만 개의 객체가 있는 버킷에서는 OOM 오류를 유발할 수 있어요. 이 메서드를 네이티브 페이지네이션(예: S3 continuationToken, GCS Page.getNextPage(), ADLS PagedIterable)으로 구현하면 모든 객체를 메모리에 로드하는 것을 피하고 불필요한 API 호출·비용을 줄여요.

기본 동작: 커스텀 PinotFS 구현이 이 메서드를 오버라이드하지 않으면 기존 listFilesWithMetadata(URI, boolean) 메서드로 폴백하고 필터링·절단을 사후에 적용해요.

실시간 테이블에서 플러그인 사용 (Using plugin in real-time table)

URI의 기본 스킴(scheme://host:port/path)을 접미사로 사용해 실시간 또는 배치 테이블에서 구성을 설정할 수 있어요. 예를 들어 경로 hdfs://user/yarn/path/to/dir의 기본 스킴은 hdfs이고, 모든 구성 키에는 pinot.controller.storage.factory.hdfs처럼 hdfs가 들어가야 해요.

여기 예시는 기존 org.apache.pinot.filesystem.HadoopPinotFS를 사용해 HDFS 파일 시스템에 실시간 세그먼트를 저장해요. Pinot 컨트롤러 구성에 다음 새 구성을 추가해요:

"controller.data.dir": "SET_TO_YOUR_HDFS_ROOT_DIR"
"controller.local.temp.dir": "SET_TO_A_LOCAL_FILESYSTEM_DIR"
"pinot.controller.storage.factory.class.hdfs": "org.apache.pinot.filesystem.HadoopPinotFS"
"pinot.controller.storage.factory.hdfs.hadoop.conf.path": "SET_TO_YOUR_HDFS_CONFIG_DIR"
"pinot.controller.storage.factory.hdfs.hadoop.kerberos.principle": "SET_IF_YOU_USE_KERBEROS"
"pinot.controller.storage.factory.hdfs.hadoop.kerberos.keytab": "SET_IF_YOU_USE_KERBEROS"
"controller.enable.split.commit": "true"

Pinot 컨트롤러 구성에 다음 새 구성을 추가해요:

"pinot.server.instance.enable.split.commit": "true"

오프라인 테이블 구성 (Configurations for Offline Tables)

이 스트림 구현 속성들은 컨트롤러와 서버 구성에 설정해야 해요.

컨트롤러·서버 구성에서 지원하려는 FS 클래스를 설정해요. pinot.controller.storage.factory.class.${YOUR_URI_SCHEME}를 포함하려는 FS 클래스의 전체 경로로 설정해요.

또한 컨트롤러 머신의 로컬 디렉토리용 pinot.controller.local.temp.dir을 구성해야 해요.

파일 시스템 특정 구성은 pinot.controller 접두사 또는 pinot.server 접두사로 전달할 수 있어요.

다음 모든 구성은 storage.factory로 접두사가 지정되어야 해요.

예를 들어 AzurePinotFS는 환경에 따라 다음 구성을 요구해요:

adl.accountId, adl.authEndpoint, adl.clientId, adl.clientSecret

샘플 컨트롤러 구성:

"pinot.controller.storage.factory.class.adl": "org.apache.pinot.filesystem.AzurePinotFS"
"pinot.controller.storage.factory.adl.accountId": "xxxx"
"pinot.controller.storage.factory.adl.authEndpoint": "xxxx"
"pinot.controller.storage.factory.adl.clientId": "xxxx"
"pinot.controller.segment.fetcher.protocols": "adl"

샘플 서버 구성:

"pinot.server.storage.factory.class.adl": "org.apache.pinot.filesystem.AzurePinotFS"
"pinot.server.storage.factory.adl.accountId": "xxxx"
"pinot.server.storage.factory.adl.authEndpoint": "xxxx"
"pinot.server.storage.factory.adl.clientId": "xxxx"
"pinot.server.segment.fetcher.protocols": "adl"

계정에서 파라미터를 찾는 방법: https://stackoverflow.com/questions/56349040/what-is-clientid-authtokenendpoint-clientkey-for-accessing-azure-data-lake

또한 다음 구성을 adl 값으로 설정해야 해요:

"segment.fetcher.protocols" : "adl"

다른 저장소 시스템에 세그먼트를 업로드하는 방법은 배치 세그먼트 페처 플러그인을 보세요.

더 알아보기 (Learn more)