pinot-client 1.27.0 → 1.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfd22c5e76430105c17c3a1279b002084aebb894d4c561913908a4d00038b519
-  data.tar.gz: e668583cdd1afde9b9b35dab28c46b2e707643911a0800cdb98950ac1de2731b
+  metadata.gz: f728a6fe054a729893524d1da24e6ab2cddabda2d17c3bfae183e77271a70b1c
+  data.tar.gz: 6f10e6f81f725d9e34ed0d68a3ed04070244308f949a7a01533f90940fff18a9
 SHA512:
-  metadata.gz: 1aba59c0e39a601dacccfa2f413b9405ad0835e94555272a8f7bf8177b421fd0eac861144fb44d24c69ec41f51834b67a786ed4bd29afb48ae6667671f5ce112
-  data.tar.gz: c81b393e62ffba2390a7c21a52fb0b0a3f0fdfd0421b3a78d9bcbcc772a35f2613e451f58a28cdcb9ecd30c6120aa114f94ae3a80c825594a0cc9baa98a521ca
+  metadata.gz: 26d0a240f8d335f1acf02363ab974bf8e0323c3ddc045b2c9539340468231d68c6fe6c1c8517e0fb8a79ad4b154bd8178847e890d8475280200b33f327fcb467
+  data.tar.gz: 987c72674f5902f79365ff493ff541299e0efcc13374016bee1c52b98018734ff50498d7991c08807f50c5e0b70aff2be734eaa564ba7aa640da6530e66b4665

data/lib/pinot/active_support_notifications.rb

@@ -43,12 +43,12 @@ module Pinot
   # ActiveSupport::Notifications to already be defined at install! time (which
   # is always the case in a Rails process).
   module ActiveSupportNotifications
-    EVENT_NAME = "sql.pinot"
+    EVENT_NAME = "sql.pinot".freeze
 
     def self.install!
       return if installed?
 
-      Pinot::Instrumentation.on_query = method(:notify)
+      @listener  = Pinot::Instrumentation.subscribe(method(:notify))
       @installed = true
     end
 
@@ -57,16 +57,17 @@ module Pinot
     end
 
     def self.uninstall!
-      Pinot::Instrumentation.on_query = nil
+      Pinot::Instrumentation.unsubscribe(@listener) if @listener
+      @listener  = nil
       @installed = false
     end
 
     def self.notify(event)
       payload = {
-        sql:      event[:query],
-        name:     event[:table],
+        sql: event[:query],
+        name: event[:table],
         duration: event[:duration_ms],
-        success:  event[:success]
+        success: event[:success]
       }
 
       if (err = event[:error])

data/lib/pinot/circuit_breaker.rb

@@ -34,7 +34,8 @@ module Pinot
     OPEN      = :open
     HALF_OPEN = :half_open
 
-    BrokerCircuitOpenError = Class.new(BrokerNotFoundError)
+    class BrokerCircuitOpenError < BrokerNotFoundError
+    end
 
     attr_reader :state, :failure_count
 
@@ -48,14 +49,14 @@ module Pinot
     end
 
     # Call the block; record success/failure and enforce open-circuit rejection.
-    def call(broker_address)
+    def call(_broker_address)
       @mutex.synchronize { check_state! }
       begin
         result = yield
         @mutex.synchronize { on_success }
         result
       rescue BrokerUnavailableError, Errno::ECONNRESET, Errno::ECONNREFUSED,
-             Errno::ETIMEDOUT, Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout => e
+             Errno::ETIMEDOUT, Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout
         @mutex.synchronize { on_failure }
         raise
       end
@@ -126,7 +127,7 @@ module Pinot
       @mutex.synchronize do
         @breakers[broker_address] ||= CircuitBreaker.new(
           failure_threshold: @failure_threshold,
-          open_timeout:      @open_timeout
+          open_timeout: @open_timeout
         )
       end
     end

data/lib/pinot/config.rb

@@ -89,9 +89,7 @@ module Pinot
         raise ConfigurationError, "query_timeout_ms must be positive, got: #{query_timeout_ms}"
       end
 
-      if !pool_size.nil? && pool_size < 1
-        raise ConfigurationError, "pool_size must be at least 1, got: #{pool_size}"
-      end
+      raise ConfigurationError, "pool_size must be at least 1, got: #{pool_size}" if !pool_size.nil? && pool_size < 1
 
       if !keep_alive_timeout.nil? && keep_alive_timeout <= 0
         raise ConfigurationError, "keep_alive_timeout must be positive, got: #{keep_alive_timeout}"

data/lib/pinot/connection.rb

@@ -34,9 +34,7 @@ module Pinot
       @circuit_breaker_registry = circuit_breaker_registry
     end
 
-    def use_multistage_engine=(val)
-      @use_multistage_engine = val
-    end
+    attr_writer :use_multistage_engine
 
     def open_trace
       @trace = true
