clickhouse-sql 0.1.0

data/lib/clickhouse/sql/join.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module ClickHouse
+  module SQL
+    class Join
+      include Part
+
+      # Builds a rendered JOIN clause.
+      #
+      # @param table [String, Symbol, ClickHouse::SQL::Part] Trusted table expression.
+      # @param type [String] JOIN type, for example `INNER` or `LEFT`.
+      # @param as [String, Symbol, nil] Optional table alias; only valid for
+      #   string/symbol table names — a ClickHouse::SQL::Table handle owns its alias.
+      # @param final [Boolean] Whether to append ClickHouse `FINAL`.
+      # @param on [String, ClickHouse::SQL::Part, Array] ON conditions.
+      # @return [ClickHouse::SQL::Join] A validated JOIN clause.
+      def initialize(table, type:, as: nil, final: false, on:)
+        @table = ClickHouse::SQL.coerce_raw_expression(table)
+        @type = type
+        @alias_name = ClickHouse::SQL.resolve_table_alias(table, as)
+        @final = final
+        @on = Array(on).flatten.compact.map { |condition| ClickHouse::SQL.coerce_expression(condition) }
+        raise Error, "JOIN requires at least one ON condition" if @on.empty?
+      end
+
+      # Renders the JOIN with ClickHouse typed placeholders intact.
+      #
+      # @return [String] SQL JOIN clause.
+      def to_sql
+        render(redacted: false)
+      end
+
+      # Renders the JOIN with typed placeholders replaced by bind markers.
+      #
+      # @param bind_index_manager [ClickHouse::SQL::BindIndexManager] Redacted bind index state.
+      # @return [String] Redacted SQL JOIN clause.
+      def to_redacted_sql(bind_index_manager)
+        render(redacted: true, bind_index_manager:)
+      end
+
+      # Returns typed placeholder values used by the JOIN.
+      #
+      # @return [Hash{Symbol=>Object}] Placeholder values keyed by name.
+      def placeholders
+        ClickHouse::SQL.collect_placeholders([@table, *@on])
+      end
+
+      # Returns ClickHouse placeholder types used by the JOIN.
+      #
+      # @return [Hash{Symbol=>String}] Placeholder types keyed by name.
+      def placeholder_types
+        ClickHouse::SQL.collect_placeholder_types([@table, *@on])
+      end
+
+      private
+
+      def render(redacted:, bind_index_manager: ClickHouse::SQL::BindIndexManager.new)
+        table_sql = ClickHouse::SQL.render_part(@table, redacted:, bind_index_manager:)
+        join_sql = +"#{@type} JOIN #{table_sql}"
+        join_sql << " FINAL" if @final
+        join_sql << " AS #{ClickHouse::SQL.validate_alias!(@alias_name)}" if @alias_name
+        join_sql << " ON "
+        # Each condition is parenthesized so a condition containing a top-level
+        # OR cannot change the meaning of the AND-joined ON clause.
+        join_sql << @on.map { |condition| "(#{ClickHouse::SQL.render_part(condition, redacted:, bind_index_manager:)})" }.join(" AND ")
+        join_sql
+      end
+    end
+  end
+end

data/lib/clickhouse/sql/part.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ClickHouse
+  module SQL
+    # Internal protocol for renderable ClickHouse::SQL builder parts.
+    module Part
+      # Renders this part with typed placeholders intact.
+      #
+      # @return [String] SQL text.
+      def to_sql
+        raise NotImplementedError
+      end
+
+      # Renders this part with typed placeholders replaced by bind markers.
+      #
+      # @param bind_index_manager [ClickHouse::SQL::BindIndexManager] Redacted bind index state.
+      # @return [String] Redacted SQL text.
+      def to_redacted_sql(bind_index_manager = ClickHouse::SQL::BindIndexManager.new)
+        raise NotImplementedError
+      end
+
+      # Returns typed placeholder values used by this part.
+      #
+      # @return [Hash{Symbol=>Object}] Placeholder values keyed by name.
+      def placeholders
+        {}
+      end
+
+      # Returns ClickHouse placeholder types used by this part.
+      #
+      # @return [Hash{Symbol=>String}] Placeholder types keyed by name.
+      def placeholder_types
+        {}
+      end
+    end
+  end
+end

