clickhouse-rb 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ccbd22754bea20c9ca9fed064ef2b4e7a5cf936b9e6c8c3f819f732adfc25e7
-  data.tar.gz: 9537ffae5678fa0bf7ffbdd7b0cbb505aa66a8471072271765e98e99456a7f9d
+  metadata.gz: b3665b6f44472615341970c7b6169eaa3e54e7df0132ad866d24b8e24cb170df
+  data.tar.gz: b5948f2b40a4e969ed35daf92dfb24f3da23215fa113b86b168c3ab911f20335
 SHA512:
-  metadata.gz: a289ee47e7d21efdf378737f101dca5efb11a0938ff41b0be804a39a2b0e2d6a694a78e57b0037d65a0e9fe136042d32f3d4377f5320bf9f63d0119d7bb51d33
-  data.tar.gz: e836803b9664e2e5548af277978ed7170b8f18e79b767d908f2bbe8005464bc016fb6261bec5fa84d60774c632b6a42578e1d56899a63f90309c49941050750f
+  metadata.gz: 777e4c17a2d3278fb7a1221ed16f5d4ea01f16eeaac31c5e24ba52f81a2b5dc81613ea379c1e722b9d75f55c3850f6761a1ad5e45265e3be4a2199449777f68c
+  data.tar.gz: af8ac7a565c217142e5234d4d83dc9caf70cf2aca86714985b76155ecf8434076f27b9716794f09090b392033a49a7b14097645bc8b180190d089df4e45616c5

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## Unreleased
+
+## [0.3.0] - 2025-12-31
+
+- Make responses more user-friendly ([#1](https://github.com/kukicola/clickhouse-rb/pull/1))
+
 ## [0.2.0] - 2025-12-28
 
 - Added instrumentation support with configurable `instrumenter` (defaults to `NullInstrumenter`)

data/README.md

@@ -51,10 +51,10 @@ end
 
 ```ruby
 conn = Clickhouse::Connection.new
-response = conn.query("SELECT * FROM users WHERE id = 1")
+response = conn.query("SELECT id, name FROM users WHERE active = true")
 
-response.rows.each do |row|
-  puts row.inspect
+response.each do |row|
+  puts "#{row[:id]}: #{row[:name]}"
 end
 ```
 
@@ -83,19 +83,29 @@ end
 
 ### Working with Results
 
+Response objects implement `Enumerable`, allowing direct iteration:
+
 ```ruby
 response = conn.query("SELECT id, name, created_at FROM users")
 
+# Iterate over rows as hashes with symbol keys
+response.each { |row| puts row[:name] }
+
+# Use any Enumerable method
+response.map { |row| row[:id] }
+response.select { |row| row[:id] > 10 }
+response.first   # => {id: 1, name: "Alice", created_at: 2024-01-01 00:00:00 UTC}
+
 # Access raw rows (arrays)
 response.rows      # => [[1, "Alice", 2024-01-01 00:00:00 UTC], ...]
-response.columns   # => ["id", "name", "created_at"]
-response.types     # => ["UInt64", "String", "DateTime"]
+response.columns   # => [:id, :name, :created_at]
+response.types     # => [:UInt64, :String, :DateTime]
 
 # Convert to array of hashes
-response.to_a      # => [{"id" => 1, "name" => "Alice", ...}, ...]
+response.to_a      # => [{id: 1, name: "Alice", ...}, ...]
 
-# Query summary from ClickHouse
-response.summary   # => {"read_rows" => "1", "read_bytes" => "42", ...}
+# Query summary from ClickHouse (symbol keys)
+response.summary   # => {read_rows: "1", read_bytes: "42", ...}
 ```
 
 ### Query Parameters

data/lib/clickhouse/http_transport.rb

@@ -36,7 +36,7 @@ module Clickhouse
       query_params = {database: @config.database}.merge(options[:params] || {})
       response = @http_client.post("/", params: query_params, body: sql, headers: @default_headers)
 
-      summary = JSON.parse(response.headers["X-ClickHouse-Summary"])
+      summary = JSON.parse(response.headers["X-ClickHouse-Summary"], symbolize_names: true)
 
       raise QueryError, response.body.to_s unless response.status.success?
 

data/lib/clickhouse/native_format_parser.rb

@@ -46,8 +46,8 @@ module Clickhouse
         col_type = read_string
 
         if @columns.length < num_columns
-          @columns << col_name
-          @types << col_type
+          @columns << col_name.to_sym
+          @types << col_type.to_sym
         end
 
         columns_data << read_column(col_type, num_rows)
@@ -65,14 +65,14 @@ module Clickhouse
       when "UInt16" then read_uint16_column(num_rows)
       when "UInt32" then read_uint32_column(num_rows)
       when "UInt64" then read_uint64_column(num_rows)
-      when "UInt128" then Array.new(num_rows) { read_uint128 }
-      when "UInt256" then Array.new(num_rows) { read_uint256 }
+      when "UInt128" then read_uint128_column(num_rows)
+      when "UInt256" then read_uint256_column(num_rows)
       when "Int8" then read_int8_column(num_rows)
       when "Int16" then read_int16_column(num_rows)
       when "Int32" then read_int32_column(num_rows)
       when "Int64" then read_int64_column(num_rows)
-      when "Int128" then Array.new(num_rows) { read_int128 }
-      when "Int256" then Array.new(num_rows) { read_int256 }
+      when "Int128" then read_int128_column(num_rows)
+      when "Int256" then read_int256_column(num_rows)
 
       # Floats
       when "Float32" then read_float32_column(num_rows)
@@ -82,7 +82,7 @@ module Clickhouse
       when "Bool" then read_bool_column(num_rows)
 
       # Strings
-      when "String" then Array.new(num_rows) { read_string }
+      when "String" then read_string_column(num_rows)
       when /^FixedString\((\d+)\)$/ then read_fixed_string_column($1.to_i, num_rows)
 
       # Dates and Times
@@ -92,11 +92,11 @@ module Clickhouse
       when /^DateTime64\((\d+)(?:,.*)?\)$/ then read_datetime64_column($1.to_i, num_rows)
 
       # UUID
-      when "UUID" then Array.new(num_rows) { read_uuid }
+      when "UUID" then read_uuid_column(num_rows)
 
       # IP addresses
-      when "IPv4" then Array.new(num_rows) { read_ipv4 }
-      when "IPv6" then Array.new(num_rows) { read_ipv6 }
+      when "IPv4" then read_ipv4_column(num_rows)
+      when "IPv6" then read_ipv6_column(num_rows)
 
       # Decimals - ClickHouse always returns Decimal(precision, scale)
       when /^Decimal\((\d+),\s*(\d+)\)$/ then read_decimal_column($1.to_i, $2.to_i, num_rows)
@@ -145,6 +145,14 @@ module Clickhouse
       @reader.read(num_rows * 8).unpack("Q<*")
     end
 
+    def read_uint128_column(num_rows)
+      Array.new(num_rows) { read_le_bytes(16) }
+    end
+
+    def read_uint256_column(num_rows)
+      Array.new(num_rows) { read_le_bytes(32) }
+    end
+
     def read_int8_column(num_rows)
       @reader.read(num_rows).unpack("c*")
     end
@@ -161,6 +169,14 @@ module Clickhouse
       @reader.read(num_rows * 8).unpack("q<*")
     end
 
+    def read_int128_column(num_rows)
+      Array.new(num_rows) { read_signed_le_bytes(16) }
+    end
+
+    def read_int256_column(num_rows)
+      Array.new(num_rows) { read_signed_le_bytes(32) }
+    end
+
     def read_float32_column(num_rows)
       @reader.read(num_rows * 4).unpack("e*")
     end
@@ -173,6 +189,10 @@ module Clickhouse
       @reader.read(num_rows).bytes.map { |b| b == 1 }
     end
 
+    def read_string_column(num_rows)
+      Array.new(num_rows) { read_string }
+    end
+
     def read_fixed_string_column(length, num_rows)
       Array.new(num_rows) { @reader.read(length).force_encoding(Encoding::UTF_8) }
     end
@@ -197,6 +217,18 @@ module Clickhouse
       end
     end
 
+    def read_uuid_column(num_rows)
+      Array.new(num_rows) { read_uuid }
+    end
+
+    def read_ipv4_column(num_rows)
+      Array.new(num_rows) { read_ipv4 }
+    end
+
+    def read_ipv6_column(num_rows)
+      Array.new(num_rows) { read_ipv6 }
+    end
+
     def read_decimal_column(precision, scale, num_rows)
       divisor = 10**scale
       if precision <= 9
@@ -230,10 +262,6 @@ module Clickhouse
     end
 
     def read_uint64 = @reader.read(8).unpack1("Q<")
-    def read_uint128 = read_le_bytes(16)
-    def read_uint256 = read_le_bytes(32)
-    def read_int128 = read_signed_le_bytes(16)
-    def read_int256 = read_signed_le_bytes(32)
 
     def read_uuid
       first_half = @reader.read(8).bytes.reverse

data/lib/clickhouse/response.rb

@@ -5,20 +5,27 @@ module Clickhouse
   #
   # @example
   #   response = conn.query("SELECT id, name FROM users")
-  #   response.columns   # => ["id", "name"]
+  #   response.columns   # => [:id, :name]
   #   response.rows      # => [[1, "Alice"], [2, "Bob"]]
-  #   response.to_a      # => [{"id" => 1, "name" => "Alice"}, ...]
+  #   response.each { |row| puts row[:name] }
   Response = Data.define(:columns, :types, :rows, :summary) do
-    # @param columns [Array<String>] column names
-    # @param types [Array<String>] column types
+    include Enumerable
+
+    # @param columns [Array<Symbol>] column names
+    # @param types [Array<Symbol>] column types
     # @param rows [Array<Array>] row data
-    # @param summary [Hash, nil] ClickHouse query summary
+    # @param summary [Hash, nil] ClickHouse query summary with symbol keys
     def initialize(columns: [], types: [], rows: [], summary: nil)
       super
     end
 
-    # Converts rows to an array of hashes.
-    # @return [Array<Hash>] rows as hashes with column names as keys
-    def to_a = rows.map { |row| columns.zip(row).to_h }
+    # Iterates over rows as hashes with symbol keys.
+    # @yield [Hash] each row as a hash
+    # @return [Enumerator] if no block given
+    def each
+      return to_enum(:each) unless block_given?
+
+      rows.each { |row| yield columns.zip(row).to_h }
+    end
   end
 end

data/lib/clickhouse/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Clickhouse
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clickhouse-rb
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Karol Bąk