clickhouse-ruby 0.1.0

data/lib/clickhouse_ruby/types/integer.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module ClickhouseRuby
+  module Types
+    # Type handler for ClickHouse integer types
+    #
+    # Handles: Int8, Int16, Int32, Int64, Int128, Int256
+    #          UInt8, UInt16, UInt32, UInt64, UInt128, UInt256
+    #
+    # ClickHouse integers are exact - no floating point issues.
+    # Large integers (128, 256 bit) use Ruby's BigInteger.
+    #
+    class Integer < Base
+      # Size limits for each integer type
+      LIMITS = {
+        'Int8' => { min: -128, max: 127 },
+        'Int16' => { min: -32_768, max: 32_767 },
+        'Int32' => { min: -2_147_483_648, max: 2_147_483_647 },
+        'Int64' => { min: -9_223_372_036_854_775_808, max: 9_223_372_036_854_775_807 },
+        'Int128' => { min: -(2**127), max: (2**127) - 1 },
+        'Int256' => { min: -(2**255), max: (2**255) - 1 },
+        'UInt8' => { min: 0, max: 255 },
+        'UInt16' => { min: 0, max: 65_535 },
+        'UInt32' => { min: 0, max: 4_294_967_295 },
+        'UInt64' => { min: 0, max: 18_446_744_073_709_551_615 },
+        'UInt128' => { min: 0, max: (2**128) - 1 },
+        'UInt256' => { min: 0, max: (2**256) - 1 }
+      }.freeze
+
+      # Converts a Ruby value to an integer
+      #
+      # @param value [Object] the value to convert
+      # @return [Integer, nil] the integer value
+      # @raise [TypeCastError] if the value cannot be converted
+      def cast(value)
+        return nil if value.nil?
+
+        case value
+        when ::Integer
+          validate_range!(value)
+          value
+        when ::Float
+          int_value = value.to_i
+          validate_range!(int_value)
+          int_value
+        when ::String
+          int_value = parse_string(value)
+          validate_range!(int_value)
+          int_value
+        when true
+          1
+        when false
+          0
+        else
+          raise TypeCastError.new(
+            "Cannot cast #{value.class} to #{name}",
+            from_type: value.class.name,
+            to_type: name,
+            value: value
+          )
+        end
+      end
+
+      # Converts a value from ClickHouse to Ruby Integer
+      #
+      # @param value [Object] the value from ClickHouse
+      # @return [Integer, nil] the integer value
+      def deserialize(value)
+        return nil if value.nil?
+
+        case value
+        when ::Integer
+          value
+        when ::String
+          parse_string(value)
+        when ::Float
+          value.to_i
+        else
+          value.to_i
+        end
+      end
+
+      # Converts an integer to SQL literal
+      #
+      # @param value [Integer, nil] the value to serialize
+      # @return [String] the SQL literal
+      def serialize(value)
+        return 'NULL' if value.nil?
+
+        value.to_s
+      end
+
+      # Returns whether this is an unsigned integer type
+      #
+      # @return [Boolean] true if unsigned
+      def unsigned?
+        name.start_with?('U')
+      end
+
+      # Returns the bit size of this integer type
+      #
+      # @return [Integer] the bit size (8, 16, 32, 64, 128, or 256)
+      def bit_size
+        name.gsub(/[^0-9]/, '').to_i
+      end
+
+      private
+
+      # Parses a string to an integer
+      #
+      # @param value [String] the string to parse
+      # @return [Integer] the parsed integer
+      # @raise [TypeCastError] if the string is not a valid integer
+      def parse_string(value)
+        stripped = value.strip
+
+        # Handle empty strings
+        if stripped.empty?
+          raise TypeCastError.new(
+            "Cannot cast empty string to #{name}",
+            from_type: 'String',
+            to_type: name,
+            value: value
+          )
+        end
+
+        # Use Integer() for strict parsing
+        Integer(stripped)
+      rescue ArgumentError
+        raise TypeCastError.new(
+          "Cannot cast '#{value}' to #{name}",
+          from_type: 'String',
+          to_type: name,
+          value: value
+        )
+      end
+
+      # Validates that a value is within the type's range
+      #
+      # @param value [Integer] the value to validate
+      # @raise [TypeCastError] if the value is out of range
+      def validate_range!(value)
+        limits = LIMITS[name]
+        return unless limits  # Unknown type, skip validation
+
+        if value < limits[:min] || value > limits[:max]
+          raise TypeCastError.new(
+            "Value #{value} is out of range for #{name} (#{limits[:min]}..#{limits[:max]})",
+            from_type: value.class.name,
+            to_type: name,
+            value: value
+          )
+        end
+      end
+    end
+  end
+end

data/lib/clickhouse_ruby/types/low_cardinality.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ClickhouseRuby
+  module Types
+    # Type handler for ClickHouse LowCardinality type
+    #
+    # LowCardinality is an optimization wrapper that stores string values
+    # in a dictionary for better compression and performance.
+    #
+    # @example
+    #   type = LowCardinality.new('LowCardinality', element_type: String.new('String'))
+    #   type.cast('hello')
+    #   type.serialize('hello') # => "'hello'"
+    #
+    class LowCardinality < Base
+      # @return [Base] the wrapped type
+      attr_reader :element_type
+
+      # @param name [String] the type name
+      # @param element_type [Base] the wrapped type
+      def initialize(name, element_type: nil)
+        super(name)
+        @element_type = element_type || Base.new('String')
+      end
+
+      # Converts a Ruby value using the wrapped type
+      #
+      # @param value [Object] the value to convert
+      # @return [Object] the converted value
+      def cast(value)
+        @element_type.cast(value)
+      end
+
+      # Converts a value from ClickHouse using the wrapped type
+      #
+      # @param value [Object] the value from ClickHouse
+      # @return [Object] the Ruby value
+      def deserialize(value)
+        @element_type.deserialize(value)
+      end
+
+      # Converts a value to SQL literal using the wrapped type
+      #
+      # @param value [Object] the value to serialize
+      # @return [String] the SQL literal
+      def serialize(value)
+        @element_type.serialize(value)
+      end
+
+      # Returns the full type string
+      #
+      # @return [String] the type string
+      def to_s
+        "LowCardinality(#{@element_type})"
+      end
+    end
+  end
+end

data/lib/clickhouse_ruby/types/map.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+module ClickhouseRuby
+  module Types
+    # Type handler for ClickHouse Map type
+    #
+    # Maps are key-value collections where all keys share one type
+    # and all values share another type.
+    #
+    # @example
+    #   type = Map.new('Map', arg_types: [String.new('String'), Integer.new('UInt64')])
+    #   type.cast({'a' => 1, 'b' => 2})
+    #   type.serialize({'a' => 1}) # => "{'a': 1}"
+    #
+    class Map < Base
+      # @return [Base] the key type
+      attr_reader :key_type
+
+      # @return [Base] the value type
+      attr_reader :value_type
+
+      # @param name [String] the type name
+      # @param arg_types [Array<Base>] array of [key_type, value_type]
+      def initialize(name, arg_types: nil)
+        super(name)
+        arg_types ||= [Base.new('String'), Base.new('String')]
+        @key_type = arg_types[0]
+        @value_type = arg_types[1] || Base.new('String')
+      end
+
+      # Converts a Ruby value to a map (Hash)
+      #
+      # @param value [Object] the value to convert
+      # @return [Hash, nil] the hash value
+      # @raise [TypeCastError] if the value cannot be converted
+      def cast(value)
+        return nil if value.nil?
+
+        hash = case value
+               when ::Hash
+                 value
+               when ::String
+                 parse_map_string(value)
+               else
+                 raise TypeCastError.new(
+                   "Cannot cast #{value.class} to Map",
+                   from_type: value.class.name,
+                   to_type: to_s,
+                   value: value
+                 )
+               end
+
+        hash.transform_keys { |k| @key_type.cast(k) }
+            .transform_values { |v| @value_type.cast(v) }
+      end
+
+      # Converts a value from ClickHouse to a Ruby Hash
+      #
+      # @param value [Object] the value from ClickHouse
+      # @return [Hash, nil] the hash value
+      def deserialize(value)
+        return nil if value.nil?
+
+        hash = case value
+               when ::Hash
+                 value
+               when ::String
+                 parse_map_string(value)
+               else
+                 { value => nil }
+               end
+
+        hash.transform_keys { |k| @key_type.deserialize(k) }
+            .transform_values { |v| @value_type.deserialize(v) }
+      end
+
+      # Converts a hash to SQL literal
+      #
+      # @param value [Hash, nil] the value to serialize
+      # @return [String] the SQL literal
+      def serialize(value)
+        return 'NULL' if value.nil?
+
+        pairs = value.map do |k, v|
+          "#{@key_type.serialize(k)}: #{@value_type.serialize(v)}"
+        end
+
+        "{#{pairs.join(', ')}}"
+      end
+
+      # Returns the full type string including key and value types
+      #
+      # @return [String] the type string
+      def to_s
+        "Map(#{@key_type}, #{@value_type})"
+      end
+
+      private
+
+      # Parses a ClickHouse map string representation
+      #
+      # @param value [String] the string to parse
+      # @return [Hash] the parsed hash
+      def parse_map_string(value)
+        stripped = value.strip
+
+        # Handle empty map
+        return {} if stripped == '{}'
+
+        # Remove outer braces
+        unless stripped.start_with?('{') && stripped.end_with?('}')
+          raise TypeCastError.new(
+            "Invalid map format: '#{value}'",
+            from_type: 'String',
+            to_type: to_s,
+            value: value
+          )
+        end
+
+        inner = stripped[1...-1]
+        return {} if inner.strip.empty?
+
+        # Parse key-value pairs
+        parse_pairs(inner)
+      end
+
+      # Parses comma-separated key:value pairs
+      #
+      # @param str [String] the inner map string
+      # @return [Hash] the parsed pairs
+      def parse_pairs(str)
+        result = {}
+        current = ''
+        depth = 0
+        in_string = false
+        escape_next = false
+
+        str.each_char do |char|
+          if escape_next
+            current += char
+            escape_next = false
+            next
+          end
+
+          case char
+          when '\\'
+            escape_next = true
+            current += char
+          when "'"
+            in_string = !in_string
+            current += char
+          when '{', '[', '('
+            depth += 1 unless in_string
+            current += char
+          when '}', ']', ')'
+            depth -= 1 unless in_string
+            current += char
+          when ','
+            if depth.zero? && !in_string
+              key, value = parse_pair(current.strip)
+              result[key] = value
+              current = ''
+            else
+              current += char
+            end
+          else
+            current += char
+          end
+        end
+
+        # Don't forget the last pair
+        unless current.strip.empty?
+          key, value = parse_pair(current.strip)
+          result[key] = value
+        end
+
+        result
+      end
+
+      # Parses a single key:value pair
+      #
+      # @param str [String] the pair string
+      # @return [Array] [key, value]
+      def parse_pair(str)
+        # Find the colon separator (not inside quotes or nested structures)
+        colon_idx = find_separator(str, ':')
+
+        if colon_idx.nil?
+          raise TypeCastError.new(
+            "Invalid map pair format: '#{str}'",
+            from_type: 'String',
+            to_type: to_s,
+            value: str
+          )
+        end
+
+        key = parse_value(str[0...colon_idx].strip)
+        value = parse_value(str[(colon_idx + 1)..].strip)
+
+        [key, value]
+      end
+
+      # Finds the index of a separator character, ignoring nested structures
+      #
+      # @param str [String] the string to search
+      # @param sep [String] the separator character
+      # @return [Integer, nil] the index or nil if not found
+      def find_separator(str, sep)
+        depth = 0
+        in_string = false
+        escape_next = false
+
+        str.each_char.with_index do |char, idx|
+          if escape_next
+            escape_next = false
+            next
+          end
+
+          case char
+          when '\\'
+            escape_next = true
+          when "'"
+            in_string = !in_string
+          when '{', '[', '('
+            depth += 1 unless in_string
+          when '}', ']', ')'
+            depth -= 1 unless in_string
+          when sep
+            return idx if depth.zero? && !in_string
+          end
+        end
+
+        nil
+      end
+
+      # Parses a value, removing quotes if necessary
+      #
+      # @param str [String] the value string
+      # @return [Object] the parsed value
+      def parse_value(str)
+        if str.start_with?("'") && str.end_with?("'")
+          str[1...-1].gsub("\\'", "'")
+        else
+          str
+        end
+      end
+    end
+  end
+end

data/lib/clickhouse_ruby/types/nullable.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module ClickhouseRuby
+  module Types
+    # Type handler for ClickHouse Nullable type
+    #
+    # Nullable wraps another type to allow NULL values.
+    # Without Nullable, ClickHouse columns cannot contain NULL.
+    #
+    # @example
+    #   type = Nullable.new('Nullable', element_type: Integer.new('Int32'))
+    #   type.cast(nil)   # => nil
+    #   type.cast(42)    # => 42
+    #   type.nullable?   # => true
+    #
+    class Nullable < Base
+      # @return [Base] the wrapped type
+      attr_reader :element_type
+
+      # @param name [String] the type name
+      # @param element_type [Base] the wrapped type
+      def initialize(name, element_type: nil)
+        super(name)
+        @element_type = element_type || Base.new('String')
+      end
+
+      # Converts a Ruby value, allowing nil
+      #
+      # @param value [Object] the value to convert
+      # @return [Object, nil] the converted value
+      def cast(value)
+        return nil if value.nil?
+
+        @element_type.cast(value)
+      end
+
+      # Converts a value from ClickHouse, allowing nil
+      #
+      # @param value [Object] the value from ClickHouse
+      # @return [Object, nil] the Ruby value
+      def deserialize(value)
+        return nil if value.nil?
+        return nil if value.is_a?(::String) && value == '\\N'
+
+        @element_type.deserialize(value)
+      end
+
+      # Converts a value to SQL literal, handling NULL
+      #
+      # @param value [Object, nil] the value to serialize
+      # @return [String] the SQL literal
+      def serialize(value)
+        return 'NULL' if value.nil?
+
+        @element_type.serialize(value)
+      end
+
+      # Returns true - this type allows NULL
+      #
+      # @return [Boolean] true
+      def nullable?
+        true
+      end
+
+      # Returns the full type string
+      #
+      # @return [String] the type string
+      def to_s
+        "Nullable(#{@element_type})"
+      end
+    end
+  end
+end