@@ -91,8 +89,6 @@ module Pinot
     def execute_sql_with_params(table, query_pattern, params, query_timeout_ms: nil, headers: {})
       query = format_query(query_pattern, params)
       execute_sql(table, query, query_timeout_ms: query_timeout_ms, headers: headers)
-    rescue => e
-      raise e
     end
 
     # Execute multiple queries in parallel and return results in the same order.
@@ -121,7 +117,7 @@ module Pinot
     def execute_many(queries, max_concurrency: nil)
       return [] if queries.empty?
 
-      results  = Array.new(queries.size)
+      results = Array.new(queries.size)
       # Queue acts as a counting semaphore: pre-filled with N tokens.
       sem = max_concurrency ? build_semaphore(max_concurrency) : nil
 
@@ -131,14 +127,14 @@ module Pinot
         timeout_ms = item[:query_timeout_ms] || item["query_timeout_ms"]
 
         Thread.new do
-          sem&.pop   # acquire
+          sem&.pop # acquire
           begin
             resp = execute_sql(table, query, query_timeout_ms: timeout_ms)
             results[idx] = QueryResult.new(table: table, query: query, response: resp, error: nil)
-          rescue => e
+          rescue StandardError => e
             results[idx] = QueryResult.new(table: table, query: query, response: nil, error: e)
           ensure
-            sem&.push(:token)  # release
+            sem&.push(:token) # release
           end
         end
       end
@@ -166,11 +162,42 @@ module Pinot
         @transport.http_client,
         broker,
         query,
-        page_size:     page_size,
+        page_size: page_size,
         extra_headers: extra_headers
       )
     end
 
+    # Check whether a broker is reachable and responding to queries.
+    #
+    # Runs a lightweight broker-side liveness check: first tries the dedicated
+    # +/health+ HTTP endpoint (returns 200 when the broker is healthy), and falls
+    # back to executing "SELECT 1 FROM DUAL" if the endpoint is unavailable.
+    #
+    # Returns +true+ when the broker responds successfully, +false+ on any
+    # error (connection refused, timeout, non-200 response, etc.). Never raises.
+    #
+    # Intended for Kubernetes readiness / liveness probes and health-check
+    # endpoints in Rails / Rack applications:
+    #
+    #   get "/healthz" do
+    #     conn.healthy? ? [200, "OK"] : [503, "Pinot unavailable"]
+    #   end
+    #
+    # @param table [String, nil] table used for broker selection (nil = any broker)
+    # @param timeout_ms [Integer] per-check timeout in ms (default 2000)
+    # @return [Boolean]
+    def healthy?(table: nil, timeout_ms: 2_000)
+      broker = @broker_selector.select_broker(table || "")
+      base   = broker.start_with?("http://", "https://") ? broker : "http://#{broker}"
+      client = HttpClient.new(timeout: timeout_ms / 1000.0)
+      resp   = client.get("#{base}/health", headers: {})
+      resp.code.to_i == 200
+    rescue StandardError
+      false
+    ensure
+      client&.close
+    end
+
     # Create a PreparedStatement from a query template with +?+ placeholders.
     #
     #   stmt = conn.prepare("myTable", "SELECT * FROM myTable WHERE id = ? AND name = ?")
@@ -185,8 +212,10 @@ module Pinot
     def prepare(table, query_template)
       raise ArgumentError, "table name cannot be empty" if table.nil? || table.strip.empty?
       raise ArgumentError, "query template cannot be empty" if query_template.nil? || query_template.strip.empty?
+
       count = query_template.count("?")
       raise ArgumentError, "query template must contain at least one parameter placeholder (?)" if count == 0
+
       PreparedStatementImpl.new(connection: self, table: table, query_template: query_template)
     end
 
@@ -196,12 +225,13 @@ module Pinot
       if placeholders != params.length
         raise "failed to format query: number of placeholders in queryPattern (#{placeholders}) does not match number of params (#{params.length})"
       end
+
       parts = pattern.split("?", -1)
       result = ""
       params.each_with_index do |param, i|
         formatted = begin
           format_arg(param)
-        rescue => e
+        rescue StandardError => e
           raise "failed to format query: failed to format parameter: #{e.message}"
         end
         result += parts[i] + formatted
@@ -213,11 +243,7 @@ module Pinot
       case value
       when String
         "'#{value.gsub("'", "''")}'"
-      when Integer
-        value.to_s
-      when Float
-        value.to_s
-      when TrueClass, FalseClass
+      when Integer, Float, TrueClass, FalseClass
         value.to_s
       when BigDecimal
         s = value.to_s("F")
@@ -239,9 +265,10 @@ module Pinot
       q
     end
 
-    def run_with_circuit_breaker(broker, &block)
+    def run_with_circuit_breaker(broker, &)
       return yield unless @circuit_breaker_registry
-      @circuit_breaker_registry.for(broker).call(broker, &block)
+
+      @circuit_breaker_registry.for(broker).call(broker, &)
     end
 
     def logger

data/lib/pinot/connection_factory.rb

@@ -138,7 +138,7 @@ module Pinot
 
     CircuitBreakerRegistry.new(
       failure_threshold: config.circuit_breaker_threshold || 5,
-      open_timeout:      config.circuit_breaker_timeout   || 30
+      open_timeout: config.circuit_breaker_timeout || 30
     )
   end
   private_class_method :build_circuit_breaker_registry

data/lib/pinot/controller_based_broker_selector.rb

@@ -4,7 +4,7 @@ require "json"
 
 module Pinot
   class ControllerBasedBrokerSelector < TableAwareBrokerSelector
-    CONTROLLER_API_PATH = "/v2/brokers/tables?state=ONLINE"
+    CONTROLLER_API_PATH = "/v2/brokers/tables?state=ONLINE".freeze
     DEFAULT_UPDATE_FREQ_MS = 1000
 
     def initialize(config, http_client = nil, logger: nil)
@@ -27,9 +27,8 @@ module Pinot
       addr = address.to_s
       if addr.include?("://")
         scheme = addr.split("://").first
-        unless %w[http https].include?(scheme)
-          raise ConfigurationError, "unsupported controller URL scheme: #{scheme}"
-        end
+        raise ConfigurationError, "unsupported controller URL scheme: #{scheme}" unless %w[http https].include?(scheme)
+
         addr.chomp("/") + CONTROLLER_API_PATH
       else
         "http://#{addr.chomp("/")}#{CONTROLLER_API_PATH}"
@@ -40,13 +39,11 @@ module Pinot
 
     def fetch_and_update
       headers = { "Accept" => "application/json" }
-        .merge(@config.extra_controller_api_headers || {})
+                  .merge(@config.extra_controller_api_headers || {})
 
       resp = @internal_http.get(@controller_url, headers: headers)
 
-      unless resp.code.to_i == 200
-        raise TransportError, "controller API returned HTTP status code #{resp.code}"
-      end
+      raise TransportError, "controller API returned HTTP status code #{resp.code}" unless resp.code.to_i == 200
 
       body = resp.body
       begin
@@ -70,7 +67,7 @@ module Pinot
           sleep interval
           begin
             fetch_and_update
-          rescue => e
+          rescue StandardError => e
             logger.warn "Pinot controller refresh failed: #{e.message}"
           end
         end

data/lib/pinot/grpc_transport.rb

@@ -47,7 +47,7 @@ module Pinot
       meta.merge!(@config.extra_metadata)
 
       Pinot::Broker::Grpc::BrokerRequest.new(
-        sql:      request.query,
+        sql: request.query,
         metadata: meta
       )
     end

data/lib/pinot/instrumentation.rb

@@ -1,45 +1,101 @@
 module Pinot
   # Low-level instrumentation hook that fires after every query executed via
   # Connection#execute_sql. This is the extension point used by
-  # Pinot::ActiveSupportNotifications and any custom observability layer.
+  # Pinot::ActiveSupportNotifications, Pinot::OpenTelemetry, and any custom
+  # observability layer.
   #
-  # Register a single callback:
+  # == Subscribing (multiple listeners supported)
   #
-  #   Pinot::Instrumentation.on_query = ->(event) do
+  #   listener = Pinot::Instrumentation.subscribe(->(event) do
   #     MyMetrics.record(event[:table], event[:duration_ms], event[:success])
+  #   end)
+  #
+  #   # Remove later:
+  #   Pinot::Instrumentation.unsubscribe(listener)
+  #
+  # == Legacy single-callback API (still supported)
+  #
+  #   Pinot::Instrumentation.on_query = ->(event) { ... }
+  #   Pinot::Instrumentation.on_query = nil  # remove
+  #
+  # == Around-execution hook (for OTel and similar span-based tools)
+  #
+  # The `around` hook wraps the entire query execution — the block yields the
+  # query, and the hook is responsible for calling Instrumentation.notify when
+  # done. Only one around hook can be registered at a time.
+  #
+  #   Pinot::Instrumentation.around = ->(table:, query:) do
+  #     MyTracer.in_span("pinot") { yield }
   #   end
   #
-  # The event Hash contains:
+  # == Event Hash keys
+  #
   #   :table        => String  — table name passed to execute_sql
   #   :query        => String  — SQL string
   #   :duration_ms  => Float   — wall-clock time in milliseconds
   #   :success      => Boolean — false when an exception was raised
   #   :error        => Exception or nil — the exception on failure, nil on success
-  #
-  # Only one callback can be registered at a time. Set on_query= to nil to remove it.
   module Instrumentation
+    @listeners = []
+    @around    = nil
+
+    # Add a post-execution listener. Returns the listener so it can be passed
+    # to unsubscribe later.
+    def self.subscribe(listener)
+      @listeners << listener
+      listener
+    end
+
+    # Remove a previously subscribed listener.
+    def self.unsubscribe(listener)
+      @listeners.delete(listener)
+    end
+
+    # Register an around-execution wrapper. Only one wrapper is supported;
+    # the new value replaces any previous one. Set to nil to remove.
+    def self.around=(wrapper)
+      @around = wrapper
+    end
+
+    def self.around
+      @around
+    end
+
+    # Legacy single-callback setter. Replaces all listeners with the given
+    # callback (or clears them when nil).
     def self.on_query=(callback)
-      @on_query = callback
+      @listeners = callback ? [callback] : []
     end
 
+    # Returns the first registered listener (legacy compat).
     def self.on_query
-      @on_query
+      @listeners.first
     end
 
     def self.instrument(table:, query:)
+      if @around
+        @around.call(table: table, query: query) { yield }
+      else
+        _timed_instrument(table: table, query: query) { yield }
+      end
+    end
+
+    # Fire all registered listeners with an event hash. Called by the default
+    # instrument path and by the OTel around wrapper.
+    def self.notify(event)
+      @listeners.each { |l| l.call(event) }
+    end
+
+    private_class_method def self._timed_instrument(table:, query:)
       start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       result = yield
       duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000
       notify(table: table, query: query, duration_ms: duration_ms, success: true, error: nil)
       result
-    rescue => e
+    rescue StandardError => e
       duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000
       notify(table: table, query: query, duration_ms: duration_ms, success: false, error: e)
       raise
     end
-
-    def self.notify(event)
-      @on_query&.call(event)
-    end
   end
 end

data/lib/pinot/open_telemetry.rb

@@ -0,0 +1,161 @@
+require "pinot"
+
+module Pinot
+  # Opt-in OpenTelemetry bridge.
+  #
+  # == Setup
+  #
+  # Add to an initializer after the opentelemetry SDK is configured:
+  #
+  #   require "pinot/open_telemetry"
+  #   Pinot::OpenTelemetry.install!
+  #
+  # == What it does
+  #
+  # Each call to Connection#execute_sql (and anything built on top of it —
+  # execute_sql_with_params, execute_many, PreparedStatement) creates an OTel
+  # span named "pinot.query" with attributes following the OpenTelemetry
+  # semantic conventions for database spans:
+  #
+  #   db.system        = "pinot"
+  #   db.statement     = "<sql>"        (the full SQL string)
+  #   db.name          = "<table>"      (the Pinot table name)
+  #   db.operation     = "SELECT"       (first token of the SQL)
+  #
+  # On failure the span is marked with error status and the exception is
+  # recorded on the span.
+  #
+  # == Trace-context propagation
+  #
+  # When installed, every outbound HTTP request to a broker is injected with
+  # W3C Trace Context headers (traceparent / tracestate) so distributed traces
+  # flow through Pinot. This relies on OpenTelemetry.propagation being
+  # configured (the default SDK sets this up automatically).
+  #
+  # == Feature flag
+  #
+  # The bridge can be toggled at runtime without reinstalling:
+  #
+  #   Pinot::OpenTelemetry.enabled = false   # pause tracing (e.g. in tests)
+  #   Pinot::OpenTelemetry.enabled = true    # resume
+  #   Pinot::OpenTelemetry.enabled?          # => true / false
+  #
+  # == Lifecycle
+  #
+  #   Pinot::OpenTelemetry.install!    # idempotent
+  #   Pinot::OpenTelemetry.installed?  # => true
+  #   Pinot::OpenTelemetry.uninstall!  # removes hooks; leaves transport unpatched
+  #
+  # Note: this gem does NOT depend on opentelemetry-api or opentelemetry-sdk.
+  # Both must be present and initialized before install! is called.
+  module OpenTelemetry
+    SPAN_NAME    = "pinot.query".freeze
+    DB_SYSTEM    = "pinot".freeze
+    TRACER_NAME  = "pinot-client".freeze
+
+    @installed = false
+    @enabled   = true
+
+    # Enable or disable tracing at runtime without uninstalling.
+    def self.enabled=(val)
+      @enabled = val ? true : false
+    end
+
+    def self.enabled?
+      @enabled
+    end
+
+    def self.install!
+      return if installed?
+
+      _install_around_hook
+      _patch_transport
+      @installed = true
+    end
+
+    def self.installed?
+      @installed
+    end
+
+    def self.uninstall!
+      ::Pinot::Instrumentation.around = nil
+      @installed = false
+      # NOTE: JsonHttpTransport prepend is permanent once applied (Ruby limitation).
+      # Disable the propagator by unsetting the flag — it no-ops when disabled.
+    end
+
+    # -------------------------------------------------------------------------
+    # Internal helpers
+    # -------------------------------------------------------------------------
+
+    def self._install_around_hook
+      ::Pinot::Instrumentation.around = method(:_around)
+    end
+    private_class_method :_install_around_hook
+
+    def self._around(table:, query:)
+      unless @enabled
+        # Bypass tracing; still time and notify listeners.
+        return ::Pinot::Instrumentation.send(:_timed_instrument, table: table, query: query) { yield }
+      end
+
+      tracer = ::OpenTelemetry.tracer_provider.tracer(TRACER_NAME, ::Pinot::VERSION)
+      attrs  = _span_attributes(table, query)
+
+      tracer.in_span(SPAN_NAME, attributes: attrs, kind: :client) do |span|
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        begin
+          result = yield
+          duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000
+          ::Pinot::Instrumentation.notify(
+            table: table, query: query, duration_ms: duration_ms, success: true, error: nil
+          )
+          result
+        rescue StandardError => e
+          duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000
+          span.record_exception(e)
+          span.status = ::OpenTelemetry::Trace::Status.error(e.message)
+          ::Pinot::Instrumentation.notify(
+            table: table, query: query, duration_ms: duration_ms, success: false, error: e
+          )
+          raise
+        end
+      end
+    end
+    private_class_method :_around
+
+    def self._span_attributes(table, query)
+      attrs = {
+        "db.system" => DB_SYSTEM,
+        "db.statement" => query,
+        "db.name" => table.to_s
+      }
+      op = query.to_s.lstrip.split(/\s+/, 2).first&.upcase
+      attrs["db.operation"] = op if op && !op.empty?
+      attrs
+    end
+    private_class_method :_span_attributes
+
+    # Patch JsonHttpTransport to inject W3C trace-context headers into every
+    # outbound HTTP request. Applied once via Module#prepend.
+    def self._patch_transport
+      return if ::Pinot::JsonHttpTransport.ancestors.include?(TraceContextInjector)
+
+      ::Pinot::JsonHttpTransport.prepend(TraceContextInjector)
+    end
+    private_class_method :_patch_transport
+
+    # Prepended into JsonHttpTransport. Injects traceparent/tracestate into
+    # request headers when the bridge is enabled and a current span exists.
+    module TraceContextInjector
+      def execute(broker_address, request, extra_request_headers: {})
+        otel = ::Pinot::OpenTelemetry
+        return super unless otel.installed? && otel.enabled?
+
+        carrier = {}
+        ::OpenTelemetry.propagation.inject(carrier)
+        super(broker_address, request, extra_request_headers: extra_request_headers.merge(carrier))
+      end
+    end
+  end
+end

data/lib/pinot/paginator.rb

@@ -53,7 +53,7 @@ module Pinot
       @extra_headers  = extra_headers
 
       @request_id  = nil
-      @cursor_base = nil  # "http://host:port" — set after first response
+      @cursor_base = nil # "http://host:port" — set after first response
       @exhausted   = false
     end
 
@@ -136,11 +136,13 @@ module Pinot
 
     def broker_base(address)
       return address if address.start_with?("http://", "https://")
+
       "http://#{address}"
     end
 
     def broker_base_from_response(resp)
       return nil unless resp.broker_host && resp.broker_port
+
       "http://#{resp.broker_host}:#{resp.broker_port}"
     end
 

data/lib/pinot/prepared_statement.rb

@@ -52,9 +52,8 @@ module Pinot
     def set(index, value)
       @mutex.synchronize do
         raise PreparedStatementClosedError, "prepared statement is closed" if @closed
-        unless index >= 1 && index <= @param_count
-          raise "parameter index #{index} is out of range [1, #{@param_count}]"
-        end
+        raise "parameter index #{index} is out of range [1, #{@param_count}]" unless index.between?(1, @param_count)
+
         @parameters[index - 1] = value
       end
       nil
@@ -63,13 +62,14 @@ module Pinot
     def execute(headers: {})
       @mutex.synchronize do
         raise PreparedStatementClosedError, "prepared statement is closed" if @closed
+
         @parameters.each_with_index do |p, i|
           raise "parameter at index #{i + 1} is not set" if p.nil?
         end
       end
       query = begin
         build_query(@parameters)
-      rescue => e
+      rescue StandardError => e
         raise "failed to build query: #{e.message}"
       end
       @connection.execute_sql(@table, query, headers: headers)
@@ -77,12 +77,11 @@ module Pinot
 
     def execute_with_params(*params, headers: {})
       @mutex.synchronize { raise PreparedStatementClosedError, "prepared statement is closed" if @closed }
-      if params.length != @param_count
-        raise "expected #{@param_count} parameters, got #{params.length}"
-      end
+      raise "expected #{@param_count} parameters, got #{params.length}" if params.length != @param_count
+
       query = begin
         build_query(params)
-      rescue => e
+      rescue StandardError => e
         raise "failed to build query: #{e.message}"
       end
       @connection.execute_sql(@table, query, headers: headers)
@@ -91,6 +90,7 @@ module Pinot
     def clear_parameters
       @mutex.synchronize do
         raise PreparedStatementClosedError, "prepared statement is closed" if @closed
+
         @parameters.fill(nil)
       end
       nil
@@ -105,14 +105,13 @@ module Pinot
     end
 
     def build_query(params)
-      if params.length != @param_count
-        raise "expected #{@param_count} parameters, got #{params.length}"
-      end
+      raise "expected #{@param_count} parameters, got #{params.length}" if params.length != @param_count
+
       result = ""
       params.each_with_index do |param, i|
         formatted = begin
           @connection.format_arg(param)
-        rescue => e
+        rescue StandardError => e
           raise "failed to format parameter: #{e.message}"
         end
         result += @parts[i] + formatted

data/lib/pinot/proto/broker_service_pb.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
+
 # Generated by the protocol buffer compiler.  DO NOT EDIT!
 # source: broker_service.proto
 
-require 'google/protobuf'
-
+require "google/protobuf"
 
 descriptor_data = "\n\x14\x62roker_service.proto\x12\x11pinot.broker.grpc\"\x8f\x01\n\rBrokerRequest\x12\x0b\n\x03sql\x18\x01 \x01(\t\x12@\n\x08metadata\x18\x02 \x03(\x0b\x32..pinot.broker.grpc.BrokerRequest.MetadataEntry\x1a/\n\rMetadataEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\":\n\x0e\x42rokerResponse\x12\x17\n\x0fresult_row_size\x18\x01 \x01(\x05\x12\x0f\n\x07payload\x18\x02 \x01(\x0c\x32m\n\x1cPinotClientGrpcBrokerService\x12M\n\x06Submit\x12 .pinot.broker.grpc.BrokerRequest\x1a!.pinot.broker.grpc.BrokerResponseb\x06proto3"
 
-pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool = Google::Protobuf::DescriptorPool.generated_pool
 pool.add_serialized_file(descriptor_data)
 
 module Pinot

data/lib/pinot/proto/broker_service_services_pb.rb

@@ -1,20 +1,19 @@
 # Generated by the protocol buffer compiler.  DO NOT EDIT!
 # Source: broker_service.proto for package 'pinot.broker.grpc'
 
-require 'grpc'
-require_relative 'broker_service_pb'
+require "grpc"
+require_relative "broker_service_pb"
 
 module Pinot
   module Broker
     module Grpc
       module PinotClientGrpcBrokerService
         class Service
-
           include ::GRPC::GenericService
 
           self.marshal_class_method = :encode
           self.unmarshal_class_method = :decode
-          self.service_name = 'pinot.broker.grpc.PinotClientGrpcBrokerService'
+          self.service_name = "pinot.broker.grpc.PinotClientGrpcBrokerService"
 
           rpc :Submit, ::Pinot::Broker::Grpc::BrokerRequest, ::Pinot::Broker::Grpc::BrokerResponse
         end

data/lib/pinot/response.rb

@@ -1,9 +1,9 @@
 require "bigdecimal"
 
 module Pinot
-  INT32_MAX =  2_147_483_647
+  INT32_MAX = 2_147_483_647
   INT32_MIN = -2_147_483_648
-  INT64_MAX =  9_223_372_036_854_775_807
+  INT64_MAX = 9_223_372_036_854_775_807
   INT64_MIN = -9_223_372_036_854_775_808
   FLOAT32_MAX = 3.4028235e+38
 
@@ -110,14 +110,20 @@ module Pinot
         if raw.include?(".") || raw.include?("e") || raw.include?("E")
           # Floating point string — check if it's a whole number
           bd = BigDecimal(raw)
-          return 0 if bd.infinite? || bd.nan? rescue return 0
+          begin
+            return 0 if bd.infinite? || bd.nan?
+          rescue StandardError
+            return 0
+          end
           int_val = bd.to_i
           return 0 unless bd == BigDecimal(int_val.to_s)
           return 0 if int_val > INT32_MAX || int_val < INT32_MIN
+
           int_val.to_i
         else
           int_val = Integer(raw)
           return 0 if int_val > INT32_MAX || int_val < INT32_MIN
+
           int_val
         end
       rescue ArgumentError, TypeError
@@ -133,16 +139,21 @@ module Pinot
       begin
         if raw.include?(".") || raw.include?("e") || raw.include?("E")
           bd = BigDecimal(raw)
-          return 0 if bd.infinite? || bd.nan? rescue return 0
+          begin
+            return 0 if bd.infinite? || bd.nan?
+          rescue StandardError
+            return 0
+          end
           int_val = bd.to_i
           return 0 unless bd == BigDecimal(int_val.to_s)
-          return 0 if int_val > INT64_MAX || int_val < INT64_MIN
-          int_val
+
         else
           int_val = Integer(raw)
-          return 0 if int_val > INT64_MAX || int_val < INT64_MIN
-          int_val
+
         end
+        return 0 if int_val > INT64_MAX || int_val < INT64_MIN
+
+        int_val
       rescue ArgumentError, TypeError
         0
       end
@@ -156,8 +167,10 @@ module Pinot
       begin
         f = Float(raw)
         return 0.0 if f.infinite? || f.nan?
+
         f32 = f.to_f
         return 0.0 if f32.abs > FLOAT32_MAX
+
         f32
       rescue ArgumentError, TypeError
         0.0
@@ -172,6 +185,7 @@ module Pinot
       begin
         f = Float(raw)
         return 0.0 if f.infinite? || f.nan?
+
         f
       rescue ArgumentError, TypeError
         0.0

data/lib/pinot/simple_broker_selector.rb

@@ -14,6 +14,7 @@ module Pinot
 
     def select_broker(_table)
       raise BrokerNotFoundError, "no pre-configured broker lists" if @broker_list.empty?
+
       @mutex.synchronize do
         broker = @broker_list[@index % @broker_list.size]
         @index += 1

data/lib/pinot/table_aware_broker_selector.rb

@@ -2,8 +2,8 @@ module Pinot
   class TableAwareBrokerSelector
     include BrokerSelector
 
-    OFFLINE_SUFFIX  = "_OFFLINE"
-    REALTIME_SUFFIX = "_REALTIME"
+    OFFLINE_SUFFIX  = "_OFFLINE".freeze
+    REALTIME_SUFFIX = "_REALTIME".freeze
 
     def initialize
       @mutex = Mutex.new
@@ -20,11 +20,13 @@ module Pinot
       @mutex.synchronize do
         if table_name.empty?
           raise BrokerNotFoundError, "no available broker" if @all_broker_list.empty?
+
           return @all_broker_list.sample
         end
         brokers = @table_broker_map[table_name]
         raise TableNotFoundError, "unable to find table: #{table}" unless brokers
         raise BrokerNotFoundError, "no available broker for table: #{table}" if brokers.empty?
+
         brokers.sample
       end
     end

data/lib/pinot/transport.rb

@@ -50,10 +50,18 @@ module Pinot
     end
 
     def close
-      @reaper.kill rescue nil
+      begin
+        @reaper.kill
+      rescue StandardError
+        nil
+      end
       @pool_mutex.synchronize do
         @pool.each_value do |entries|
-          entries.each { |entry| entry.http.finish rescue nil }
+          entries.each do |entry|
+            entry.http.finish
+          rescue StandardError
+            nil
+          end
         end
         @pool.clear
       end
@@ -69,8 +77,12 @@ module Pinot
         result = yield http
         checkin(key, http)
         result
-      rescue => e
-        http.finish rescue nil
+      rescue StandardError => e
+        begin
+          http.finish
+        rescue StandardError
+          nil
+        end
         raise e
       end
     end
@@ -85,7 +97,11 @@ module Pinot
             fresh = entry.http
             break
           else
-            entry.http.finish rescue nil
+            begin
+              entry.http.finish
+            rescue StandardError
+              nil
+            end
           end
         end
         fresh
@@ -99,7 +115,11 @@ module Pinot
         if pool_for_key.size < @max_pool_size
           pool_for_key.push(PoolEntry.new(http, Process.clock_gettime(Process::CLOCK_MONOTONIC)))
         else
-          http.finish rescue nil
+          begin
+            http.finish
+          rescue StandardError
+            nil
+          end
         end
       end
     end
@@ -121,7 +141,11 @@ module Pinot
         @pool.each_value do |entries|
           entries.reject! do |entry|
             if now - entry.checked_in_at >= @keep_alive_timeout
-              entry.http.finish rescue nil
+              begin
+                entry.http.finish
+              rescue StandardError
+                nil
+              end
               true
             else
               false
@@ -156,11 +180,11 @@ module Pinot
             http.cert = OpenSSL::X509::Certificate.new(File.read(@tls_config.client_cert_file))
             http.key = OpenSSL::PKey.read(File.read(@tls_config.client_key_file))
           end
-          if @tls_config.insecure_skip_verify
-            http.verify_mode = OpenSSL::SSL::VERIFY_NONE
-          else
-            http.verify_mode = OpenSSL::SSL::VERIFY_PEER
-          end
+          http.verify_mode = if @tls_config.insecure_skip_verify
+                               OpenSSL::SSL::VERIFY_NONE
+                             else
+                               OpenSSL::SSL::VERIFY_PEER
+                             end
         end
       else
         http.use_ssl = false
@@ -216,9 +240,9 @@ module Pinot
         url = build_url(broker_address, request.query_format)
         body = build_body(request)
         headers = DEFAULT_HEADERS
-          .merge(@extra_headers)
-          .merge("X-Correlation-Id" => SecureRandom.uuid)
-          .merge(extra_request_headers)
+                    .merge(@extra_headers)
+                    .merge("X-Correlation-Id" => SecureRandom.uuid)
+                    .merge(extra_request_headers)
 
         resp = @http_client.post(url, body: body, headers: headers)
 
@@ -245,11 +269,11 @@ module Pinot
         broker_response
       rescue *RETRYABLE_HTTP_ERRORS, *RETRYABLE_ERRORS => e
         if attempts < max_attempts
-          sleep_ms = (@retry_interval_ms || 200) * (2 ** (attempts - 1))
+          sleep_ms = (@retry_interval_ms || 200) * (2**(attempts - 1))
           sleep(sleep_ms / 1000.0)
           retry
         end
-        raise Net::ReadTimeout === e || Net::WriteTimeout === e ? QueryTimeoutError.new(e.message) : e
+        raise(Net::ReadTimeout === e || Net::WriteTimeout === e ? QueryTimeoutError.new(e.message) : e)
       end
     end
 
@@ -282,9 +306,7 @@ module Pinot
       if request.query_format == "sql"
         parts << "groupByMode=sql;responseFormat=sql"
         parts << "useMultistageEngine=true" if request.use_multistage_engine
-        if @timeout_ms && @timeout_ms > 0
-          parts << "timeoutMs=#{@timeout_ms}"
-        end
+        parts << "timeoutMs=#{@timeout_ms}" if @timeout_ms && @timeout_ms > 0
         parts << "timeoutMs=#{request.query_timeout_ms}" if request.query_timeout_ms
       end
       parts.join(";")

data/lib/pinot/version.rb

@@ -1,3 +1,3 @@
 module Pinot
-  VERSION = "1.27.0"
+  VERSION = "1.29.0".freeze
 end

data/lib/pinot/zookeeper_broker_selector.rb

@@ -1,12 +1,11 @@
 require "json"
-require "set"
 require_relative "table_aware_broker_selector"
 require_relative "errors"
 
 module Pinot
   class ZookeeperBrokerSelector < TableAwareBrokerSelector
     # ZK path where Pinot stores broker external view
-    BROKER_EXTERNAL_VIEW_PATH = "/EXTERNALVIEW/brokerResource"
+    BROKER_EXTERNAL_VIEW_PATH = "/EXTERNALVIEW/brokerResource".freeze
 
     def initialize(zk_path:, zk_client: nil)
       super()
@@ -39,9 +38,13 @@ module Pinot
     end
 
     def setup_watcher
-      @zk.register(BROKER_EXTERNAL_VIEW_PATH) do |event|
-        fetch_and_update rescue nil
-        setup_watcher  # re-register watch after each trigger
+      @zk.register(BROKER_EXTERNAL_VIEW_PATH) do |_event|
+        begin
+          fetch_and_update
+        rescue StandardError
+          nil
+        end
+        setup_watcher # re-register watch after each trigger
       end
       # Set initial watch
       @zk.exists?(BROKER_EXTERNAL_VIEW_PATH, watch: true)
@@ -61,12 +64,15 @@ module Pinot
         brokers = []
         broker_map.each do |broker_key, state|
           next unless state == "ONLINE"
+
           # Broker key format: Broker_<hostname>_<port>
           # Use the last segment as port and the second-to-last as host
           parts = broker_key.split("_")
           next if parts.length < 2
+
           port = parts.last
           next unless port =~ /\A\d+\z/
+
           host = parts[-2]
           brokers << "#{host}:#{port}"
         end

data/lib/pinot.rb

@@ -34,5 +34,5 @@ end
 
 begin
   require_relative "pinot/zookeeper_broker_selector"
-rescue LoadError
+rescue LoadError # rubocop:disable Lint/SuppressedException
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pinot-client
 version: !ruby/object:Gem::Version
-  version: 1.27.0
+  version: 1.29.0
 platform: ruby
 authors:
 - Xiang Fu
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-19 00:00:00.000000000 Z
+date: 2026-04-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger
@@ -94,6 +94,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 description: A Ruby client for Apache Pinot, mirroring the Go client API
 email:
 executables: []
@@ -116,6 +144,7 @@ files:
 - lib/pinot/grpc_transport.rb
 - lib/pinot/instrumentation.rb
 - lib/pinot/logger.rb
+- lib/pinot/open_telemetry.rb
 - lib/pinot/paginator.rb
 - lib/pinot/prepared_statement.rb
 - lib/pinot/proto/broker_service.proto