click_house-client 0.8.3 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f12c7192094a0cec94c354381b9be928dff901c03a9e8522dde43a695ce99b62
-  data.tar.gz: bedf93d6760663e747598c2cf9f60b90106b5d6979a7fe11dd00749cb03e4326
+  metadata.gz: bef646c7c07c30559265378e9fec3f14f5e41aeadd86058120a31d532d77d10a
+  data.tar.gz: e969763ad335eda82d36f3d949207cfcb95ab238646ff0b3e4ec18e5a17bd445
 SHA512:
-  metadata.gz: 5fe06dbc303e5b94e72e84b0da50c96defa1be6445a77236ad29f49ed4283cb0e0d5ce147e5bafba671ac01d7064be5c3f0e4f80ff83ffe74eae7207f1b6a56e
-  data.tar.gz: a183e8f5081a5f1c4463e0b35c5fde96968023555c6b65ef4e5495a52650f747a224dfb468145cb3c5d5a55333e859398db6284952fec9c323f0bec3a4b6247e
+  metadata.gz: 9f7883a21fba0ab5534c85ca43686a3490234252c2277e200a244a3bead56fa3a31d7597c8b23deecb0086b5ad3a90dde67c8425f8ce257c289cb29abb8b29ad
+  data.tar.gz: 175aaeaefe0f02f0ba1cd9e3828d9d4bb876c450f626765b78568297c0d35d7e2eb7de00f900ea88db84f7240fbb32790fededbd258dcad4afb4d9291bb16f7c

data/.gitignore

@@ -0,0 +1 @@
+.rspec_status

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    click_house-client (0.8.3)
+    click_house-client (0.10.0)
       activerecord (>= 7.0, < 9.0)
       activesupport (>= 7.0, < 9.0)
       addressable (~> 2.8)
@@ -136,7 +136,7 @@ CHECKSUMS
   benchmark (0.4.1) sha256=d4ef40037bba27f03b28013e219b950b82bace296549ec15a78016552f8d2cce
   bigdecimal (3.2.2) sha256=39085f76b495eb39a79ce07af716f3a6829bc35eb44f2195e2753749f2fa5adc
   byebug (12.0.0) sha256=d4a150d291cca40b66ec9ca31f754e93fed8aa266a17335f71bb0afa7fca1a1e
-  click_house-client (0.8.3)
+  click_house-client (0.10.0)
   concurrent-ruby (1.3.5) sha256=813b3e37aca6df2a21a3b9f1d497f8cbab24a2b94cab325bffe65ee0f6cbebc6
   connection_pool (2.5.3) sha256=cfd74a82b9b094d1ce30c4f1a346da23ee19dc8a062a16a85f58eab1ced4305b
   diff-lcs (1.5.0) sha256=49b934001c8c6aedb37ba19daec5c634da27b318a7a3c654ae979d6ba1929b67

data/README.md