data/lib/clickhouse/sql/placeholder.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ClickHouse
+  module SQL
+    # A parsed `{name}`, `{name:Type}`, or anonymous `{}` placeholder from a
+    # SQL fragment.
+    #
+    # @!attribute raw
+    #   @return [String] The placeholder text including braces.
+    # @!attribute name
+    #   @return [String, nil] Placeholder name, or nil for anonymous `{}` slots.
+    # @!attribute type
+    #   @return [String, nil] ClickHouse type text, or nil for fragment slots.
+    # @!attribute begin_pos
+    #   @return [Integer] Start offset in the source SQL.
+    # @!attribute end_pos
+    #   @return [Integer] End offset in the source SQL.
+    Placeholder = Struct.new(:raw, :name, :type, :begin_pos, :end_pos, keyword_init: true) do
+      # Returns whether this placeholder is a ClickHouse typed value.
+      #
+      # @return [Boolean] True for `{name:Type}`, false for fragment slots.
+      def typed?
+        !ValueNormalization.blank_string?(type)
+      end
+
+      # Returns whether this placeholder is an anonymous `{}` fragment slot.
+      #
+      # @return [Boolean] True for `{}`, false for named placeholders.
+      def anonymous?
+        name.nil?
+      end
+
+      # Returns the placeholder name as a symbol.
+      #
+      # @return [Symbol, nil] Symbolized placeholder name, or nil for anonymous slots.
+      def name_sym
+        name&.to_sym
+      end
+    end
+  end
+end

