click_house-client 0.8.8 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efb07f40cb2cd6ebd768d0d216372f960e57af838c825f41dfa3356bcb76143c
-  data.tar.gz: 3da016575fc8ff03342151fd60b13f8b01c9aaf3a73a635572031a6c75b6d929
+  metadata.gz: bef646c7c07c30559265378e9fec3f14f5e41aeadd86058120a31d532d77d10a
+  data.tar.gz: e969763ad335eda82d36f3d949207cfcb95ab238646ff0b3e4ec18e5a17bd445
 SHA512:
-  metadata.gz: a7abdfef08371fcadccc3bb911742a983ed6773510b54166858b8b16e36f2c0b0b30ef910fc884dc3147a54699e321b899231b0eaa4224b3a224aae7fa8491a3
-  data.tar.gz: 26d6897f5abbc5c0403e4e04362268ee0ec672bd2149e4714f2f0b77a225c13b225a85459faaaa65a9f5a9cf5eb08200c06f77d5911360f30b018b32a705f0a6
+  metadata.gz: 9f7883a21fba0ab5534c85ca43686a3490234252c2277e200a244a3bead56fa3a31d7597c8b23deecb0086b5ad3a90dde67c8425f8ce257c289cb29abb8b29ad
+  data.tar.gz: 175aaeaefe0f02f0ba1cd9e3828d9d4bb876c450f626765b78568297c0d35d7e2eb7de00f900ea88db84f7240fbb32790fededbd258dcad4afb4d9291bb16f7c

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    click_house-client (0.8.8)
+    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.8)
+  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/query_builder.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'active_record'
+require_relative 'arel_extensions/nodes/final'
 
 module ClickHouse
   module Client
@@ -159,40 +160,78 @@ 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
@@ -419,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/version.rb

@@ -2,6 +2,6 @@
 
 module ClickHouse
   module Client
-    VERSION = "0.8.8"
+    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.8
+  version: 0.10.0
 platform: ruby
 authors:
 - group::optimize
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-02 00:00:00.000000000 Z
+date: 2026-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -185,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