@@ -182,9 +182,28 @@ query
 # => "SELECT * FROM `users` WHERE `users`.`active` = 'true' GROUP BY `users`.`department` HAVING `users`.`avg_salary` > 50000"
 ```
 
+### FINAL Modifier
+
+ClickHouse's `FINAL` modifier forces merging of rows during query time for tables in the MergeTree family. Apply it via `.final`:
+
+```ruby
+query.final.to_sql
+# => "SELECT * FROM `users` FINAL"
+
+query.final.where(active: true).to_sql
+# => "SELECT * FROM `users` FINAL WHERE `users`.`active` = 'true'"
+```
+
+> ⚠️ **Warning:** Using `FINAL` in production code can cause excessive I/O and affect ClickHouse availability. Prefer using it only in test environments or behind a feature flag.
+
+`FINAL` is currently applied only to the main `FROM` table. When joining, joined tables are not marked `FINAL`. Calling `.final` multiple times is idempotent.
+
 ### Working with JOINs
 
-When using JOINs, you can apply conditions to joined tables: _(Supports only `INNER JOIN`)_
+`#joins` supports `INNER JOIN` (default) and `LEFT OUTER JOIN` via
+`type: :outer`. The join source can be a table name, an `Arel::Table`, or a
+pre-aliased subquery (`QueryBuilder.new(sub, 'alias').table` or
+`sub.to_arel.as('alias')`).
 
 ```ruby
 # Join with conditions on joined table
@@ -201,6 +220,17 @@ query
   .having(orders: { total: [100, 200, 300] })
   .to_sql
 # => "SELECT * FROM `users` INNER JOIN `orders` ON `users`.`id` = `orders`.`user_id` GROUP BY `users`.`department` HAVING `orders`.`total` IN (100, 200, 300)"
+
+# LEFT OUTER JOIN against a pre-aliased subquery
+orders_sub = ClickHouse::Client::QueryBuilder.new(
+  ClickHouse::Client::QueryBuilder.new('orders').select(:id, :user_id),
+  'o'
+)
+
+query
+  .joins(orders_sub.table, { id: :user_id }, type: :outer)
+  .to_sql
+# => "SELECT * FROM `users` LEFT OUTER JOIN (SELECT `orders`.`id`, `orders`.`user_id` FROM `orders`) `o` ON `users`.`id` = `o`.`user_id`"
 ```
 
 ### Complete Example

data/lib/click_house/client/arel_extensions/nodes/final.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'arel'
+
+module ClickHouse
+  module Client
+    module ArelExtensions
+      module Nodes
+        class Final < ::Arel::Nodes::Unary
+        end
+      end
+    end
+  end
+end

data/lib/click_house/client/arel_visitor.rb

@@ -30,6 +30,11 @@ module ClickHouse
         end
       end
 
+      def visit_ClickHouse_Client_ArelExtensions_Nodes_Final(object, collector)
+        collector = visit(object.expr, collector)
+        collector << " FINAL"
+      end
+
       # rubocop:enable Naming/MethodName
     end
   end

data/lib/click_house/client/formatter.rb

@@ -5,34 +5,46 @@ module ClickHouse
     class Formatter
       DEFAULT = ->(value) { value }
 
-      BASIC_TYPE_CASTERS = {
-        'Int32' => ->(value) { Integer(value) },
-        'UInt32' => ->(value) { Integer(value) },
-        'Int64' => ->(value) { Integer(value) },
-        'UInt64' => ->(value) { Integer(value) },
-        "DateTime64(6, 'UTC')" => ->(value) { ActiveSupport::TimeZone['UTC'].parse(value) },
+      TYPE_CASTERS = {
+        # UInt8/16/32/64, Int8/16/32/64
+        /\AU?Int\d+\z/ => ->(value) { Integer(value) },
+        # Float8/16/32/64
+        /\AFloat\d+\z/ => ->(value) { Float(value) },
+        # Date, Date32
+        /\ADate\d*\z/ => ->(value) { Date.parse(value) },
+        # DateTime64(0/3/6/9, 'UTC')
+        /\ADateTime64\(\d+, 'UTC'\)\z/ => ->(value) { ActiveSupport::TimeZone['UTC'].parse(value) },
+        "DateTime('UTC')" => ->(value) { ActiveSupport::TimeZone['UTC'].parse(value) },
         "IntervalSecond" => ->(value) { ActiveSupport::Duration.build(value.to_i) },
         "IntervalMillisecond" => ->(value) { ActiveSupport::Duration.build(value.to_i / 1000.0) }
       }.freeze
 
-      TYPE_CASTERS = BASIC_TYPE_CASTERS.merge(
-        BASIC_TYPE_CASTERS.transform_keys { |type| "Nullable(#{type})" }
-          .transform_values { |caster| ->(value) { value.nil? ? nil : caster.call(value) } }
-      )
-
       def self.format(result)
-        name_type_mapping = result['meta'].each_with_object({}) do |column, hash|
-          hash[column['name']] = column['type']
+        column_typecasters = result['meta'].each_with_object({}) do |column, hash|
+          hash[column['name']] = get_typecaster(column['type']) || DEFAULT
         end
 
         result['data'].map do |row|
           row.each_with_object({}) do |(column, value), casted_row|
-            caster = TYPE_CASTERS.fetch(name_type_mapping[column], DEFAULT)
-
-            casted_row[column] = caster.call(value)
+            casted_row[column] = value.nil? ? value : column_typecasters[column].call(value)
           end
         end
       end
+
+      def self.get_typecaster(column_type)
+        return unless column_type
+
+        inner_type = column_type
+          .sub(/\ANullable\((.+)\)\z/, '\1') # e.g Nullable(String)
+          .sub(/\ALowCardinality\((.+)\)\z/, '\1') # e.g. LowCardinality(String)
+          .sub(/\ASimpleAggregateFunction\(.+,\s*(.+)\)\z/, '\1') # e.g. SimpleAggregateFunction(sum, UInt64)
+
+        TYPE_CASTERS.each do |key, caster|
+          return caster if key.is_a?(String) ? key == inner_type : key.match?(inner_type)
+        end
+
+        nil
+      end
     end
   end
 end

data/lib/click_house/client/query_builder.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'active_record'
+require_relative 'arel_extensions/nodes/final'
 
 module ClickHouse
   module Client
@@ -29,6 +30,8 @@ module ClickHouse
         Arel::Nodes::As
       ].freeze
 