data/lib/clickhouse/sql/placeholder_type.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module ClickHouse
+  module SQL
+    class PlaceholderType
+      # @return [String] Raw ClickHouse placeholder type text.
+      attr_reader :raw
+
+      # @return [String] Whitespace-normalized ClickHouse placeholder type text.
+      attr_reader :normalized
+
+      # Parses and normalizes a ClickHouse placeholder type.
+      #
+      # @param raw [String, #to_s] ClickHouse type text from a placeholder.
+      # @return [ClickHouse::SQL::PlaceholderType] Parsed placeholder type.
+      def initialize(raw)
+        @raw = raw.to_s.strip
+        @normalized = ClickHouse::SQL.normalize_placeholder_type(@raw)
+      end
+
+      # Validates and normalizes a Ruby value for this ClickHouse type.
+      #
+      # @param value [Object] Ruby value to validate for the placeholder type.
+      # @return [Object] Value normalized for ClickHouse parameter serialization.
+      def validate_and_normalize(value)
+        base, arguments = parse_base_and_arguments(raw)
+
+        if value.nil?
+          return nil if nullable?
+
+          raise Error, "#{raw} placeholder does not accept nil"
+        end
+
+        case base.downcase
+        when "array"
+          validate_array(value, arguments)
+        when "nullable", "lowcardinality"
+          validate_wrapped(value, arguments)
+        when "uuid"
+          validate_uuid(value)
+        when "identifier"
+          validate_identifier(value)
+        when "string", "fixedstring"
+          validate_string(value)
+        when "date"
+          validate_date(value)
+        when "datetime"
+          validate_datetime(value, timezone: timezone_argument(arguments.first))
+        when "datetime64"
+          validate_datetime64(value, arguments)
+        when "integer"
+          validate_integer(value)
+        when /\Auint(\d+)\z/
+          validate_sized_integer(value, bits: Regexp.last_match(1).to_i, unsigned: true)
+        when /\Aint(\d+)\z/
+          validate_sized_integer(value, bits: Regexp.last_match(1).to_i, unsigned: false)
+        when "float32", "float64"
+          validate_numeric(value)
+        else
+          value
+        end
+      end
+
+      # Whether this type accepts nil, recursing through LowCardinality
+      # wrappers since ClickHouse only permits the LowCardinality(Nullable(T))
+      # nesting order.
+      #
+      # @return [Boolean] True if nil is a valid value for this type.
+      def nullable?
+        base, arguments = parse_base_and_arguments(raw)
+        return true if base.casecmp?("Nullable")
+        return self.class.new(arguments.first).nullable? if base.casecmp?("LowCardinality") && !arguments.first.to_s.empty?
+
+        false
+      end
+
+      private
+
+      def parse_base_and_arguments(type)
+        match = type.match(/\A\s*([A-Za-z][A-Za-z0-9]*)\s*(?:\((.*)\))?\s*\z/m)
+        raise Error, "Invalid ClickHouse placeholder type: #{type.inspect}" unless match
+
+        [match[1], ClickHouse::SQL.split_top_level_arguments(match[2].to_s)]
+      end
+
+      def validate_array(value, arguments)
+        raise Error, "Array placeholder requires an Array, got #{value.class}" unless value.is_a?(Array)
+
+        inner_type = arguments.first
+        raise Error, "Array placeholder requires an inner type" if ValueNormalization.blank_string?(inner_type)
+
+        inner = self.class.new(inner_type)
+        value.map { |item| inner.validate_and_normalize(item) }
+      end
+
+      def validate_wrapped(value, arguments)
+        inner_type = arguments.first
+        raise Error, "#{raw} placeholder requires an inner type" if ValueNormalization.blank_string?(inner_type)
+
+        self.class.new(inner_type).validate_and_normalize(value)
+      end
+
+      def validate_uuid(value)
+        string = value.to_s
+        unless string.match?(UUID_REGEX)
+          raise Error, "UUID placeholder requires a UUID-shaped value, got #{ClickHouse::SQL.truncated_inspect(value)}"
+        end
+
+        value
+      end
+
+      def validate_identifier(value)
+        string = value.to_s
+        unless string.match?(IDENTIFIER_REGEX) && !string.include?("..")
+          raise Error, "Identifier placeholder requires a safe identifier, got #{ClickHouse::SQL.truncated_inspect(value)}"
+        end
+
+        string
+      end
+
+      def validate_string(value)
+        raise Error, "String placeholder requires a String, got #{value.class}" unless value.is_a?(String)
+
+        value
+      end
+
+      # DateTime is a subclass of Date but serializes with a time component,
+      # which is not a valid ClickHouse Date literal, so it is rejected.
+      def validate_date(value)
+        return value if value.is_a?(Date) && !value.is_a?(DateTime)
+        return value if value.is_a?(String) && value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+
+        raise Error, "Date placeholder requires a Date or YYYY-MM-DD string, got #{ClickHouse::SQL.truncated_inspect(value)}"
+      end
+
+      def validate_datetime(value, timezone: nil)
+        if time_like?(value)
+          reject_non_utc_timezone!(timezone)
+          return value.to_time.getutc
+        end
+        return value if value.is_a?(String)
+        return value if value.is_a?(Numeric)
+
+        raise Error, "DateTime placeholder requires a Time, DateTime, String, or Numeric, got #{ClickHouse::SQL.truncated_inspect(value)}"
+      end
+
+      def validate_datetime64(value, arguments)
+        value = validate_datetime(value, timezone: timezone_argument(arguments[1]))
+        return value unless value.is_a?(Time)
+
+        precision = Integer(arguments.first, exception: false)
+        return value unless precision
+
+        format_time(value, precision)
+      end
+
+      def time_like?(value)
+        value.is_a?(Time) ||
+          value.is_a?(DateTime)
+      end
+
+      def timezone_argument(argument)
+        timezone = argument.to_s.delete("'\"")
+        timezone unless ValueNormalization.blank_string?(timezone)
+      end
+
+      # ClickHouse interprets rendered DateTime strings in the timezone the
+      # placeholder type declares, so a Ruby time value can only be formatted
+      # safely for UTC. Callers targeting other declared timezones must format
+      # the value themselves and pass a String.
+      def reject_non_utc_timezone!(timezone)
+        return if timezone.nil? || timezone == "UTC"
+
+        raise Error, "#{raw} placeholder declares a non-UTC timezone; pass a pre-formatted String instead of a time value"
+      end
+
+      def validate_integer(value)
+        return value if value.is_a?(Integer)
+        return value.to_i if value.is_a?(String) && value.match?(/\A[+-]?\d+\z/)
+
+        raise Error, "Integer placeholder requires an Integer or integer string, got #{value.class}"
+      end
+
+      def validate_sized_integer(value, bits:, unsigned:)
+        integer = validate_integer(value)
+        validate_integer_range(integer, bits:, unsigned:)
+        integer
+      end
+
+      def validate_integer_range(value, bits:, unsigned:)
+        min, max = if unsigned
+                     [0, (2**bits) - 1]
+                   else
+                     [-(2**(bits - 1)), (2**(bits - 1)) - 1]
+                   end
+        return if value.between?(min, max)
+
+        raise Error, "#{raw} placeholder value #{value.inspect} is outside #{min}..#{max}"
+      end
+
+      def validate_numeric(value)
+        raise Error, "Float placeholder requires a Numeric, got #{value.class}" unless value.is_a?(Numeric)
+        raise Error, "#{raw} placeholder value must be finite, got #{value.inspect}" unless value.finite?
+
+        value
+      end
+
+      def format_time(time, precision)
+        base = time.strftime("%Y-%m-%d %H:%M:%S")
+        return base if precision <= 0
+
+        fraction = time.nsec.to_s.rjust(9, "0")
+        fraction = fraction.ljust(precision, "0") if precision > 9
+
+        "#{base}.#{fraction[0, precision]}"
+      end
+    end
+  end
+end

