click_house-client 0.8.8 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efb07f40cb2cd6ebd768d0d216372f960e57af838c825f41dfa3356bcb76143c
-  data.tar.gz: 3da016575fc8ff03342151fd60b13f8b01c9aaf3a73a635572031a6c75b6d929
+  metadata.gz: cccbd9106d3d83f03a0dba17c0e3c43fc58f93dfd5ed75baaa86cbdd1f3628b0
+  data.tar.gz: 876218b5e4601d897b0c83b607ec83a23c10e6d927347ac2ac03bf34309d7b55
 SHA512:
-  metadata.gz: a7abdfef08371fcadccc3bb911742a983ed6773510b54166858b8b16e36f2c0b0b30ef910fc884dc3147a54699e321b899231b0eaa4224b3a224aae7fa8491a3
-  data.tar.gz: 26d6897f5abbc5c0403e4e04362268ee0ec672bd2149e4714f2f0b77a225c13b225a85459faaaa65a9f5a9cf5eb08200c06f77d5911360f30b018b32a705f0a6
+  metadata.gz: 65bfaba824f239654390d509efcaf9dd03486fee4db020916c53cad306cd0abdf8d93fa1ea091da0a55123bef2512947f10df572d181f387eac8ee5d34b8488f
+  data.tar.gz: 428207f4a11fa7ec577e5316130d053f59c3d88544e3f0f77da8f33ab0f2f60efaa6646ca8cf523e20ef474a13acbdfc8b44f7dde19347c28a861c3816c16a27

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    click_house-client (0.8.8)
+    click_house-client (0.9.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.9.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,6 +182,22 @@ 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`)_

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,13 +160,41 @@ 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
 

data/lib/click_house/client/version.rb

@@ -2,6 +2,6 @@
 
 module ClickHouse
   module Client
-    VERSION = "0.8.8"
+    VERSION = "0.9.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.9.0
 platform: ruby
 authors:
 - group::optimize
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-02 00:00:00.000000000 Z
+date: 2026-05-28 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