pinot-client 1.28.0 → 1.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da3d726029acb7167db3fef1a14951e4f4c46beac51f32e88e1e7782eab64fa1
-  data.tar.gz: 4271e56a42a4d269bdf8de68a4c631e8320ec2eec4a36deeb3b635e10e8dc933
+  metadata.gz: cf947863b8d33ffa5c029bdd62e51f3451b76320a0b5f46c1d48ba8994827767
+  data.tar.gz: 433c4df6222017a3e32069410e550146ffa249ba6b34c9cb12bbd49b89933191
 SHA512:
-  metadata.gz: ef69651b14484fceeec26edca916ede91f04ea3224f24d449e2cf022a3bb847e9ca0d429908daad14e10daa72c9bd4719f4e2400dff06431dca1c6126c90bd7e
-  data.tar.gz: 8ab20c872830e2387245fadebae91e2739b5e30eb959a9769346df4652e0a3e18d673da2e6a3f88ae5753e55e41e7ed21ae709827d920e338e569444ba4a878a
+  metadata.gz: ada0f4344c5482daafefdf4cb062e80601723119b2732df5d5e116d1247931076db9eed6f3c393e6af3befcde14dedaac66a7a1fa90e7a0a6e8a65ce81e4eab0
+  data.tar.gz: fe0699c5d2fe75b1cb0aeeb832dcb57eb8b7fe44e33801171c76a7006e99cee08f34476134d1e87e2dccce8695a8dfc4b7b642436c5faebbe60246c3cbebd627

data/lib/pinot/active_support_notifications.rb

@@ -43,7 +43,7 @@ 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?
@@ -64,10 +64,10 @@ module Pinot
 
     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

@@ -92,7 +92,7 @@ module Pinot
       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

data/lib/pinot/open_telemetry.rb

@@ -49,9 +49,9 @@ module Pinot
   # 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"
-    DB_SYSTEM    = "pinot"
-    TRACER_NAME  = "pinot-client"
+    SPAN_NAME    = "pinot.query".freeze
+    DB_SYSTEM    = "pinot".freeze
+    TRACER_NAME  = "pinot-client".freeze
 
     @installed = false
     @enabled   = true
@@ -80,7 +80,7 @@ module Pinot
     def self.uninstall!
       ::Pinot::Instrumentation.around = nil
       @installed = false
-      # Note: JsonHttpTransport prepend is permanent once applied (Ruby limitation).
+      # NOTE: JsonHttpTransport prepend is permanent once applied (Ruby limitation).
       # Disable the propagator by unsetting the flag — it no-ops when disabled.
     end
 
@@ -111,7 +111,7 @@ module Pinot
             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
           span.record_exception(e)
           span.status = ::OpenTelemetry::Trace::Status.error(e.message)
@@ -126,9 +126,9 @@ module Pinot
 
     def self._span_attributes(table, query)
       attrs = {
-        "db.system"    => DB_SYSTEM,
+        "db.system" => DB_SYSTEM,
         "db.statement" => query,
-        "db.name"      => table.to_s
+        "db.name" => table.to_s
       }
       op = query.to_s.lstrip.split(/\s+/, 2).first&.upcase
       attrs["db.operation"] = op if op && !op.empty?
@@ -140,6 +140,7 @@ module Pinot
     # 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

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/railtie.rb

@@ -0,0 +1,105 @@
+require "pinot"
+require "pinot/active_support_notifications"
+
+module Pinot
+  # Rails integration via Railtie — zero configuration required.
+  #
+  # Automatically activated when the gem is required inside a Rails app.
+  # Just add `gem "pinot-client"` to your Gemfile.
+  #
+  # == What it does
+  #
+  # 1. **ActiveSupport::Notifications bridge** — every Pinot query fires a
+  #    "sql.pinot" event on the AS::N bus, picked up by Rails log subscribers,
+  #    Skylight, Scout APM, etc.
+  #
+  # 2. **OpenTelemetry bridge** — when the opentelemetry-api gem is present,
+  #    creates "pinot.query" spans and injects W3C trace-context headers into
+  #    every outbound broker request.
+  #
+  # 3. **X-Request-Id propagation** — inserts Pinot::RequestIdMiddleware into
+  #    the Rack stack. The current request's X-Request-Id is forwarded as an
+  #    HTTP header on every broker call so Pinot broker logs can be correlated
+  #    with application request logs.
+  #
+  # == Opting out of individual features
+  #
+  #   # config/initializers/pinot.rb
+  #   Rails.application.config.pinot.notifications  = false
+  #   Rails.application.config.pinot.open_telemetry = false
+  #   Rails.application.config.pinot.request_id     = false
+  #
+  # == Manual setup (non-Rails / opt-out of Railtie entirely)
+  #
+  #   require "pinot/active_support_notifications"
+  #   Pinot::ActiveSupportNotifications.install!
+  #
+  #   require "pinot/open_telemetry"
+  #   Pinot::OpenTelemetry.install!
+  #
+  #   # In your Rack middleware stack:
+  #   use Pinot::RequestIdMiddleware
+  class Railtie < ::Rails::Railtie
+    initializer "pinot.install_notifications" do |app|
+      opts = app.config.pinot
+      next if opts[:notifications] == false
+
+      require "pinot/active_support_notifications"
+      ActiveSupportNotifications.install!
+    end
+
+    initializer "pinot.install_open_telemetry" do |app|
+      opts = app.config.pinot
+      next if opts[:open_telemetry] == false
+
+      begin
+        require "opentelemetry"
+        require "pinot/open_telemetry"
+        OpenTelemetry.install!
+      rescue LoadError
+        # opentelemetry-api gem not present — skip silently
+      end
+    end
+
+    initializer "pinot.request_id_propagation" do |app|
+      opts = app.config.pinot
+      next if opts[:request_id] == false
+
+      app.config.middleware.use(RequestIdMiddleware)
+      Connection.prepend(RequestIdInjector)
+    end
+  end
+
+  # Rack middleware that captures X-Request-Id from the inbound HTTP request
+  # and stores it in a thread-local for the duration of the request.
+  #
+  # Inserted automatically by Pinot::Railtie. For non-Rails Rack apps:
+  #
+  #   use Pinot::RequestIdMiddleware
+  class RequestIdMiddleware
+    RACK_HEADER = "HTTP_X_REQUEST_ID".freeze
+
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      Thread.current[:pinot_request_id] = env[RACK_HEADER]
+      @app.call(env)
+    ensure
+      Thread.current[:pinot_request_id] = nil
+    end
+  end
+
+  # Prepended into Connection when the Railtie is active.
+  # Automatically merges the current request's X-Request-Id into every
+  # outbound Pinot query as an HTTP header, without requiring callers to
+  # pass it explicitly.
+  module RequestIdInjector
+    def execute_sql(table, query, query_timeout_ms: nil, headers: {})
+      rid = Thread.current[:pinot_request_id]
+      merged = rid && !headers.key?("X-Request-Id") ? headers.merge("X-Request-Id" => rid) : headers
+      super(table, query, query_timeout_ms: query_timeout_ms, headers: merged)
+    end
+  end
+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,17 @@ 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
+          return 0 if bd.infinite? || bd.nan?
+
           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 +136,18 @@ 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
+          return 0 if bd.infinite? || bd.nan?
+
           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 +161,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 +179,7 @@ module Pinot
       begin
         f = Float(raw)
         return 0.0 if f.infinite? || f.nan?
+
         f
       rescue ArgumentError, TypeError
         0.0

data/lib/pinot/schema_client.rb

