click_house-client 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cccbd9106d3d83f03a0dba17c0e3c43fc58f93dfd5ed75baaa86cbdd1f3628b0
-  data.tar.gz: 876218b5e4601d897b0c83b607ec83a23c10e6d927347ac2ac03bf34309d7b55
+  metadata.gz: 20e1cebe2da3ec70c0a9ab7be6e5e53d2f2462b4787fd7e7389adfdbe4c64ea9
+  data.tar.gz: 0bdebe100594f4025f53a5c28723ef776d10ff327283166f70c9990a3323bb62
 SHA512:
-  metadata.gz: 65bfaba824f239654390d509efcaf9dd03486fee4db020916c53cad306cd0abdf8d93fa1ea091da0a55123bef2512947f10df572d181f387eac8ee5d34b8488f
-  data.tar.gz: 428207f4a11fa7ec577e5316130d053f59c3d88544e3f0f77da8f33ab0f2f60efaa6646ca8cf523e20ef474a13acbdfc8b44f7dde19347c28a861c3816c16a27
+  metadata.gz: 58e7ed6985feda6a89dd33a1eac938509d3515016eea6c92ea38621c327a94d6e997dd166d67b3b7a2ddd1350edee0e3997055301159c01e8b0e3cac75531707
+  data.tar.gz: fd25cb3026f5be1d693181cbab8c13915abdad23ac0acd31e4d098b4477c35d6ef99e010e3e4c1477eb00b729bbdaecc5d4a2b40f36d1a35d147f4cdd6f1402f

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    click_house-client (0.9.0)
+    click_house-client (0.11.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.9.0)
+  click_house-client (0.11.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

@@ -200,7 +200,10 @@ query.final.where(active: true).to_sql
 
 ### 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
@@ -217,8 +220,46 @@ 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`"
 ```
 
+### Common Table Expressions (CTEs)
+
+Use `#as_cte(name)` to wrap a query as a named CTE node, then attach it to a
+main query with `#with(cte)`. The CTE can then be referenced by name in `FROM`
+and IN-subquery positions, which is useful when the same subquery is needed in
+more than one place.
+
+```ruby
+inner = ClickHouse::Client::QueryBuilder.new('builds').select(:id, :stage_id)
+query_builder = ClickHouse::Client::QueryBuilder.new('finished_builds').select(:id)
+
+query_builder.with(inner.as_cte(:finished_builds)).to_sql
+# => "WITH finished_builds AS (SELECT `builds`.`id`, `builds`.`stage_id` FROM `builds`) SELECT `finished_builds`.`id` FROM `finished_builds`"
+```
+
+Chained calls accumulate, unlike `Arel::SelectManager#with` which would keep
+only the last CTE:
+
+```ruby
+query_builder.with(inner.as_cte(:a)).with(inner.as_cte(:b)).to_sql
+# => "WITH a AS (...), b AS (...) SELECT ..."
+```
+
+`#with` returns a new `QueryBuilder` (immutable), requires an `Arel::Nodes::Cte`
+(build it via `#as_cte`), and raises if the same CTE name is declared more than
+once.
+
 ### Complete Example
 
 Here's a comprehensive example combining multiple QueryBuilder features:

data/gemfiles/Gemfile-rails-7.2

@@ -5,6 +5,9 @@ source "https://rubygems.org"
 gemspec path: ".."
 
 gem "rails", "~> 7.2"
+# i18n >= 1.15 calls Fiber#[] (Ruby 3.2+) but declares no required_ruby_version,
+# so it resolves on Ruby 3.1 and then crashes at load.
+gem "i18n", "< 1.15"
 gem "gitlab-styles", "~> 12.0.1"
 gem "rake", "~> 13.0"
 gem "rspec", "~> 3.0"

data/lib/click_house/client/query_builder.rb

@@ -198,30 +198,80 @@ module ClickHouse
         end
       end
 
-      def joins(table_name, constraint = nil)
+      # Wraps this query as a CTE node with the given name, so it can be passed
+      # to #with: `query_builder.with(sub_query.as_cte(:foo))`. The name is
+      # rendered as a SQL identifier, not a quoted value.
+      #
+      # The manager is cloned so later in-place mutations on this builder (e.g.
+      # #limit or #offset) do not alter the captured CTE body.
+      #
+      # @param name [String, Symbol] name the CTE is referenced by
+      # @return [Arel::Nodes::Cte]
+      def as_cte(name)
+        Arel::Nodes::Cte.new(Arel::Nodes::SqlLiteral.new(name.to_s), to_arel.clone)
+      end
+
+      # Attaches a CTE node, emitting `WITH name AS (...)` before the SELECT.
+      # The CTE can then be referenced by name in FROM and IN-subquery positions,
+      # which is useful when the same subquery is needed in more than one place.
+      #
+      # Build the node with #as_cte, for example
+      # `query_builder.with(sub_query.as_cte(:foo))`.
+      #
+      # Chained calls accumulate: `query_builder.with(a).with(b)` emits both
+      # CTEs. This differs from `Arel::SelectManager#with`, which replaces any
+      # previously set CTE and would keep only `b`.
+      #
+      # @param cte [Arel::Nodes::Cte] a CTE node from #as_cte
+      # @return [ClickHouse::Client::QueryBuilder]
+      def with(cte)
+        unless cte.is_a?(Arel::Nodes::Cte)
+          raise ArgumentError, "expected Arel::Nodes::Cte, got #{cte.class}. " \
+            'Use #as_cte(name) to create one.'
+        end
+
+        clone.tap do |new_instance|
+          existing = new_instance.manager.ast.with
+          all_ctes = existing ? existing.children + [cte] : [cte]
+          validate_unique_cte_names!(all_ctes)
+          new_instance.manager.ast.with = Arel::Nodes::With.new(all_ctes)
+        end
+      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.
+      # @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
@@ -448,6 +498,21 @@ 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
+
+      def validate_unique_cte_names!(ctes)
+        names = ctes.map { |cte| cte.name.to_s }
+        duplicates = names.tally.select { |_, count| count > 1 }.keys
+
+        return if duplicates.empty?
+
+        raise ArgumentError, "duplicate CTE name(s): #{duplicates.join(', ')}"
+      end
     end
   end
 end

data/lib/click_house/client/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: click_house-client
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.11.0
 platform: ruby
 authors:
 - group::optimize
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-28 00:00:00.000000000 Z
+date: 2026-06-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord