Broker gRPC API
Broker gRPC API
Pinot 브로커 gRPC 쿼리 레퍼런스를 다루는 문서예요. Pinot의 브로커 gRPC API는 HTTP 쿼리 제출의 전송 대안이에요. 클라이언트 라이브러리가 더 낮은 오버헤드, Arrow 인코딩, 또는 연결 수준 압축 제어를 원할 때 주로 유용해요.
출처: 문서
본문
Pinot의 브로커 gRPC API는 HTTP 쿼리 제출의 전송 대안이에요. 클라이언트 라이브러리가 낮은 오버헤드, Arrow 인코딩, 또는 연결 수준 압축 제어를 원할 때 주로 유용해요.
활성화 (Enablement)
pinot.broker.grpc.port=8010
pinot.broker.grpc.tls.enabled=true
pinot.broker.grpc.tls.port=8020
보안 브로커 gRPC 리스너를 노출하면 현재 브로커 시작 경로는 키스토어·트러스트스토어에 pinot.broker.tls.* 아래의 TLS 자재를 재사용해요. 전체 리스너·TLS 설정은 브로커 구성 레퍼런스를 보세요.
클라이언트 옵션 (Client Options)
Java gRPC 클라이언트와 JDBC pinotgrpc 드라이버는 둘 다 연결 전송 설정에 GrpcConfig를 사용해요. 즉 같은 전송 속성 이름이 Java Properties와 JDBC URL 쿼리 파라미터 모두에서 동작해요.
요청 메타데이터 옵션 (Request Metadata Options)
| 옵션 | 기본값 | 메모 |
|---|---|---|
blockRowSize |
10000 |
응답 블록당 행 수 |
compression |
ZSTD |
전송 압축 선택 |
encoding |
JSON |
결과 전송 인코딩; ARROW도 지원 |
headers.<name> |
없음 | headers.Authorization 같은 요청 메타데이터 헤더 추가 |
전송 속성 (Transport Properties)
| 속성 | 기본값 | 메모 |
|---|---|---|
usePlainText |
true |
일반 텍스트 gRPC 전송 사용. TLS를 활성화하려면 false로 설정. |
maxInboundMessageSizeBytes |
134217728 (128 MB) |
클라이언트가 수용하는 최대 인바운드 gRPC 메시지 크기 |
channelKeepAliveTimeSeconds |
-1 (비활성) |
Keepalive 핑 간격. keepalive를 활성화하려면 양수 값 설정 |
channelKeepAliveTimeoutSeconds |
20 |
keepalive 확인을 기다리는 타임아웃 |
channelKeepAliveWithoutCalls |
true |
활성 RPC가 없어도 keepalive 핑 허용 |
channelShutdownTimeoutSeconds |
10 |
클라이언트가 종료 시 gRPC 채널 종료를 기다리는 시간 |
tls.keystore.type |
JVM 기본 키스토어 타입 (KeyStore.getDefaultType()) |
상호 TLS용 클라이언트 키스토어 타입 |
tls.keystore.path |
없음 | 상호 TLS용 클라이언트 키스토어 경로 |
tls.keystore.password |
없음 | 클라이언트 키스토어 비밀번호 |
tls.truststore.type |
JVM 기본 키스토어 타입 (KeyStore.getDefaultType()) |
브로커 인증서 검증에 사용하는 트러스트스토어 타입 |
tls.truststore.path |
없음 | 브로커 인증서 검증에 사용하는 트러스트스토어 경로 |
tls.truststore.password |
없음 | 트러스트스토어 비밀번호 |
tls.ssl.provider |
JDK |
gRPC 클라이언트 SSL 컨텍스트 생성 시 사용하는 SSL 제공자 |
tls.insecure |
false |
브로커 인증서 검증 건너뛰기. 프로덕션 외 테스트에만 적절 |
tls.protocols |
JVM TLS 기본값 | TLSv1.2,TLSv1.3 같은 쉼표로 구분된 TLS 프로토콜 허용 목록 |
클라이언트 예시 (Client Examples)
gRPC Java와 JDBC 클라이언트는 pinotgrpc 스킴을 사용해요.
Properties properties = new Properties();
properties.setProperty("usePlainText", "false");
properties.setProperty("tls.truststore.path", "/path/to/grpc-truststore.jks");
properties.setProperty("tls.truststore.password", "changeit");
GrpcConnection grpcConnection = ConnectionFactory.fromControllerGrpc(properties, "localhost:9000");
ResultSetGroup resultSetGroup = grpcConnection.execute(
"SELECT * FROM airlineStats LIMIT 1000",
Map.of("blockRowSize", "10000", "encoding", "JSON", "compression", "ZSTD"));
Properties properties = new Properties();
properties.setProperty("usePlainText", "false");
properties.setProperty("tls.truststore.path", "/path/to/grpc-truststore.jks");
properties.setProperty("tls.truststore.password", "changeit");
try (Connection connection = DriverManager.getConnection(
"jdbc:pinotgrpc://localhost:9000?blockRowSize=10000&encoding=JSON&compression=ZSTD",
properties)) {
// execute queries
}
운영 노트 (Operational Notes)
- Arrow 기반 클라이언트를 실행할 때는 같은
--add-opensJVM 플래그를 사용해요. - 연결 설정은 가벼운 검증 쿼리를 수행해요.
- 클라이언트 TLS 속성은 브로커 측 키(예:
pinot.broker.tls.*)가 아니라tls.*아래에 네임스페이스가 지정돼요. - Java gRPC 클라이언트는
execute(..., metadataMap)또는executeGrpc(..., metadataMap)에 전달한 메타데이터 맵을 통해 요청별로blockRowSize,compression,encoding을 받아요. - JDBC gRPC 드라이버도 URL 파라미터나 연결 속성으로
blockRowSize,compression,encoding을 수용해 요청 메타데이터로 전달해요. - 브로커가 브로커-서버 통신에도
pinot.broker.request.handler.type=grpc를 사용한다면, 비슷한 이름의 최상위broker.confkeepalive·shutdown 설정은 Java/JDBC 클라이언트 연결이 아니라 브로커의 아웃바운드 채널에 적용돼요.
이 페이지에서 다룬 내용 (What this page covered)
- 브로커 gRPC 활성화 방법
- 가장 중요한 클라이언트 측 옵션
- 클라이언트 작성자가 알아야 할 연결·인코딩 동작
다음 단계 (Next step)
통합 코드가 필요하다면 Java 또는 JDBC 클라이언트 문서를 사용하고, 노출하려는 브로커 엔드포인트에 대해 쿼리 경로를 검증하세요.