click_house-client 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5513d15d8bf17295cf98d021b30650f46d0101a6d828b2620499f87a949f2e3d
-  data.tar.gz: 27fd28cc07d8b67d8de72031de4e3c7e343cef51a3230afd96ba0adf3d24c252
+  metadata.gz: 839c38cadbcf3638fc513c949c9f7d1b40453c92c0274e32db1d1e9da86df156
+  data.tar.gz: f23d52098f04a9cdb460bf0d8479b19947641546b37ccd85519eeeaba3e59eb6
 SHA512:
-  metadata.gz: b3d7bf7328dd7ab42b004e3e35e58c35b4869267e4a2e701f7d29f963c2c445c3d63f0bbd5e45db679cc4d2fda6880ef367aff18e0a04b1a030f54ede2317ead
-  data.tar.gz: 40125fc9d75f13be2f1230ea872b72c6d01e797384674064d3fb42c613d1792c827e58d6ccfcd894b783ff4d89b838c04e9f50b2e297f4b085bba5c33b95585e
+  metadata.gz: 3c6f54deb213de89f6a5e2e5ad3cccf3e4b3412eb2b22624dc4fda38a41e8a21555736fa7b453fc2e7a07c1cf9fe6f07ef5f5b7bef0aee58019f0e7faa77604c
+  data.tar.gz: 2bbbcf502cba7cb5ed185674afd8eae30a28173ab599b2b00f582a21ed65a140b2d92b0ed523ad1dad192c35fbc0a5eb19ec98a3c815f7212f4f98d739795a53

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    click_house-client (0.11.0)
+    click_house-client (0.13.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.11.0)
+  click_house-client (0.13.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

@@ -231,6 +231,28 @@ query.final.where(active: true).to_sql
 
 `FINAL` is currently applied only to the main `FROM` table. When joining, joined tables are not marked `FINAL`. Calling `.final` multiple times is idempotent.
 
+### Query Settings
+
+Use `.settings` to append a ClickHouse
+[`SETTINGS`](https://clickhouse.com/docs/en/sql-reference/statements/select#settings-in-select-query)
+clause to the query. Chained calls merge, with later values overriding earlier ones.
+Booleans are rendered as `1` / `0` and strings are quoted.
+
+```ruby
+query.where(active: true).settings(max_execution_time: 60, use_query_cache: true).limit(10).to_sql
+# => "SELECT * FROM `users` WHERE `users`.`active` = 'true' LIMIT 10 SETTINGS max_execution_time = 60, use_query_cache = 1"
+```
+
+Settings belong to the query they are set on. When that builder is embedded as a
+subquery, CTE, `UNION` member or `{var:Subquery}` placeholder, its `SETTINGS` clause is
+rendered inside that part of the query, and ClickHouse applies it there:
+
+```ruby
+subquery = ClickHouse::Client::QueryBuilder.new('orders').select(:user_id).settings(max_threads: 2)
+query.where(id: subquery).to_sql
+# => "SELECT * FROM `users` WHERE `users`.`id` IN (SELECT `orders`.`user_id` FROM `orders` SETTINGS max_threads = 2)"
+```
+
 ### Working with JOINs
 
 `#joins` supports `INNER JOIN` (default) and `LEFT OUTER JOIN` via

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'arel'
+
+module ClickHouse
+  module Client
+    module ArelExtensions
+      module Nodes
+        # Holds the settings hash rendered as a trailing ClickHouse `SETTINGS` clause.
+        class Settings < ::Arel::Nodes::Unary
+        end
+      end
+    end
+  end
+end

data/lib/click_house/client/arel_visitor.rb

@@ -40,7 +40,20 @@ module ClickHouse
         collector << " FINAL"
       end
 
+      def visit_ClickHouse_Client_ArelExtensions_Nodes_Settings(object, collector)
+        rendered = object.expr.map { |name, value| "#{name} = #{quote_setting_value(value)}" }
+        collector << "SETTINGS #{rendered.join(', ')}"
+      end
+
       # rubocop:enable Naming/MethodName
+
+      def quote_setting_value(value)
+        case value
+        when true then '1'
+        when false then '0'
+        else ClickHouse::Client::Quoting.quote(value)
+        end
+      end
     end
   end
 end

data/lib/click_house/client/query_builder.rb

@@ -2,6 +2,7 @@
 
 require 'active_record'
 require_relative 'arel_extensions/nodes/final'
+require_relative 'arel_extensions/nodes/settings'
 
 module ClickHouse
   module Client
@@ -30,6 +31,8 @@ module ClickHouse
         Arel::Nodes::As
       ].freeze
 
+      SETTING_NAME_REGEX = /\A[a-zA-Z_][a-zA-Z0-9_]*\z/
+
       delegate :[], to: :table
 
       def initialize(table, alias_name = nil)
@@ -224,6 +227,35 @@ module ClickHouse
         end
       end
 
+      # Appends a ClickHouse `SETTINGS` clause to the end of the query.
+      # See https://clickhouse.com/docs/en/sql-reference/statements/select#settings-in-select-query
+      #
+      # Chained calls merge settings; a later value overrides an earlier one.
+      # Boolean values are rendered as 1 / 0 and strings are quoted.
+      #
+      # Settings are part of the query AST, so they are also rendered when the
+      # builder is embedded as a subquery, CTE or UNION member, and ClickHouse
+      # applies them to that part of the query.
+      #
+      # @example
+      #   query.settings(max_execution_time: 60, use_query_cache: true).to_sql
+      #   # => "SELECT * FROM `test_table` SETTINGS max_execution_time = 60, use_query_cache = 1"
+      #
+      # @param new_settings [Hash{Symbol, String => Integer, Float, String, Symbol, Boolean}]
+      # @raise [ArgumentError] if a setting name or value is invalid
+      # @return [ClickHouse::Client::QueryBuilder] New instance of query builder.
+      def settings(new_settings)
+        new_settings.each { |name, value| validate_setting!(name, value) }
+
+        clone.tap do |new_instance|
+          ast = new_instance.manager.ast
+          merged = (ast.lock&.expr || {}).merge(new_settings.transform_keys(&:to_s)).freeze
+          # ClickHouse has no row locking, so the `lock` slot (rendered after LIMIT / OFFSET)
+          # is free to carry the SETTINGS clause.
+          ast.lock = ArelExtensions::Nodes::Settings.new(merged)
+        end
+      end
+
       def from(subquery, alias_name)
         clone.tap do |new_instance|
           new_from = if subquery.is_a?(self.class)
@@ -501,6 +533,16 @@ module ClickHouse
 
       private
 
+      def validate_setting!(name, value)
+        unless (name.is_a?(String) || name.is_a?(Symbol)) && name.to_s.match?(SETTING_NAME_REGEX)
+          raise ArgumentError, "Invalid setting name '#{name}'"
+        end
+
+        return if [Integer, Float, String, Symbol, TrueClass, FalseClass].any? { |klass| value.is_a?(klass) }
+
+        raise ArgumentError, "Invalid value for setting '#{name}': #{value.class.name}"
+      end
+
       def normalize_operand(operand)
         case operand
         when Arel::Expressions

data/lib/click_house/client/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: click_house-client
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - group::optimize
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-04 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -186,6 +186,7 @@ files:
 - 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_extensions/nodes/settings.rb
 - lib/click_house/client/arel_visitor.rb
 - lib/click_house/client/configuration.rb
 - lib/click_house/client/database.rb