data/lib/clickhouse/sql/query.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module ClickHouse
+  module SQL
+    class Query
+      include Part
+
+      REDACTED_BIND_TOKEN = "\0clickhouse_sql_bind\0"
+      private_constant :REDACTED_BIND_TOKEN
+
+      class RedactedBindIndexManager
+        # Returns an internal marker used when compiling redacted SQL templates.
+        #
+        # @return [String] Redacted bind marker token.
+        def next_bind_str
+          REDACTED_BIND_TOKEN
+        end
+      end
+      private_constant :RedactedBindIndexManager
+
+      # Builds a bind index manager for compiled redacted SQL templates.
+      #
+      # @return [#next_bind_str] Bind index manager that emits internal bind tokens.
+      def self.redacted_bind_index_manager
+        RedactedBindIndexManager.new
+      end
+
+      # Builds an immutable query object satisfying the client query protocol
+      # (#to_sql and #placeholders) accepted by ClickHouse::HTTPClient.
+      #
+      # @param sql [String, #to_s] Fully rendered SQL containing typed ClickHouse placeholders.
+      # @param redacted_sql [String, #to_s] Redacted SQL template containing internal bind tokens.
+      # @param placeholders [Hash{Symbol,String=>Object}] Placeholder values keyed by name.
+      # @param placeholder_types [Hash{Symbol,String=>String}] Placeholder types keyed by name.
+      # @return [ClickHouse::SQL::Query] Immutable client query object.
+      def initialize(sql:, redacted_sql:, placeholders:, placeholder_types:)
+        raise Error, "Empty SQL query given" if ValueNormalization.blank_string?(sql)
+        raise Error, "Empty redacted SQL query given" if ValueNormalization.blank_string?(redacted_sql)
+
+        @sql = sql.to_s.dup.freeze
+        @redacted_sql = redacted_sql.to_s.dup.freeze
+        @placeholders = immutable_symbolized_hash(placeholders)
+        @placeholder_types = immutable_symbolized_hash(placeholder_types)
+
+        validate_nil_placeholders!
+        freeze
+      end
+
+      # Renders the final SQL with ClickHouse typed placeholders intact.
+      #
+      # @return [String] SQL query text.
+      def to_sql
+        @sql
+      end
+
+      # Renders the final SQL with typed placeholders replaced by bind markers.
+      #
+      # @param bind_index_manager [ClickHouse::SQL::BindIndexManager] Redacted bind index state.
+      # @return [String] Redacted SQL query text.
+      def to_redacted_sql(bind_index_manager = ClickHouse::SQL::BindIndexManager.new)
+        parts = @redacted_sql.split(REDACTED_BIND_TOKEN, -1)
+        return @redacted_sql if parts.length == 1
+
+        parts.each_with_index.with_object(+"") do |(part, index), rendered|
+          rendered << part
+          rendered << bind_index_manager.next_bind_str unless index == parts.length - 1
+        end
+      end
+
+      # Returns typed placeholder values used by this query.
+      #
+      # @return [Hash{Symbol=>Object}] Placeholder values keyed by name.
+      attr_reader :placeholders
+
+      # Returns ClickHouse placeholder types used by this query.
+      #
+      # @return [Hash{Symbol=>String}] Placeholder types keyed by name.
+      attr_reader :placeholder_types
+
+      private
+
+      def immutable_symbolized_hash(hash)
+        ValueNormalization.symbolize_keys(hash)
+          .transform_values { |value| immutable_copy(value) }
+          .freeze
+      end
+
+      def immutable_copy(value)
+        case value
+        when Array
+          value.map { |item| immutable_copy(item) }.freeze
+        when Hash
+          value.to_h { |key, item| [immutable_copy(key), immutable_copy(item)] }.freeze
+        when String
+          value.dup.freeze
+        else
+          value
+        end
+      end
+
+      # The client sends nil placeholder values as NULL, which only a
+      # Nullable placeholder type can represent. For most non-Nullable types
+      # ClickHouse rejects NULL loudly, but a plain String placeholder
+      # silently parses it as an empty string — so nils are validated against
+      # the declared placeholder types here, where both are known.
+      def validate_nil_placeholders!
+        @placeholders.each do |name, value|
+          type = @placeholder_types[name].to_s
+
+          if value.nil?
+            next if !ValueNormalization.blank_string?(type) && PlaceholderType.new(type).nullable?
+
+            raise Error, "nil bound to non-Nullable placeholder {#{name}:#{type}}; declare the type as Nullable(...) to bind NULL"
+          elsif contains_nil?(value)
+            # Containment heuristic, not positional: one Nullable(...)
+            # member permits nils anywhere in the bound container, so e.g. a
+            # nil key in Map(String, Nullable(String)) slips through to
+            # ClickHouse. Positional validation would require parsing
+            # composite types.
+            next if type.include?("Nullable(")
+
+            raise Error, "nil element bound to non-Nullable placeholder {#{name}:#{type}}; declare the element type as Nullable(...) to bind NULLs"
+          end
+        end
+      end
+
+      def contains_nil?(value)
+        case value
+        when Array
+          value.any? { |item| item.nil? || contains_nil?(item) }
+        when Hash
+          value.any? { |key, item| key.nil? || item.nil? || contains_nil?(key) || contains_nil?(item) }
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/clickhouse/sql/raw.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ClickHouse
+  module SQL
+    class Raw
+      include Part
+
+      # @return [String, nil] Reason this raw SQL is intentionally unsafe, if any.
+      attr_reader :unsafe_reason
+
+      # Builds a trusted raw SQL expression.
+      #
+      # @param sql [String, #to_s] Raw SQL text.
+      # @param unsafe_reason [String, nil] Reason for using unsafe raw SQL.
+      # @return [ClickHouse::SQL::Raw] A raw SQL expression.
+      def initialize(sql, unsafe_reason: nil)
+        raise Error, "Empty SQL string given" if ValueNormalization.blank_string?(sql)
+
+        @sql = sql.to_s
+        @unsafe_reason = unsafe_reason
+      end
+
+      # Renders the raw SQL text.
+      #
+      # @return [String] Raw SQL text.
+      def to_sql
+        @sql
+      end
+
+      # Renders the raw SQL text for redacted logs.
+      #
+      # @param _bind_index_manager [ClickHouse::SQL::BindIndexManager] Unused redacted bind index state.
+      # @return [String] Raw SQL text.
+      def to_redacted_sql(_bind_index_manager = ClickHouse::SQL::BindIndexManager.new)
+        @sql
+      end
+
+      # Returns no placeholders because raw SQL cannot bind values.
+      #
+      # @return [Hash] Empty placeholder values.
+      def placeholders
+        {}
+      end
+
+      # Returns no placeholder types because raw SQL cannot bind values.
+      #
+      # @return [Hash] Empty placeholder types.
+      def placeholder_types
+        {}
+      end
+    end
+  end
+end