@@ -0,0 +1,122 @@
+require "net/http"
+require "uri"
+require "json"
+
+module Pinot
+  # Thin client for the Pinot Controller REST API — table listing and schema
+  # introspection. Useful for tooling, migrations, and debugging column types.
+  #
+  # == Usage
+  #
+  #   client = Pinot::SchemaClient.new("http://controller:9000")
+  #
+  #   client.list_tables                      # => ["baseballStats", "orders", ...]
+  #   client.get_schema("baseballStats")      # => Hash (raw schema JSON)
+  #   client.get_table_config("baseballStats")# => Hash (raw tableConfig JSON)
+  #   client.table_exists?("orders")          # => true / false
+  #
+  # == Authentication / extra headers
+  #
+  #   client = Pinot::SchemaClient.new(
+  #     "https://controller:9000",
+  #     headers: { "Authorization" => "Bearer <token>" }
+  #   )
+  #
+  # The client is intentionally stateless and lightweight — it uses a shared
+  # HttpClient (connection pool) but does not perform background polling.
+  class SchemaClient
+    TABLES_PATH      = "/tables".freeze
+    SCHEMA_PATH      = "/schemas/%<table>s".freeze
+    TABLE_CONFIG_PATH = "/tables/%<table>s".freeze
+
+    # @param controller_address [String] base URL e.g. "controller:9000" or
+    #   "http://controller:9000" or "https://controller:9000"
+    # @param headers [Hash] extra HTTP headers for every request
+    # @param http_client [HttpClient, nil] optional pre-configured client
+    def initialize(controller_address, headers: {}, http_client: nil)
+      @base    = normalize_address(controller_address)
+      @headers = { "Accept" => "application/json" }.merge(headers)
+      @http    = http_client || HttpClient.new
+    end
+
+    # Returns an array of all table names known to the controller.
+    #
+    # @return [Array<String>]
+    def list_tables
+      body = get_json(TABLES_PATH)
+      body["tables"] || []
+    end
+
+    # Returns the schema for a table as a Hash.
+    #
+    # @param table [String] table name (without _OFFLINE / _REALTIME suffix)
+    # @return [Hash] raw schema JSON
+    # @raise [TableNotFoundError] if the table or schema does not exist (404)
+    # @raise [TransportError] on other non-200 responses
+    def get_schema(table)
+      get_json(format(SCHEMA_PATH, table: table))
+    end
+
+    # Returns the full table config (including segmentsConfig, tableIndexConfig,
+    # tenants, etc.) for a table as a Hash.
+    #
+    # @param table [String] table name (without _OFFLINE / _REALTIME suffix)
+    # @return [Hash] raw tableConfig JSON
+    # @raise [TableNotFoundError] if the table does not exist (404)
+    # @raise [TransportError] on other non-200 responses
+    def get_table_config(table)
+      get_json(format(TABLE_CONFIG_PATH, table: table))
+    end
+
+    # Returns true when the controller knows about the given table.
+    #
+    # @param table [String]
+    # @return [Boolean]
+    def table_exists?(table)
+      get_table_config(table)
+      true
+    rescue TableNotFoundError
+      false
+    end
+
+    # Returns the column names and their data types for a table.
+    #
+    # Convenience wrapper around get_schema that returns a flat Hash:
+    #   { "playerId" => "INT", "playerName" => "STRING", ... }
+    #
+    # @param table [String]
+    # @return [Hash{String => String}]
+    def column_types(table)
+      schema = get_schema(table)
+      dims   = schema["dimensionFieldSpecs"] || []
+      metrics = schema["metricFieldSpecs"] || []
+      date_time = schema["dateTimeFieldSpecs"] || []
+      (dims + metrics + date_time).to_h do |spec|
+        [spec["name"], spec["dataType"]]
+      end
+    end
+
+    private
+
+    def normalize_address(address)
+      addr = address.to_s.chomp("/")
+      addr.start_with?("http://", "https://") ? addr : "http://#{addr}"
+    end
+
+    def get_json(path)
+      url  = "#{@base}#{path}"
+      resp = @http.get(url, headers: @headers)
+
+      case resp.code.to_i
+      when 200
+        JSON.parse(resp.body)
+      when 404
+        raise TableNotFoundError, "not found: #{path}"
+      else
+        raise TransportError, "controller returned HTTP #{resp.code} for #{path}"
+      end
+    rescue JSON::ParserError => e
+      raise TransportError, "invalid JSON from controller: #{e.message}"
+    end
+  end
+end

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.28.0"
+  VERSION = "1.30.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

@@ -24,6 +24,7 @@ require_relative "pinot/paginator"
 require_relative "pinot/connection"
 require_relative "pinot/prepared_statement"
 require_relative "pinot/connection_factory"
+require_relative "pinot/schema_client"
 
 require_relative "pinot/grpc_config"
 begin
@@ -34,5 +35,7 @@ end
 
 begin
   require_relative "pinot/zookeeper_broker_selector"
-rescue LoadError
+rescue LoadError # rubocop:disable Lint/SuppressedException
 end
+
+require_relative "pinot/railtie" if defined?(Rails::Railtie)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pinot-client
 version: !ruby/object:Gem::Version
-  version: 1.28.0
+  version: 1.30.0
 platform: ruby
 authors:
 - Xiang Fu
@@ -94,6 +94,48 @@ 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'
+- !ruby/object:Gem::Dependency
+  name: bundler-audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: A Ruby client for Apache Pinot, mirroring the Go client API
 email:
 executables: []
@@ -123,8 +165,10 @@ files:
 - lib/pinot/proto/broker_service_pb.rb
 - lib/pinot/proto/broker_service_services_pb.rb
 - lib/pinot/query_result.rb
+- lib/pinot/railtie.rb
 - lib/pinot/request.rb
 - lib/pinot/response.rb
+- lib/pinot/schema_client.rb
 - lib/pinot/simple_broker_selector.rb
 - lib/pinot/table_aware_broker_selector.rb
 - lib/pinot/tls_config.rb