click_house-client 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bef646c7c07c30559265378e9fec3f14f5e41aeadd86058120a31d532d77d10a
-  data.tar.gz: e969763ad335eda82d36f3d949207cfcb95ab238646ff0b3e4ec18e5a17bd445
+  metadata.gz: 20e1cebe2da3ec70c0a9ab7be6e5e53d2f2462b4787fd7e7389adfdbe4c64ea9
+  data.tar.gz: 0bdebe100594f4025f53a5c28723ef776d10ff327283166f70c9990a3323bb62
 SHA512:
-  metadata.gz: 9f7883a21fba0ab5534c85ca43686a3490234252c2277e200a244a3bead56fa3a31d7597c8b23deecb0086b5ad3a90dde67c8425f8ce257c289cb29abb8b29ad
-  data.tar.gz: 175aaeaefe0f02f0ba1cd9e3828d9d4bb876c450f626765b78568297c0d35d7e2eb7de00f900ea88db84f7240fbb32790fededbd258dcad4afb4d9291bb16f7c
+  metadata.gz: 58e7ed6985feda6a89dd33a1eac938509d3515016eea6c92ea38621c327a94d6e997dd166d67b3b7a2ddd1350edee0e3997055301159c01e8b0e3cac75531707
+  data.tar.gz: fd25cb3026f5be1d693181cbab8c13915abdad23ac0acd31e4d098b4477c35d6ef99e010e3e4c1477eb00b729bbdaecc5d4a2b40f36d1a35d147f4cdd6f1402f

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    click_house-client (0.10.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.10.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

@@ -233,6 +233,33 @@ query
 # => "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,6 +198,46 @@ module ClickHouse
         end
       end
 
+      # 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.
@@ -464,6 +504,15 @@ module ClickHouse
 
         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.10.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.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - group::optimize
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-04 00:00:00.000000000 Z
+date: 2026-06-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord