clickhouse-ruby 0.1.0

data/lib/clickhouse_ruby/types/array.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module ClickhouseRuby
+  module Types
+    # Type handler for ClickHouse Array type
+    #
+    # Arrays in ClickHouse are homogeneous - all elements must be the same type.
+    # Supports nested arrays like Array(Array(String)).
+    #
+    # @example
+    #   type = Array.new('Array', element_type: String.new('String'))
+    #   type.cast(['a', 'b', 'c'])  # => ['a', 'b', 'c']
+    #   type.serialize(['a', 'b']) # => "['a', 'b']"
+    #
+    class Array < Base
+      # @return [Base] the type of array elements
+      attr_reader :element_type
+
+      # @param name [String] the type name
+      # @param element_type [Base] the element type
+      def initialize(name, element_type: nil)
+        super(name)
+        @element_type = element_type || Base.new('String')
+      end
+
+      # Converts a Ruby value to an array
+      #
+      # @param value [Object] the value to convert
+      # @return [Array, nil] the array value
+      # @raise [TypeCastError] if the value cannot be converted
+      def cast(value)
+        return nil if value.nil?
+
+        arr = case value
+              when ::Array
+                value
+              when ::String
+                parse_array_string(value)
+              else
+                raise TypeCastError.new(
+                  "Cannot cast #{value.class} to Array",
+                  from_type: value.class.name,
+                  to_type: to_s,
+                  value: value
+                )
+              end
+
+        arr.map { |v| @element_type.cast(v) }
+      end
+
+      # Converts a value from ClickHouse to a Ruby Array
+      #
+      # @param value [Object] the value from ClickHouse
+      # @return [Array, nil] the array value
+      def deserialize(value)
+        return nil if value.nil?
+
+        arr = case value
+              when ::Array
+                value
+              when ::String
+                parse_array_string(value)
+              else
+                [value]
+              end
+
+        arr.map { |v| @element_type.deserialize(v) }
+      end
+
+      # Converts an array to SQL literal
+      #
+      # @param value [Array, nil] the value to serialize
+      # @return [String] the SQL literal
+      def serialize(value)
+        return 'NULL' if value.nil?
+
+        elements = value.map { |v| @element_type.serialize(v) }
+        "[#{elements.join(', ')}]"
+      end
+
+      # Returns the full type string including element type
+      #
+      # @return [String] the type string
+      def to_s
+        "Array(#{@element_type})"
+      end
+
+      private
+
+      # Parses a ClickHouse array string representation
+      #
+      # @param value [String] the string to parse
+      # @return [Array] the parsed array
+      def parse_array_string(value)
+        stripped = value.strip
+
+        # Handle empty array
+        return [] if stripped == '[]'
+
+        # Remove outer brackets
+        unless stripped.start_with?('[') && stripped.end_with?(']')
+          raise TypeCastError.new(
+            "Invalid array format: '#{value}'",
+            from_type: 'String',
+            to_type: to_s,
+            value: value
+          )
+        end
+
+        inner = stripped[1...-1]
+        return [] if inner.strip.empty?
+
+        # Parse elements (handles nested arrays and quoted strings)
+        parse_elements(inner)
+      end
+
+      # Parses comma-separated elements, handling nesting and quotes
+      #
+      # @param str [String] the inner array string
+      # @return [Array] the parsed elements
+      def parse_elements(str)
+        elements = []
+        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
+              elements << parse_element(current.strip)
+              current = ''
+            else
+              current += char
+            end
+          else
+            current += char
+          end
+        end
+
+        # Don't forget the last element
+        elements << parse_element(current.strip) unless current.strip.empty?
+
+        elements
+      end
+
+      # Parses a single element, removing quotes if necessary
+      #
+      # @param str [String] the element string
+      # @return [Object] the parsed element
+      def parse_element(str)
+        # Remove surrounding quotes if present
+        if str.start_with?("'") && str.end_with?("'")
+          str[1...-1].gsub("\\'", "'")
+        elsif str.start_with?('[')
+          # Nested array - let the element type handle it
+          str
+        else
+          str
+        end
+      end
+    end
+  end
+end

data/lib/clickhouse_ruby/types/base.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module ClickhouseRuby
+  module Types
+    # Base class for all ClickHouse types
+    #
+    # Provides the interface for type conversion between Ruby and ClickHouse.
+    # Subclasses implement specific conversion logic.
+    #
+    # @abstract Subclasses should override {#cast}, {#deserialize}, and {#serialize}
+    #
+    class Base
+      # @return [String] the ClickHouse type name
+      attr_reader :name
+
+      # @param name [String] the ClickHouse type name
+      def initialize(name)
+        @name = name
+      end
+
+      # Converts a Ruby value to the appropriate type for this ClickHouse column
+      #
+      # @param value [Object] the value to convert
+      # @return [Object] the converted value
+      def cast(value)
+        value
+      end
+
+      # Converts a value from ClickHouse response format to Ruby
+      #
+      # @param value [Object] the value from ClickHouse
+      # @return [Object] the Ruby value
+      def deserialize(value)
+        value
+      end
+
+      # Converts a Ruby value to ClickHouse SQL literal format
+      #
+      # @param value [Object] the Ruby value
+      # @return [String] the SQL literal
+      def serialize(value)
+        value.to_s
+      end
+
+      # Returns whether NULL values are allowed
+      #
+      # @return [Boolean] true if nullable
+      def nullable?
+        false
+      end
+
+      # Returns the ClickHouse type string
+      #
+      # @return [String] the type string
+      def to_s
+        name
+      end
+
+      # Equality comparison
+      #
+      # @param other [Base] another type
+      # @return [Boolean] true if equal
+      def ==(other)
+        other.is_a?(Base) && other.name == name
+      end
+
+      alias eql? ==
+
+      # Hash code for use in hash keys
+      #
+      # @return [Integer] the hash code
+      def hash
+        name.hash
+      end
+    end
+  end
+end

data/lib/clickhouse_ruby/types/boolean.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module ClickhouseRuby
+  module Types
+    # Type handler for ClickHouse Bool type
+    #
+    # ClickHouse Bool is internally stored as UInt8 (0 or 1)
+    # but can accept various truthy/falsy values.
+    #
+    class Boolean < Base
+      # Values that represent true
+      TRUE_VALUES = [true, 1, '1', 'true', 'TRUE', 'True', 't', 'T', 'yes', 'YES', 'Yes', 'y', 'Y', 'on', 'ON', 'On'].freeze
+
+      # Values that represent false
+      FALSE_VALUES = [false, 0, '0', 'false', 'FALSE', 'False', 'f', 'F', 'no', 'NO', 'No', 'n', 'N', 'off', 'OFF', 'Off'].freeze
+
+      # Converts a Ruby value to a boolean
+      #
+      # @param value [Object] the value to convert
+      # @return [Boolean, nil] the boolean value
+      # @raise [TypeCastError] if the value cannot be interpreted as boolean
+      def cast(value)
+        return nil if value.nil?
+
+        if TRUE_VALUES.include?(value)
+          true
+        elsif FALSE_VALUES.include?(value)
+          false
+        else
+          raise TypeCastError.new(
+            "Cannot cast '#{value}' to Bool",
+            from_type: value.class.name,
+            to_type: name,
+            value: value
+          )
+        end
+      end
+
+      # Converts a value from ClickHouse to Ruby boolean
+      #
+      # @param value [Object] the value from ClickHouse
+      # @return [Boolean, nil] the boolean value
+      def deserialize(value)
+        return nil if value.nil?
+
+        case value
+        when true, 1, '1', 'true'
+          true
+        when false, 0, '0', 'false'
+          false
+        else
+          # Default to truthy evaluation
+          !!value
+        end
+      end
+
+      # Converts a boolean to SQL literal
+      #
+      # @param value [Boolean, nil] the value to serialize
+      # @return [String] the SQL literal (1 or 0)
+      def serialize(value)
+        return 'NULL' if value.nil?
+
+        value ? '1' : '0'
+      end
+    end
+  end
+end

data/lib/clickhouse_ruby/types/date_time.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'date'
+
+module ClickhouseRuby
+  module Types
+    # Type handler for ClickHouse date and datetime types
+    #
+    # Handles: Date, Date32, DateTime, DateTime64
+    #
+    # Date types:
+    # - Date: days since 1970-01-01 (range: 1970-01-01 to 2149-06-06)
+    # - Date32: days since 1970-01-01 (range: 1900-01-01 to 2299-12-31)
+    #
+    # DateTime types:
+    # - DateTime: seconds since 1970-01-01 00:00:00 UTC
+    # - DateTime64(precision): with sub-second precision (0-9 decimal places)
+    #
+    class DateTime < Base
+      # The precision for DateTime64 (nil for other types)
+      # @return [Integer, nil] precision in decimal places
+      attr_reader :precision
+
+      # The timezone for DateTime types
+      # @return [String, nil] timezone name
+      attr_reader :timezone
+
+      def initialize(name, precision: nil, timezone: nil)
+        super(name)
+        @precision = precision
+        @timezone = timezone
+      end
+
+      # Converts a Ruby value to a Time or Date
+      #
+      # @param value [Object] the value to convert
+      # @return [Time, Date, nil] the time/date value
+      # @raise [TypeCastError] if the value cannot be converted
+      def cast(value)
+        return nil if value.nil?
+
+        case value
+        when ::Time
+          date_only? ? value.to_date : value
+        when ::Date
+          date_only? ? value : value.to_time
+        when ::String
+          parse_string(value)
+        when ::Integer
+          # Unix timestamp
+          date_only? ? Time.at(value).to_date : Time.at(value)
+        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 Time or Date
+      #
+      # @param value [Object] the value from ClickHouse
+      # @return [Time, Date, nil] the time/date value
+      def deserialize(value)
+        return nil if value.nil?
+
+        case value
+        when ::Time, ::Date
+          date_only? ? value.to_date : value.to_time
+        when ::String
+          parse_string(value)
+        when ::Integer
+          date_only? ? Time.at(value).to_date : Time.at(value)
+        else
+          parse_string(value.to_s)
+        end
+      end
+
+      # Converts a time/date to SQL literal
+      #
+      # @param value [Time, Date, nil] the value to serialize
+      # @return [String] the SQL literal
+      def serialize(value)
+        return 'NULL' if value.nil?
+
+        if date_only?
+          format_date(value)
+        else
+          format_datetime(value)
+        end
+      end
+
+      # Returns whether this is a date-only type (Date, Date32)
+      #
+      # @return [Boolean] true if date-only
+      def date_only?
+        name.start_with?('Date') && !name.start_with?('DateTime')
+      end
+
+      private
+
+      # Parses a string to a Time or Date
+      #
+      # @param value [String] the string to parse
+      # @return [Time, Date] the parsed value
+      # @raise [TypeCastError] if the string cannot be parsed
+      def parse_string(value)
+        stripped = value.strip
+
+        if stripped.empty?
+          raise TypeCastError.new(
+            "Cannot cast empty string to #{name}",
+            from_type: 'String',
+            to_type: name,
+            value: value
+          )
+        end
+
+        if date_only?
+          ::Date.parse(stripped)
+        else
+          ::Time.parse(stripped)
+        end
+      rescue ArgumentError => e
+        raise TypeCastError.new(
+          "Cannot cast '#{value}' to #{name}: #{e.message}",
+          from_type: 'String',
+          to_type: name,
+          value: value
+        )
+      end
+
+      # Formats a date value for SQL
+      #
+      # @param value [Date, Time] the value to format
+      # @return [String] the formatted SQL literal
+      def format_date(value)
+        date = value.respond_to?(:to_date) ? value.to_date : value
+        "'#{date.strftime('%Y-%m-%d')}'"
+      end
+
+      # Formats a datetime value for SQL
+      #
+      # @param value [Time, Date] the value to format
+      # @return [String] the formatted SQL literal
+      def format_datetime(value)
+        time = value.respond_to?(:to_time) ? value.to_time : value
+
+        if @precision && @precision > 0
+          # DateTime64 with fractional seconds
+          format_str = "%Y-%m-%d %H:%M:%S.%#{@precision}N"
+          "'#{time.strftime(format_str)}'"
+        else
+          # Regular DateTime
+          "'#{time.strftime('%Y-%m-%d %H:%M:%S')}'"
+        end
+      end
+    end
+  end
+end

data/lib/clickhouse_ruby/types/float.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module ClickhouseRuby
+  module Types
+    # Type handler for ClickHouse floating point types
+    #
+    # Handles: Float32, Float64
+    #
+    # Note: ClickHouse also supports special values: inf, -inf, nan
+    #
+    class Float < Base
+      # Converts a Ruby value to a float
+      #
+      # @param value [Object] the value to convert
+      # @return [Float, nil] the float value
+      # @raise [TypeCastError] if the value cannot be converted
+      def cast(value)
+        return nil if value.nil?
+
+        case value
+        when ::Float
+          value
+        when ::Integer
+          value.to_f
+        when ::String
+          parse_string(value)
+        when ::BigDecimal
+          value.to_f
+        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 Float
+      #
+      # @param value [Object] the value from ClickHouse
+      # @return [Float, nil] the float value
+      def deserialize(value)
+        return nil if value.nil?
+
+        case value
+        when ::Float
+          value
+        when ::String
+          parse_string(value)
+        else
+          value.to_f
+        end
+      end
+
+      # Converts a float to SQL literal
+      #
+      # @param value [Float, nil] the value to serialize
+      # @return [String] the SQL literal
+      def serialize(value)
+        return 'NULL' if value.nil?
+
+        if value.nan?
+          'nan'
+        elsif value.infinite? == 1
+          'inf'
+        elsif value.infinite? == -1
+          '-inf'
+        else
+          value.to_s
+        end
+      end
+
+      private
+
+      # Parses a string to a float
+      #
+      # @param value [String] the string to parse
+      # @return [Float] the parsed float
+      # @raise [TypeCastError] if the string is not a valid float
+      def parse_string(value)
+        stripped = value.strip.downcase
+
+        # Handle special values
+        case stripped
+        when 'inf', '+inf', 'infinity', '+infinity'
+          ::Float::INFINITY
+        when '-inf', '-infinity'
+          -::Float::INFINITY
+        when 'nan'
+          ::Float::NAN
+        else
+          # Handle empty strings
+          if stripped.empty?
+            raise TypeCastError.new(
+              "Cannot cast empty string to #{name}",
+              from_type: 'String',
+              to_type: name,
+              value: value
+            )
+          end
+
+          Float(stripped)
+        end
+      rescue ArgumentError
+        raise TypeCastError.new(
+          "Cannot cast '#{value}' to #{name}",
+          from_type: 'String',
+          to_type: name,
+          value: value
+        )
+      end
+    end
+  end
+end