pinot-client 1.29.0 → 1.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f728a6fe054a729893524d1da24e6ab2cddabda2d17c3bfae183e77271a70b1c
-  data.tar.gz: 6f10e6f81f725d9e34ed0d68a3ed04070244308f949a7a01533f90940fff18a9
+  metadata.gz: cf947863b8d33ffa5c029bdd62e51f3451b76320a0b5f46c1d48ba8994827767
+  data.tar.gz: 433c4df6222017a3e32069410e550146ffa249ba6b34c9cb12bbd49b89933191
 SHA512:
-  metadata.gz: 26d0a240f8d335f1acf02363ab974bf8e0323c3ddc045b2c9539340468231d68c6fe6c1c8517e0fb8a79ad4b154bd8178847e890d8475280200b33f327fcb467
-  data.tar.gz: 987c72674f5902f79365ff493ff541299e0efcc13374016bee1c52b98018734ff50498d7991c08807f50c5e0b70aff2be734eaa564ba7aa640da6530e66b4665
+  metadata.gz: ada0f4344c5482daafefdf4cb062e80601723119b2732df5d5e116d1247931076db9eed6f3c393e6af3befcde14dedaac66a7a1fa90e7a0a6e8a65ce81e4eab0
+  data.tar.gz: fe0699c5d2fe75b1cb0aeeb832dcb57eb8b7fe44e33801171c76a7006e99cee08f34476134d1e87e2dccce8695a8dfc4b7b642436c5faebbe60246c3cbebd627

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

@@ -110,11 +110,8 @@ module Pinot
         if raw.include?(".") || raw.include?("e") || raw.include?("E")
           # Floating point string — check if it's a whole number
           bd = BigDecimal(raw)
-          begin
-            return 0 if bd.infinite? || bd.nan?
-          rescue StandardError
-            return 0
-          end
+          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
@@ -139,11 +136,8 @@ module Pinot
       begin
         if raw.include?(".") || raw.include?("e") || raw.include?("E")
           bd = BigDecimal(raw)
-          begin
-            return 0 if bd.infinite? || bd.nan?
-          rescue StandardError
-            return 0
-          end
+          return 0 if bd.infinite? || bd.nan?
+
           int_val = bd.to_i
           return 0 unless bd == BigDecimal(int_val.to_s)
 

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

@@ -1,3 +1,3 @@
 module Pinot
-  VERSION = "1.29.0".freeze
+  VERSION = "1.30.0".freeze
 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
@@ -36,3 +37,5 @@ begin
   require_relative "pinot/zookeeper_broker_selector"
 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.29.0
+  version: 1.30.0
 platform: ruby
 authors:
 - Xiang Fu
@@ -122,6 +122,20 @@ dependencies:
     - - "~>"
       - !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: []
@@ -151,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