+      delegate :[], to: :table
+
       def initialize(table, alias_name = nil)
         @table = if table.is_a?(self.class) # subquery
                    Arel::Nodes::TableAlias.new(table.to_arel, alias_name)
@@ -68,6 +71,15 @@ module ClickHouse
         end
       end
 
+      # Evaluates given block in scope of current builder. Example:
+      # query = ClickHouse::Client::QueryBuilder.new('test_table').build do
+      #   select(named_func('argMax', [table[:id], table[:timestamp]]).as('max_id')).limit(10)
+      # end
+      # @return [ClickHouse::QueryBuilder] New instance of query builder.
+      def build(&)
+        instance_eval(&)
+      end
+
       # The `having` method applies constraints to the HAVING clause, similar to how
       # `where` applies constraints to the WHERE clause. It supports the same constraint types.
       # Correct usage:
@@ -148,44 +160,96 @@ module ClickHouse
         self
       end
 
+      # Applies the ClickHouse `FINAL` modifier to the main FROM table.
+      # See https://clickhouse.com/docs/en/sql-reference/statements/select/from#final-modifier
+      #
+      # @example
+      #   query.final.to_sql
+      #   # => "SELECT * FROM `test_table` FINAL"
+      #
+      # Note: `FINAL` only makes sense on a ClickHouse MergeTree-family table.
+      #
+      # WARNING: Using `FINAL` in production code can cause excessive I/O and
+      # affect ClickHouse availability. Prefer using it only in test environments
+      # or behind a feature flag.
+      #
+      # @return [ClickHouse::Client::QueryBuilder] New instance of query builder.
+      def final
+        clone.tap do |new_instance|
+          source = new_instance.manager.source.left
+          wrapped = source.is_a?(ArelExtensions::Nodes::Final) ? source : ArelExtensions::Nodes::Final.new(source)
+          new_instance.manager.from(wrapped)
+        end
+      end
+
       def from(subquery, alias_name)
         clone.tap do |new_instance|
-          if subquery.is_a?(self.class)
-            new_instance.manager.from(subquery.to_arel.as(alias_name))
-          else
-            new_instance.manager.from(Arel::Nodes::TableAlias.new(subquery, alias_name))
+          new_from = if subquery.is_a?(self.class)
+                       subquery.to_arel.as(alias_name)
+                     else
+                       Arel::Nodes::TableAlias.new(subquery, alias_name)
+                     end
+
+          if new_instance.manager.source.left.is_a?(ArelExtensions::Nodes::Final)
+            new_from = ArelExtensions::Nodes::Final.new(new_from)
           end
+
+          new_instance.manager.from(new_from)
         end
       end
 
-      def joins(table_name, constraint = nil)
+      # 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.
+      # @return [ClickHouse::Client::QueryBuilder] New instance of query builder.
+      def joins(source, constraint = nil, type: :inner)
+        validate_join_type!(type)
+
         clone.tap do |new_instance|
-          join_table = table_name.is_a?(Arel::Table) ? table_name : Arel::Table.new(table_name)
+          join_target = case source
+                        when Arel::Table, Arel::Nodes::TableAlias then source
+                        else Arel::Table.new(source)
+                        end
+          join_class = type == :outer ? Arel::Nodes::OuterJoin : Arel::Nodes::InnerJoin
 
           join_condition = case constraint
                            when Hash
                              # Handle hash based constraints like { table1.id: table2.ref_id } or {id: :ref_id}
                              constraint_conditions = constraint.map do |left, right|
                                left_field = left.is_a?(Arel::Attributes::Attribute) ? left : new_instance.table[left]
-                               right_field = right.is_a?(Arel::Attributes::Attribute) ? right : join_table[right]
+                               right_field = right.is_a?(Arel::Attributes::Attribute) ? right : join_target[right]
                                left_field.eq(right_field)
                              end
 
                              constraint_conditions.reduce(&:and)
                            when Proc
-                             constraint.call(new_instance.table, join_table)
-                           when Arel::Nodes::Node
+                             constraint.call(new_instance.table, join_target)
+                           when Arel::Nodes::Node, Arel::Nodes::SqlLiteral
                              constraint
                            end
 
           if join_condition
-            new_instance.manager.join(join_table).on(join_condition)
+            new_instance.manager.join(join_target, join_class).on(join_condition)
           else
-            new_instance.manager.join(join_table)
+            new_instance.manager.join(join_target, join_class)
           end
         end
       end
 
+      # Shortcut for `Arel::Nodes::NamedFunction.new`
+      # @return [Arel::Nodes::NamedFunction]
+      def named_func(*args)
+        Arel::Nodes::NamedFunction.new(*args)
+      end
+
+      # Shortcut for `Arel::Nodes.build_quoted`
+      # @return [Arel::Nodes::Node]
+      def quote(...)
+        Arel::Nodes.build_quoted(...)
+      end
+
+      alias_method :func, :named_func
+
       # Aggregation helper methods
 
       # Creates an AVG aggregate function node
@@ -394,6 +458,12 @@ module ClickHouse
 
         raise ArgumentError, "Invalid order direction '#{direction}'. Must be :asc or :desc"
       end
+
+      def validate_join_type!(type)
+        return if %i[inner outer].include?(type)
+
+        raise ArgumentError, "Invalid join type '#{type}'. Must be :inner or :outer"
+      end
     end
   end
 end

data/lib/click_house/client/quoting.rb

@@ -9,6 +9,7 @@ module ClickHouse
           when Numeric then value.to_s
           when String, Symbol then "'#{value.to_s.gsub('\\', '\&\&').gsub("'", "''")}'"
           when Array then "[#{value.map { |v| quote(v) }.join(',')}]"
+          when Time then value.utc.to_f
           when nil then "NULL"
           else quote_str(value.to_s)
           end

data/lib/click_house/client/version.rb

@@ -2,6 +2,6 @@
 
 module ClickHouse
   module Client
-    VERSION = "0.8.3"
+    VERSION = "0.10.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: click_house-client
 version: !ruby/object:Gem::Version
-  version: 0.8.3
+  version: 0.10.0
 platform: ruby
 authors:
 - group::optimize
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-21 00:00:00.000000000 Z
+date: 2026-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -170,6 +170,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".gitignore"
 - ".gitlab-ci.yml"
 - ".rspec"
 - ".rubocop.yml"
@@ -184,6 +185,7 @@ files:
 - gemfiles/Gemfile-rails-8.0
 - lib/click_house/client.rb
 - 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