click_house-client 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20e1cebe2da3ec70c0a9ab7be6e5e53d2f2462b4787fd7e7389adfdbe4c64ea9
-  data.tar.gz: 0bdebe100594f4025f53a5c28723ef776d10ff327283166f70c9990a3323bb62
+  metadata.gz: 5513d15d8bf17295cf98d021b30650f46d0101a6d828b2620499f87a949f2e3d
+  data.tar.gz: 27fd28cc07d8b67d8de72031de4e3c7e343cef51a3230afd96ba0adf3d24c252
 SHA512:
-  metadata.gz: 58e7ed6985feda6a89dd33a1eac938509d3515016eea6c92ea38621c327a94d6e997dd166d67b3b7a2ddd1350edee0e3997055301159c01e8b0e3cac75531707
-  data.tar.gz: fd25cb3026f5be1d693181cbab8c13915abdad23ac0acd31e4d098b4477c35d6ef99e010e3e4c1477eb00b729bbdaecc5d4a2b40f36d1a35d147f4cdd6f1402f
+  metadata.gz: b3d7bf7328dd7ab42b004e3e35e58c35b4869267e4a2e701f7d29f963c2c445c3d63f0bbd5e45db679cc4d2fda6880ef367aff18e0a04b1a030f54ede2317ead
+  data.tar.gz: 40125fc9d75f13be2f1230ea872b72c6d01e797384674064d3fb42c613d1792c827e58d6ccfcd894b783ff4d89b838c04e9f50b2e297f4b085bba5c33b95585e

data/README.md

@@ -1,6 +1,6 @@
 # ClickHouse::Client
 
-This Gem provides a simple way to query ClickHouse databases using the HTTP interface. 
+This Gem provides a simple way to query ClickHouse databases using the HTTP interface.
 
 ## Example usage
 
@@ -61,6 +61,21 @@ puts ClickHouse::Client.execute('CREATE TABLE IF NOT EXISTS t1 (id Int64) ENGINE
 puts ClickHouse::Client.execute('DROP TABLE IF EXISTS t1', :main)
 ```
 
+## Custom typecasters
+
+Values returned by `ClickHouse::Client.select` are typecast based on the column type using built-in typecasters (integers, floats, dates, datetimes, intervals). You can register custom typecasters which take precedence over the built-in ones:
+
+```ruby
+ClickHouse::Client.configure do |config|
+  # Parse the value of `*_json` String columns as JSON
+  config.register_typecaster('String', ->(meta, value) do
+    meta['name'].match?(/\w+_json\z/) ? JSON.parse(value) : value
+  end)
+end
+```
+
+The first argument is the column type: either a `String` for an exact match or a `Regexp` (for example `/\AU?Int\d+\z/`). Wrapper types such as `Nullable(...)`, `LowCardinality(...)` and `SimpleAggregateFunction(...)` are unwrapped before matching. The typecaster receives the column metadata Hash (for example `{ 'name' => 'title', 'type' => 'String' }`) and the raw value. It should handle its own edge cases (for example malformed JSON). `NULL` values are returned as `nil` without invoking any typecaster.
+
 ## ClickHouse::Client::QueryBuilder
 
 The QueryBuilder provides an ActiveRecord-like interface for constructing ClickHouse queries programmatically. While similar to ActiveRecord's query interface, it has been tailored specifically for ClickHouse's SQL dialect and features.
@@ -182,6 +197,24 @@ query
 # => "SELECT * FROM `users` WHERE `users`.`active` = 'true' GROUP BY `users`.`department` HAVING `users`.`avg_salary` > 50000"
 ```
 
+### Reversing Order
+
+The `reverse_order` method inverts the direction of all `ORDER BY` clauses (`ASC` becomes `DESC` and vice versa).
+
+```ruby
+query.order(:name, :desc).order(:id).reverse_order.to_sql
+# => "SELECT * FROM `users` ORDER BY `users`.`name` ASC, `users`.`id` DESC"
+```
+
+### Empty Result Set
+
+Use `.none` to get a query that yields no rows. It appends an always-false `1 = 0` condition to the `WHERE` clause and stays chainable with other query builder methods:
+
+```ruby
+query.none.where(active: true).to_sql
+# => "SELECT * FROM `users` WHERE 1 = 0 AND `users`.`active` = 'true'"
+```
+
 ### FINAL Modifier
 
 ClickHouse's `FINAL` modifier forces merging of rows during query time for tables in the MergeTree family. Apply it via `.final`:
@@ -260,6 +293,30 @@ query_builder.with(inner.as_cte(:a)).with(inner.as_cte(:b)).to_sql
 (build it via `#as_cte`), and raises if the same CTE name is declared more than
 once.
 
+### UNION
+
+Use `#union` to combine the result sets of two or more queries. The combined
+queries are wrapped as an aliased subquery, so further chaining (`where`,
+`order`, `limit`, ...) applies to the outer `SELECT`.
+
+```ruby
+query1 = ClickHouse::Client::QueryBuilder.new('users_2023').select(:id)
+query2 = ClickHouse::Client::QueryBuilder.new('users_2024').select(:id)
+
+query1.union(query2).to_sql
+# => "SELECT * FROM ( SELECT `users_2023`.`id` FROM `users_2023` UNION DISTINCT SELECT `users_2024`.`id` FROM `users_2024` ) `union_subquery`"
+
+# UNION ALL with a custom subquery alias, chaining on the union result
+query1.union(query2, type: :all, alias_name: 'users').where(id: [1, 2]).to_sql
+# => "SELECT * FROM ( ... UNION ALL ... ) `users` WHERE `users`.`id` IN (1, 2)"
+
+# More than two queries can be combined in a single call
+query1.union(query2, query3, type: :all)
+```
+
+`#union` returns a new `QueryBuilder` (immutable) and raises if given anything
+other than `QueryBuilder` instances or an unknown `type`.
+
 ### Complete Example
 
 Here's a comprehensive example combining multiple QueryBuilder features:
@@ -287,12 +344,12 @@ result = ClickHouse::Client::QueryBuilder.new('users')
   .limit(10)
 
 puts result.to_sql
-"SELECT `users`.`department`, COUNT(*) AS user_count FROM `users` WHERE `users`.`active` = 'true' 
-AND `users`.`department` IN ('Sales', 'Marketing', 'Engineering') 
-AND `users`.`id` IN (SELECT `orders`.`user_id` FROM `orders` WHERE `orders`.`status` = 'completed' 
-AND `users`.`created_at` > '2025-08-12') 
-AND `users`.`email` ILIKE '%@company.com' 
-GROUP BY department HAVING COUNT(*) AS user_count > 5 
+"SELECT `users`.`department`, COUNT(*) AS user_count FROM `users` WHERE `users`.`active` = 'true'
+AND `users`.`department` IN ('Sales', 'Marketing', 'Engineering')
+AND `users`.`id` IN (SELECT `orders`.`user_id` FROM `orders` WHERE `orders`.`status` = 'completed'
+AND `users`.`created_at` > '2025-08-12')
+AND `users`.`email` ILIKE '%@company.com'
+GROUP BY department HAVING COUNT(*) AS user_count > 5
 ORDER BY user_count DESC LIMIT 10"
 ```
 

data/lib/click_house/client/arel_visitor.rb

@@ -30,6 +30,11 @@ module ClickHouse
         end
       end
 
+      # ClickHouse rejects a bare `UNION`; the mode must be explicit.
+      def visit_Arel_Nodes_Union(object, collector)
+        infix_value_with_paren(object, collector, " UNION DISTINCT ")
+      end
+
       def visit_ClickHouse_Client_ArelExtensions_Nodes_Final(object, collector)
         collector = visit(object.expr, collector)
         collector << " FINAL"

data/lib/click_house/client/configuration.rb

@@ -21,6 +21,12 @@ module ClickHouse
       # *logger*: object for receiving logger commands. Default `$stdout`
       # *log_proc*: any output (e.g. structure) to wrap around the query for every statement
       #
+      # *register_typecaster* (method): registers a custom typecaster for a column type,
+      #   taking precedence over the built-in typecasters. Arguments:
+      #   - type: column type as a String (exact match) or a Regexp
+      #   - typecaster: a callable object receiving the column metadata Hash
+      #     (e.g. { 'name' => 'title', 'type' => 'String' }) and the raw value
+      #
       # Example:
       #
       # ClickHouse::Client.configure do |c|
@@ -51,12 +57,17 @@ module ClickHouse
       #   end
       #
       #   c.json_parser = JSON
+      #
+      #   c.register_typecaster('String', ->(meta, value) do
+      #     meta['name'].match?(/\w+_json\z/) ? JSON.parse(value) : value
+      #   end)
       # end
       attr_accessor :http_post_proc, :json_parser, :logger, :log_proc
-      attr_reader :databases
+      attr_reader :databases, :typecasters
 
       def initialize
         @databases = {}
+        @typecasters = {}
         @http_post_proc = nil
         @json_parser = JSON
         @logger = ::Logger.new($stdout)
@@ -69,6 +80,12 @@ module ClickHouse
         @databases[name] = Database.new(**args)
       end
 
+      def register_typecaster(type, typecaster)
+        raise ConfigurationError, "The typecaster for '#{type}' is already registered" if @typecasters.key?(type)
+
+        @typecasters[type] = typecaster
+      end
+
       def validate!
         raise ConfigurationError, "The 'http_post_proc' option is not configured" unless @http_post_proc
         raise ConfigurationError, "The 'json_parser' option is not configured" unless @json_parser

data/lib/click_house/client/formatter.rb

@@ -19,9 +19,9 @@ module ClickHouse
         "IntervalMillisecond" => ->(value) { ActiveSupport::Duration.build(value.to_i / 1000.0) }
       }.freeze
 
-      def self.format(result)
+      def self.format(result, custom_typecasters = {})
         column_typecasters = result['meta'].each_with_object({}) do |column, hash|
-          hash[column['name']] = get_typecaster(column['type']) || DEFAULT
+          hash[column['name']] = build_typecaster(column, custom_typecasters)
         end
 
         result['data'].map do |row|
@@ -31,7 +31,14 @@ module ClickHouse
         end
       end
 
-      def self.get_typecaster(column_type)
+      def self.build_typecaster(column, custom_typecasters)
+        custom_caster = get_typecaster(column['type'], custom_typecasters)
+        return ->(value) { custom_caster.call(column, value) } if custom_caster
+
+        get_typecaster(column['type']) || DEFAULT
+      end
+
+      def self.get_typecaster(column_type, typecasters = TYPE_CASTERS)
         return unless column_type
 
         inner_type = column_type
@@ -39,7 +46,7 @@ module ClickHouse
           .sub(/\ALowCardinality\((.+)\)\z/, '\1') # e.g. LowCardinality(String)
           .sub(/\ASimpleAggregateFunction\(.+,\s*(.+)\)\z/, '\1') # e.g. SimpleAggregateFunction(sum, UInt64)
 
-        TYPE_CASTERS.each do |key, caster|
+        typecasters.each do |key, caster|
           return caster if key.is_a?(String) ? key == inner_type : key.match?(inner_type)
         end
 

data/lib/click_house/client/query.rb

@@ -51,14 +51,14 @@ module ClickHouse
         end
       end
 
-      def to_redacted_sql(bind_index_manager = BindIndexManager.new)
+      def to_redacted_sql
         raw_query.gsub(PLACEHOLDER_REGEX) do |placeholder_in_query|
           value = placeholder_value(placeholder_in_query)
 
           if value.is_a?(QueryLike)
-            value.to_redacted_sql(bind_index_manager)
+            value.to_redacted_sql
           else
-            bind_index_manager.next_bind_str
+            '?'
           end
         end
       end

data/lib/click_house/client/query_builder.rb

@@ -33,8 +33,11 @@ module ClickHouse
       delegate :[], to: :table
 
       def initialize(table, alias_name = nil)
-        @table = if table.is_a?(self.class) # subquery
+        @table = case table
+                 when self.class # subquery
                    Arel::Nodes::TableAlias.new(table.to_arel, alias_name)
+                 when Arel::Nodes::TableAlias
+                   table
                  else
                    Arel::Table.new(table)
                  end
@@ -144,6 +147,30 @@ module ClickHouse
         end
       end
 
+      # Inverts the direction of all ORDER BY clauses: ASC becomes DESC and
+      # vice versa.
+      #
+      # @example
+      #   query.order(:id).reverse_order.to_sql
+      #   # => "SELECT * FROM `test_table` ORDER BY `test_table`.`id` DESC"
+      #
+      # @raise [ArgumentError] if any ordering node has no explicit direction
+      # @return [ClickHouse::Client::QueryBuilder] New instance of query builder.
+      def reverse_order
+        clone.tap do |new_instance|
+          new_instance.manager.ast.orders = new_instance.manager.ast.orders.map do |order|
+            case order
+            when Arel::Nodes::Ascending
+              Arel::Nodes::Descending.new(order.expr)
+            when Arel::Nodes::Descending
+              Arel::Nodes::Ascending.new(order.expr)
+            else
+              raise ArgumentError, "Cannot reverse ordering node without explicit direction: #{order.class.name}"
+            end
+          end
+        end
+      end
+
       def group(*columns)
         clone.tap do |new_instance|
           new_instance.manager.group(*columns)
@@ -182,6 +209,21 @@ module ClickHouse
         end
       end
 
+      # Returns a query that yields no rows.
+      #
+      # @example
+      #   query.none.to_sql
+      #   # => "SELECT * FROM `test_table` WHERE 1 = 0"
+      #
+      # @return [ClickHouse::Client::QueryBuilder] New instance of query builder.
+      def none
+        clone.tap do |new_instance|
+          new_instance.manager.where(
+            Arel.sql('1 = 0')
+          )
+        end
+      end
+
       def from(subquery, alias_name)
         clone.tap do |new_instance|
           new_from = if subquery.is_a?(self.class)
@@ -238,6 +280,31 @@ module ClickHouse
         end
       end
 
+      # Combines this query with one or more other queries using UNION and
+      # returns a new builder that selects from the combined result as an
+      # aliased subquery, so further chaining (#where, #order, #limit, ...)
+      # applies to the outer SELECT.
+      #
+      # @param others [Array<ClickHouse::Client::QueryBuilder>] queries to combine with
+      # @param type [Symbol] :distinct or :all
+      # @param alias_name [String, Symbol] alias for the union subquery
+      # @return [ClickHouse::Client::QueryBuilder] New instance of query builder.
+      def union(*others, type: :distinct, alias_name: 'union_subquery')
+        validate_union_type!(type)
+        raise ArgumentError, 'at least one query to union with is required' if others.empty?
+
+        others.each do |other|
+          raise ArgumentError, "expected #{self.class}, got #{other.class}" unless other.is_a?(self.class)
+        end
+
+        node_class = type == :all ? Arel::Nodes::UnionAll : Arel::Nodes::Union
+        union_node = others.reduce(to_arel.clone.ast) do |left, other|
+          node_class.new(left, other.to_arel.clone.ast)
+        end
+
+        self.class.new(Arel::Nodes::TableAlias.new(union_node, alias_name.to_s))
+      end
+
       # Adds a JOIN clause. Pass `type: :outer` for `LEFT OUTER JOIN`.
       # To join a subquery, pre-alias it via `QueryBuilder.new(sub, 'x').table`
       # or `sub.to_arel.as('x')` and pass that.
@@ -423,9 +490,8 @@ module ClickHouse
         visitor.accept(manager.ast, Arel::Collectors::SQLString.new).value
       end
 
-      def to_redacted_sql(bind_index_manager = ClickHouse::Client::BindIndexManager.new)
-        visitor = ClickHouse::Client::ToRedactedSqlVisitor.new(ClickHouse::Client::ArelEngine.new,
-          bind_manager: bind_index_manager)
+      def to_redacted_sql
+        visitor = ClickHouse::Client::ToRedactedSqlVisitor.new(ClickHouse::Client::ArelEngine.new)
         visitor.accept(manager.ast, Arel::Collectors::SQLString.new).value
       end
 
@@ -499,6 +565,12 @@ module ClickHouse
         raise ArgumentError, "Invalid order direction '#{direction}'. Must be :asc or :desc"
       end
 
+      def validate_union_type!(type)
+        return if %i[distinct all].include?(type)
+
+        raise ArgumentError, "Invalid union type '#{type}'. Must be :distinct or :all"
+      end
+
       def validate_join_type!(type)
         return if %i[inner outer].include?(type)
 

data/lib/click_house/client/query_like.rb

@@ -11,7 +11,7 @@ module ClickHouse
       # Redacted version of the SQL query generated by the to_sql method where the
       # placeholders are stripped. These queries are meant to be exported to external
       # log aggregation systems.
-      def to_redacted_sql(bind_index_manager = BindIndexManager.new)
+      def to_redacted_sql
         raise NotImplementedError
       end
 

data/lib/click_house/client/to_redacted_sql_visitor.rb

@@ -8,15 +8,8 @@ module ClickHouse
     #   query_builder = ClickHouse::QueryBuilder.new('users').where(name: 'John Doe')
     #   redacted_query = query_builder.to_redacted_sql
     #   # The redacted_query will contain the SQL query with values replaced by placeholders.
-    #   output: "SELECT * FROM \"users\" WHERE \"users\".\"name\" = $1"
+    #   output: "SELECT * FROM \"users\" WHERE \"users\".\"name\" = ?"
     class ToRedactedSqlVisitor < ArelVisitor
-      attr_reader :bind_manager
-
-      def initialize(*args, bind_manager: ClickHouse::Client::BindIndexManager.new)
-        @bind_manager = bind_manager
-        super(*args)
-      end
-
       private
 
       def redaction_enabled?
@@ -80,11 +73,9 @@ module ClickHouse
 
         case redacted_o.name
         when 'startsWith'
-          redacted_o.expressions[1] = Arel.sql(bind_manager.next_bind_str)
+          redacted_o.expressions[1] = bind_param
         else
-          redacted_o.expressions = redacted_o.expressions.map do
-            Arel.sql(bind_manager.next_bind_str)
-          end
+          redacted_o.expressions = redacted_o.expressions.map { bind_param }
         end
 
         super(redacted_o, collector)
@@ -100,17 +91,19 @@ module ClickHouse
         cloned_o = o.clone
 
         redacted_right = if o.right.is_a?(Array)
-                           Array.new(o.right.size) do
-                             Arel.sql(bind_manager.next_bind_str)
-                           end
+                           Array.new(o.right.size) { bind_param }
                          else
-                           Arel.sql(bind_manager.next_bind_str)
+                           bind_param
                          end
 
         cloned_o.right = redacted_right
         cloned_o
       end
 
+      def bind_param
+        Arel::Nodes::BindParam.new('?')
+      end
+
       # rubocop:enable Naming/MethodName
       # rubocop:enable Naming/MethodParameterName
     end

data/lib/click_house/client/version.rb

@@ -2,6 +2,6 @@
 
 module ClickHouse
   module Client
-    VERSION = "0.11.0"
+    VERSION = "0.12.0"
   end
 end

data/lib/click_house/client.rb

@@ -10,7 +10,6 @@ require 'active_support/core_ext/object/blank'
 require_relative "client/version"
 require_relative "client/database"
 require_relative "client/configuration"
-require_relative "client/bind_index_manager"
 require_relative "client/quoting"
 require_relative "client/arel_engine"
 require_relative "client/query_like"
@@ -50,7 +49,7 @@ module ClickHouse
 
         instrument[:statistics] = parsed_response['statistics']&.symbolize_keys
 
-        Formatter.format(parsed_response)
+        Formatter.format(parsed_response, configuration.typecasters)
       end
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: click_house-client
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - group::optimize
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-19 00:00:00.000000000 Z
+date: 2026-08-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -187,7 +187,6 @@ files:
 - lib/click_house/client/arel_engine.rb
 - lib/click_house/client/arel_extensions/nodes/final.rb
 - lib/click_house/client/arel_visitor.rb
-- lib/click_house/client/bind_index_manager.rb
 - lib/click_house/client/configuration.rb
 - lib/click_house/client/database.rb
 - lib/click_house/client/formatter.rb

data/lib/click_house/client/bind_index_manager.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-module ClickHouse
-  module Client
-    class BindIndexManager
-      def initialize(start_index = 1)
-        @current_index = start_index
-      end
-
-      def next_bind_str
-        bind_str = "$#{@current_index}"
-        @current_index += 1
-        bind_str
-      end
-    end
-  end
-end