data/lib/clickhouse/sql/select_item.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ClickHouse
+  module SQL
+    # A SELECT expression with an optional validated alias.
+    #
+    # @!attribute expression
+    #   @return [ClickHouse::SQL::Part] SQL expression to select.
+    # @!attribute alias_name
+    #   @return [String, Symbol, nil] Optional output alias.
+    SelectItem = Struct.new(:expression, :alias_name, keyword_init: true) do
+      include Part
+
+      # Renders the SELECT expression.
+      #
+      # @return [String] SQL select item.
+      def to_sql
+        return expression.to_sql unless alias_name
+
+        "#{expression.to_sql} AS #{ClickHouse::SQL.validate_alias!(alias_name)}"
+      end
+
+      # Renders the SELECT expression with typed placeholders redacted.
+      #
+      # @param bind_index_manager [ClickHouse::SQL::BindIndexManager] Redacted bind index state.
+      # @return [String] Redacted SQL select item.
+      def to_redacted_sql(bind_index_manager)
+        return expression.to_redacted_sql(bind_index_manager) unless alias_name
+
+        "#{expression.to_redacted_sql(bind_index_manager)} AS #{ClickHouse::SQL.validate_alias!(alias_name)}"
+      end
+
+      # Returns typed placeholder values used by the SELECT expression.
+      #
+      # @return [Hash{Symbol=>Object}] Placeholder values keyed by name.
+      def placeholders
+        expression.placeholders
+      end
+
+      # Returns ClickHouse placeholder types used by the SELECT expression.
+      #
+      # @return [Hash{Symbol=>String}] Placeholder types keyed by name.
+      def placeholder_types
+        expression.placeholder_types
+      end
+    end
+  end
+end