click_house-client 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9934204626e5719062113ca9663b762a387b91112a39bfe78aa6ac92f5741d6
-  data.tar.gz: 574ea9046e7cd316802871c6dc86152022092b4d0bea14c1d10943dec3cf6748
+  metadata.gz: 45b65dc2ae8ced88a1129e3fb7e78e3d314bbc5eb41402e430932d7e4c169e98
+  data.tar.gz: 9f25ca4f27d5c0b500339bc682d6de3b5b0ffd97b5484b14707949906064b891
 SHA512:
-  metadata.gz: 8ace70ea9c9575040206ac917acb386b95bb206d79a4e270f558b2b189ed5a11add58fd79e8b821538d6042ebd9d189a7552472b1036bd4191705a5d8504788e
-  data.tar.gz: 2b962b32106e75a1ed3384703907558de78d97356a88d9903cc3b427a43c4158415a28810fd10d7d28ad0fa9c2999421c7a7b7d925e7b3cb5cc1a50e3ad418b9
+  metadata.gz: a50a5010fb3900ec46fc9c84fe4bbe6f3647beee599fd40940ddfa89f7ae6ba6a0eb569021b9f34a0e9f72237277b75b34a4820523fa2413a95b696d16c9a2c5
+  data.tar.gz: 998b97239232786839a7568a8a06aa69090127ae1ba68be5cb30bfb57ad26c599aedfda37a4603b0cdf3464a7dd9209f88793688ed5af81dcd0f4315646ed97c

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    click_house-client (0.7.0)
+    click_house-client (0.8.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.7.0)
+  click_house-client (0.8.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

@@ -61,6 +61,184 @@ puts ClickHouse::Client.execute('CREATE TABLE IF NOT EXISTS t1 (id Int64) ENGINE
 puts ClickHouse::Client.execute('DROP TABLE IF EXISTS t1', :main)
 ```
 
+## ClickHouse::Client::QueryBuilder
+
+The QueryBuilder provides an ActiveRecord-like interface for constructing ClickHouse queries programmatically. While similar to ActiveRecord's query interface, it has been tailored specifically for ClickHouse's SQL dialect and features.
+
+### Basic Usage
+
+```ruby
+# Initialize a query builder for a table
+query = ClickHouse::Client::QueryBuilder.new('users')
+
+# Build and execute queries
+query.select(:id, :name).where(active: true).to_sql
+# => "SELECT `users`.`id`, `users`.`name` FROM `users` WHERE `users`.`active` = 'true'"
+```
+
+### WHERE Clause
+
+The `where` method supports various types of conditions:
+
+#### Simple Equality Conditions
+
+```ruby
+query.where(status: 'active').to_sql
+# => "SELECT * FROM `users` WHERE `users`.`status` = 'active'"
+
+# Multiple conditions (joined with AND)
+query.where(status: 'active', role: 'admin').to_sql
+# => "SELECT * FROM `users` WHERE `users`.`status` = 'active' AND `users`.`role` = 'admin'"
+```
+
+#### Array Conditions (IN clause)
+
+```ruby
+query.where(id: [1, 2, 3]).to_sql
+# => "SELECT * FROM `users` WHERE `users`.`id` IN (1, 2, 3)"
+```
+
+#### Using Arel Nodes for Complex Conditions
+
+```ruby
+# Greater than
+query.where(query.table[:age].gt(18)).to_sql
+# => "SELECT * FROM `users` WHERE `users`.`age` > 18"
+
+# Less than
+query.where(query.table[:price].lt(100)).to_sql
+# => "SELECT * FROM `users` WHERE `users`.`price` < 100"
+
+# Between
+query.where(query.table[:created_at].between(Date.yesterday..Date.today)).to_sql
+# => "SELECT * FROM `users` WHERE `users`.`created_at` BETWEEN '2025-09-10' AND '2025-09-11'"
+
+# Combining conditions with AND
+condition = query.table[:age].gt(18).and(query.table[:status].eq('active'))
+query.where(condition).to_sql
+# => "SELECT * FROM `users` WHERE `users`.`age` > 18 AND `users`.`status` = 'active'"
+
+# Combining conditions with OR
+condition = query.table[:role].eq('admin').or(query.table[:role].eq('moderator'))
+query.where(condition).to_sql
+# => "SELECT * FROM `users` WHERE (`users`.`role` = 'admin' OR `users`.`role` = 'moderator')"
+
+# List of supported node types in where clause
+puts ClickHouse::Client::QueryBuilder::VALID_NODES
+```
+
+#### Pattern Matching with LIKE/ILIKE
+
+```ruby
+# Case-insensitive pattern matching (ILIKE - default)
+query.where(query.table[:email].matches('%@example.com')).to_sql
+# => "SELECT * FROM `users` WHERE `users`.`email` ILIKE '%@example.com'"
+
+# Case-sensitive pattern matching (LIKE)
+query.where(query.table[:name].matches('John%', nil, true)).to_sql
+# => "SELECT * FROM `users` WHERE `users`.`name` LIKE 'John%'"
+
+# Negative pattern matching (NOT ILIKE)
+query.where(query.table[:email].does_not_match('%@spam.com')).to_sql
+# => "SELECT * FROM `users` WHERE `users`.`email` NOT ILIKE '%@spam.com'"
+```
+
+#### Subqueries
+
+```ruby
+# Using a subquery in WHERE clause
+subquery = ClickHouse::Client::QueryBuilder.new('orders')
+  .select(:user_id)
+  .where(status: 'completed')
+
+query.where(id: subquery).to_sql
+# => "SELECT * FROM `users` WHERE `users`.`id` IN (SELECT `orders`.`user_id` FROM `orders` WHERE `orders`.`status` = 'completed')"
+```
+
+### HAVING Clause
+
+The `having` method works similarly to `where` but is used for filtering aggregated results:
+
+```ruby
+# Using COUNT(*) in HAVING clause
+count_func = Arel::Nodes::NamedFunction.new('COUNT', [Arel.star])
+query.group(:department).having(count_func.gt(10)).to_sql
+# => "SELECT * FROM `users` GROUP BY `users`.`department` HAVING COUNT(*) > 10"
+
+# Using other aggregation functions
+sum_func = Arel::Nodes::NamedFunction.new('SUM', [query.table[:salary]])
+query.group(:department).having(sum_func.gt(100000)).to_sql
+# => "SELECT * FROM `users` GROUP BY `users`.`department` HAVING SUM(`users`.`salary`) > 100000"
+```
+
+#### Combining WHERE and HAVING
+
+```ruby
+query
+  .where(active: true)
+  .group(:department)
+  .having(query.table[:avg_salary].gt(50000))
+  .to_sql
+# => "SELECT * FROM `users` WHERE `users`.`active` = 'true' GROUP BY `users`.`department` HAVING `users`.`avg_salary` > 50000"
+```
+
+### Working with JOINs
+
+When using JOINs, you can apply conditions to joined tables: _(Supports only `INNER JOIN`)_
+
+```ruby
+# Join with conditions on joined table
+query
+  .joins('orders', { 'id' => 'user_id' })
+  .where(orders: { status: 'pending' })
+  .to_sql
+# => "SELECT * FROM `users` INNER JOIN `orders` ON `users`.`id` = `orders`.`user_id` WHERE `orders`.`status` = 'pending'"
+
+# HAVING clause with joined tables
+query
+  .joins('orders', { 'id' => 'user_id' })
+  .group(:department)
+  .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)"
+```
+
+### Complete Example
+
+Here's a comprehensive example combining multiple QueryBuilder features:
+
+```ruby
+# Find active users in specific departments who have completed orders
+# Group by department and filter groups with more than 5 users
+
+completed_orders = ClickHouse::Client::QueryBuilder.new('orders')
+  .select(:user_id)
+  .where(status: 'completed')
+  .where(query.table[:created_at].gt(Date.today - 30))
+
+count_func = Arel::Nodes::NamedFunction.new('COUNT', [Arel.star])
+
+result = ClickHouse::Client::QueryBuilder.new('users')
+  .select(:department, count_func.as('user_count'))
+  .where(active: true)
+  .where(department: ['Sales', 'Marketing', 'Engineering'])
+  .where(id: completed_orders)
+  .where(query.table[:email].matches('%@company.com'))
+  .group(:department)
+  .having(count_func.gt(5))
+  .order(Arel.sql('user_count'), :desc)
+  .limit(10)
+
+puts result.to_sql
+"SELECT `users`.`department`, COUNT(*) AS user_count FROM `users` WHERE `users`.`active` = 'true' 
+AND `users`.`department` IN ('Sales', 'Marketing', 'Engineering') 
+AND `users`.`id` IN (SELECT `orders`.`user_id` FROM `orders` WHERE `orders`.`status` = 'completed' 
+AND `users`.`created_at` > '2025-08-12') 
+AND `users`.`email` ILIKE '%@company.com' 
+GROUP BY department HAVING COUNT(*) AS user_count > 5 
+ORDER BY user_count DESC LIMIT 10"
+```
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/click_house/client/query_builder.rb

@@ -23,7 +23,10 @@ module ClickHouse
         Arel::Nodes::Or,
         Arel::Nodes::Grouping,
         Arel::Nodes::Matches,
-        Arel::Nodes::DoesNotMatch
+        Arel::Nodes::DoesNotMatch,
+        Arel::Nodes::Division,
+        Arel::Nodes::Multiplication,
+        Arel::Nodes::As
       ].freeze
 
       def initialize(table_name)
@@ -178,6 +181,134 @@ module ClickHouse
         end
       end
 
+      # Aggregation helper methods
+
+      # Creates an AVG aggregate function node
+      # @param column [Symbol, String, Arel::Expressions] The column to average
+      # @return [Arel::Nodes::NamedFunction] The AVG function node
+      # @example Basic average
+      #   query.select(query.avg(:duration)).to_sql
+      #   # => "SELECT avg(`table`.`duration`) FROM `table`"
+      # @example Average with alias
+      #   query.select(query.avg(:price).as('average_price')).to_sql
+      #   # => "SELECT avg(`table`.`price`) AS average_price FROM `table`"
+      def avg(column)
+        column_node = normalize_operand(column)
+        Arel::Nodes::NamedFunction.new('avg', [column_node])
+      end
+
+      # Creates a quantile aggregate function node
+      # @param level [Float] The quantile level (e.g., 0.5 for median)
+      # @param column [Symbol, String, Arel::Expressions] The column to calculate quantile for
+      # @return [Arel::Nodes::NamedFunction] The quantile function node
+      # @example Calculate median (50th percentile)
+      #   query.select(query.quantile(0.5, :response_time)).to_sql
+      #   # => "SELECT quantile(0.5)(`table`.`response_time`) FROM `table`"
+      # @example Calculate 95th percentile with alias
+      #   query.select(query.quantile(0.95, :latency).as('p95')).to_sql
+      #   # => "SELECT quantile(0.95)(`table`.`latency`) AS p95 FROM `table`"
+      def quantile(level, column)
+        column_node = normalize_operand(column)
+        Arel::Nodes::NamedFunction.new("quantile(#{level})", [column_node])
+      end
+
+      # Creates a COUNT aggregate function node
+      # @param column [Symbol, String, Arel::Expressions, nil] The column to count, or nil for COUNT(*)
+      # @return [Arel::Nodes::NamedFunction] The COUNT function node
+      # @example Count all rows
+      #   query.select(query.count).to_sql
+      #   # => "SELECT count() FROM `table`"
+      # @example Count specific column
+      #   query.select(query.count(:id)).to_sql
+      #   # => "SELECT count(`table`.`id`) FROM `table`"
+      def count(column = nil)
+        if column.nil?
+          Arel::Nodes::NamedFunction.new('count', [])
+        else
+          column_node = normalize_operand(column)
+          Arel::Nodes::NamedFunction.new('count', [column_node])
+        end
+      end
+
+      # Creates a countIf aggregate function node
+      # @param condition [Arel::Nodes::Node] The condition to count
+      # @return [Arel::Nodes::NamedFunction] The countIf function node
+      # @raise [ArgumentError] if condition is not an Arel node
+      # @example Count rows matching a condition
+      #   query.select(query.count_if(query.table[:status].eq('active'))).to_sql
+      #   # => "SELECT countIf(`table`.`status` = 'active') FROM `table`"
+      def count_if(condition)
+        raise ArgumentError, "countIf requires an Arel node as condition" unless condition.is_a?(Arel::Nodes::Node)
+
+        Arel::Nodes::NamedFunction.new('countIf', [condition])
+      end
+
+      # Creates a division node with grouping
+      # @param left [Arel::Expressions, Symbol, String, Numeric] The dividend
+      # @param right [Arel::Expressions, Symbol, String, Numeric] The divisor
+      # @return [Arel::Nodes::Grouping] The grouped division node for proper precedence
+      # @example Simple division
+      #   query.select(query.division(:completed, :total)).to_sql
+      #   # => "SELECT (`table`.`completed` / `table`.`total`) FROM `table`"
+      # @example Calculate percentage
+      #   rate = query.division(:success_count, :total_count)
+      #   query.select(query.multiply(rate, 100).as('success_rate')).to_sql
+      #   # => "SELECT ((`table`.`success_count` / `table`.`total_count`) * 100) AS success_rate FROM `table`"
+      def division(left, right)
+        left_node = normalize_operand(left)
+        right_node = normalize_operand(right)
+
+        Arel::Nodes::Grouping.new(Arel::Nodes::Division.new(left_node, right_node))
+      end
+
+      # Creates a multiplication node with grouping
+      # @param left [Arel::Expressions, Symbol, String, Numeric] The left operand
+      # @param right [Arel::Expressions, Symbol, String, Numeric] The right operand
+      # @return [Arel::Nodes::Grouping] The grouped multiplication node for proper precedence
+      # @example Multiply columns
+      #   query.select(query.multiply(:quantity, :unit_price)).to_sql
+      #   # => "SELECT (`table`.`quantity` * `table`.`unit_price`) FROM `table`"
+      # @example Convert to percentage
+      #   query.select(query.multiply(:rate, 100).as('percentage')).to_sql
+      #   # => "SELECT (`table`.`rate` * 100) AS percentage FROM `table`"
+      def multiply(left, right)
+        left_node = normalize_operand(left)
+        right_node = normalize_operand(right)
+
+        Arel::Nodes::Grouping.new(Arel::Nodes::Multiplication.new(left_node, right_node))
+      end
+
+      # Creates an equality node
+      # @param left [Arel::Expressions, Symbol, String] The left side of the comparison
+      # @param right [Arel::Expressions, Symbol, String, Numeric, Boolean] The right side of the comparison
+      # @return [Arel::Nodes::Equality] The equality node
+      # @example Use in WHERE clause
+      #   query.where(query.equality(:status, 'active')).to_sql
+      #   # => "SELECT * FROM `table` WHERE `table`.`status` = 'active'"
+      # @example Use with countIf
+      #   query.select(query.count_if(query.equality(:type, 'premium'))).to_sql
+      #   # => "SELECT countIf(`table`.`type` = 'premium') FROM `table`"
+      def equality(left, right)
+        left_node = normalize_operand(left)
+        right_node = normalize_operand(right)
+        Arel::Nodes::Equality.new(left_node, right_node)
+      end
+
+      # Creates an alias for a node
+      # @param node [Arel::Nodes::Node] The node to alias
+      # @param alias_name [String, Symbol] The alias name
+      # @return [Arel::Nodes::As] The aliased node
+      # @raise [ArgumentError] if node is not an Arel Expression
+      # @example Alias an aggregate function
+      #   avg_node = query.avg(:price)
+      #   query.select(query.as(avg_node, 'average_price')).to_sql
+      #   # => "SELECT avg(`table`.`price`) AS average_price FROM `table`"
+      def as(node, alias_name)
+        raise ArgumentError, "as requires an Arel node" unless node.is_a?(Arel::Expressions)
+
+        node.as(alias_name.to_s)
+      end
+
       def to_sql
         visitor = ClickHouse::Client::ArelVisitor.new(ClickHouse::Client::ArelEngine.new)
         visitor.accept(manager.ast, Arel::Collectors::SQLString.new).value
@@ -193,6 +324,17 @@ module ClickHouse
 
       private
 
+      def normalize_operand(operand)
+        case operand
+        when Arel::Expressions
+          operand
+        when Symbol, String
+          table[operand.to_s]
+        else
+          Arel::Nodes.build_quoted(operand)
+        end
+      end
+
       def validate_constraint_type!(constraint)
         return unless constraint.is_a?(Arel::Nodes::Node) && VALID_NODES.exclude?(constraint.class)
 

data/lib/click_house/client/version.rb

@@ -2,6 +2,6 @@
 
 module ClickHouse
   module Client
-    VERSION = "0.7.0"
+    VERSION = "0.8.0"
   end
 end

data/lib/click_house/client.rb

@@ -77,7 +77,6 @@ module ClickHouse
 
       headers = db.headers.merge(
         'Transfer-Encoding' => 'chunked',
-        'Content-Length' => File.size(io).to_s,
         'Content-Encoding' => 'gzip'
       )
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: click_house-client
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - group::optimize
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-09-09 00:00:00.000000000 Z
+date: 2025-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord