simple_query 0.4.0 → 0.6.0

data/lib/simple_query/builder.rb

@@ -12,17 +12,18 @@ module SimpleQuery
       @arel_table = @model.arel_table
 
       @selects = []
-      @wheres = WhereClause.new(@arel_table)
+      @wheres = WhereClause.new(@arel_table, @model)
       @joins = JoinClause.new
-      @group_having = GroupHavingClause.new(@arel_table)
+      @group_having = GroupHavingClause.new(@arel_table, @model)
       @orders = OrderClause.new(@arel_table)
       @limits = LimitOffsetClause.new
       @distinct_flag = DistinctClause.new
+      @aggregations = AggregationClause.new(@arel_table, @model)
 
       @query_cache = {}
       @query_built = false
       @read_model_class = nil
-      @result_struct = nil
+      @result_structs = {}
     end
 
     def select(*fields)
@@ -91,6 +92,99 @@ module SimpleQuery
       self
     end
 
+    # Aggregation methods
+    def count(column = nil, alias_name: nil)
+      @aggregations.count(column, alias_name: alias_name)
+      reset_query
+      self
+    end
+
+    def sum(column, alias_name: nil)
+      @aggregations.sum(column, alias_name: alias_name)
+      reset_query
+      self
+    end
+
+    def avg(column, alias_name: nil)
+      @aggregations.avg(column, alias_name: alias_name)
+      reset_query
+      self
+    end
+
+    def min(column, alias_name: nil)
+      @aggregations.min(column, alias_name: alias_name)
+      reset_query
+      self
+    end
+
+    def max(column, alias_name: nil)
+      @aggregations.max(column, alias_name: alias_name)
+      reset_query
+      self
+    end
+
+    def variance(column, alias_name: nil)
+      @aggregations.variance(column, alias_name: alias_name)
+      reset_query
+      self
+    end
+
+    def stddev(column, alias_name: nil)
+      @aggregations.stddev(column, alias_name: alias_name)
+      reset_query
+      self
+    end
+
+    def group_concat(column, separator: ",", alias_name: nil)
+      @aggregations.group_concat(column, separator: separator, alias_name: alias_name)
+      reset_query
+      self
+    end
+
+    def custom_aggregation(expression, alias_name)
+      @aggregations.custom(expression, alias_name)
+      reset_query
+      self
+    end
+
+    # Convenience methods for common aggregation patterns
+    def total_count(alias_name: "total")
+      count(alias_name: alias_name)
+    end
+
+    def stats(column, alias_prefix: nil)
+      prefix = alias_prefix || column.to_s
+      count(alias_name: "#{prefix}_count")
+      sum(column, alias_name: "#{prefix}_sum")
+      avg(column, alias_name: "#{prefix}_avg")
+      min(column, alias_name: "#{prefix}_min")
+      max(column, alias_name: "#{prefix}_max")
+      self
+    end
+
+    # Method to get first/top record by column
+    def first_by(column, alias_name: nil)
+      alias_name ||= "first_#{column}"
+      custom_aggregation("FIRST_VALUE(#{resolve_column_name(column)}) OVER (ORDER BY #{resolve_column_name(column)})",
+                         alias_name)
+    end
+
+    # Method to get last/bottom record by column
+    def last_by(column, alias_name: nil)
+      alias_name ||= "last_#{column}"
+      custom_aggregation("LAST_VALUE(#{resolve_column_name(column)}) OVER (ORDER BY #{resolve_column_name(column)} " \
+                         "ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING)",
+                         alias_name)
+    end
+
+    # Percentage calculations
+    def percentage_of_total(column, alias_name: nil)
+      alias_name ||= "#{column}_percentage"
+      column_expr = resolve_column_name(column)
+      expression = "ROUND((#{column_expr} * 100.0 / SUM(#{column_expr}) OVER ()), 2)"
+      custom_aggregation(expression, alias_name)
+    end
+
     def map_to(klass)
       @read_model_class = klass
       reset_query
@@ -98,37 +192,44 @@ module SimpleQuery
     end
 
     def bulk_update(set:)
-      table_name = @arel_table.name
-      set_sql = SetClause.new(set).to_sql
+      validate_bulk_update_scope!
 
+      set_sql = SetClause.new(set, @model).to_sql
       raise ArgumentError, "No columns to update" if set_sql.empty?
 
-      where_sql = build_where_sql
-      sql = "UPDATE #{table_name} SET #{set_sql}"
-      sql += " WHERE #{where_sql}" unless where_sql.nil? || where_sql.empty?
+      update = Arel::UpdateManager.new
+      update.table(@arel_table)
+      update.set(Arel.sql(set_sql))
+      condition = @wheres.to_arel
+      update.where(condition) if condition
 
-      ActiveRecord::Base.connection.execute(sql)
+      connection.execute(compile_sql(update))
     end
 
     def stream_each(batch_size: 1000, &block)
-      adapter = ActiveRecord::Base.connection.adapter_name.downcase
+      validate_stream_batch_size!(batch_size)
+
+      adapter_name = connection.adapter_name
+      adapter = adapter_name.downcase
       if adapter.include?("postgres")
         stream_each_postgres(batch_size, &block)
       elsif adapter.include?("mysql")
         stream_each_mysql(&block)
       else
-        raise "stream_each is only implemented for Postgres and MySQL."
+        message = "stream_each is only implemented for PostgreSQL and MySQL adapters " \
+                  "(current adapter: #{adapter_name})"
+        raise UnsupportedAdapterError, message
       end
     end
 
     def execute
-      records = ActiveRecord::Base.connection.select_all(cached_sql)
+      records = connection.select_all(cached_sql)
       build_result_objects_from_rows(records)
     end
 
     def lazy_execute
       Enumerator.new do |yielder|
-        records = ActiveRecord::Base.connection.select_all(cached_sql)
+        records = connection.select_all(cached_sql)
         if @read_model_class
           build_read_models_enumerator(records, yielder)
         else
@@ -145,7 +246,10 @@ module SimpleQuery
 
       @query = Arel::SelectManager.new(Arel::Table.engine)
       @query.from(@arel_table)
-      @query.project(*(@selects.empty? ? [@arel_table[Arel.star]] : @selects))
+
+      # Combine regular selects with aggregations
+      all_selects = build_select_expressions
+      @query.project(*all_selects)
 
       apply_distinct
       apply_where_conditions
@@ -160,11 +264,46 @@ module SimpleQuery
 
     private
 
-    def build_where_sql
-      condition = @wheres.to_arel
-      return "" unless condition
+    def validate_stream_batch_size!(batch_size)
+      return if batch_size.is_a?(Integer) && batch_size.positive?
+
+      raise ArgumentError, "stream_each batch_size must be a positive Integer"
+    end
+
+    def validate_bulk_update_scope!
+      unsupported = []
+      unsupported << "joins" if @joins.joins.any?
+      unsupported << "limit/offset" if @limits.limit_value || @limits.offset_value
+      unsupported << "group/having" if @group_having.group_fields.any? || @group_having.having_conditions.any?
+      return if unsupported.empty?
+
+      raise ArgumentError, "bulk_update only supports where conditions (found #{unsupported.join(", ")})"
+    end
+
+    def build_select_expressions
+      expressions = []
+
+      # Add regular selects
+      if @selects.any?
+        expressions.concat(@selects)
+      elsif @aggregations.empty?
+        # Only use * if no aggregations and no explicit selects
+        expressions << @arel_table[Arel.star]
+      end
+
+      # Add aggregation expressions
+      expressions.concat(@aggregations.to_arel_expressions)
+
+      expressions
+    end
+
+    def connection
+      @model.connection
+    end
 
-      condition.to_sql
+    # Compiles with the model's own connection, inlining any bind values.
+    def compile_sql(arel)
+      connection.unprepared_statement { connection.to_sql(arel) }
     end
 
     def reset_query
@@ -182,10 +321,11 @@ module SimpleQuery
         @orders.orders,
         @limits.limit_value,
         @limits.offset_value,
-        @distinct_flag.use_distinct?
+        @distinct_flag.use_distinct?,
+        @aggregations.aggregations
       ]
 
-      @query_cache[key] ||= build_query.to_sql
+      @query_cache[key] ||= compile_sql(build_query)
     end
 
     def build_result_objects_from_rows(records)
@@ -226,7 +366,8 @@ module SimpleQuery
     end
 
     def result_struct(columns)
-      @result_struct ||= Struct.new(*columns.map(&:to_sym))
+      struct_key = columns.map(&:to_s)
+      @result_structs[struct_key] ||= Struct.new(*struct_key.map(&:to_sym))
     end
 
     def apply_distinct
@@ -267,9 +408,21 @@ module SimpleQuery
       end
     end
 
-    def method_missing(method_name, *args, &block)
+    def resolve_column_name(column)
+      case column
+      when Symbol
+        "#{@arel_table.name}.#{column}"
+      when String
+        column.include?(".") ? column : "#{@arel_table.name}.#{column}"
+      else
+        column.to_s
+      end
+    end
+
+    def method_missing(method_name, *args, **kwargs, &block)
       if (scope_block = find_scope(method_name))
-        instance_exec(*args, &scope_block)
+        validate_scope_arity!(method_name, scope_block, scope_arguments_for_validation(scope_block, args, kwargs))
+        instance_exec(*args, **kwargs, &scope_block)
         self
       else
         super
@@ -285,5 +438,69 @@ module SimpleQuery
 
       model._simple_scopes[method_name.to_sym]
     end
+
+    def validate_scope_arity!(scope_name, scope_block, args)
+      range = scope_argument_range(scope_block)
+      provided = args.length
+      return if scope_arity_matches?(range, provided)
+
+      raise ArgumentError,
+            "simple_scope :#{scope_name} expected #{scope_arity_description(range)}, provided #{provided}"
+    end
+
+    def scope_arguments_for_validation(scope_block, args, kwargs)
+      return args if kwargs.empty? || scope_uses_keyword_arguments?(scope_block)
+
+      args + [kwargs]
+    end
+
+    def scope_argument_range(scope_block)
+      # Keyword argument arity has Ruby-version-specific edge cases; let Ruby raise its native error.
+      return nil if scope_uses_keyword_arguments?(scope_block)
+
+      minimum = minimum_scope_arguments(scope_block)
+      maximum = maximum_scope_arguments(scope_block)
+
+      [minimum, maximum]
+    end
+
+    def scope_uses_keyword_arguments?(scope_block)
+      scope_block.parameters.any? { |kind, _name| [:key, :keyreq, :keyrest].include?(kind) }
+    end
+
+    def minimum_scope_arguments(scope_block)
+      arity = scope_block.arity
+      return arity if arity >= 0
+
+      -arity - 1
+    end
+
+    def maximum_scope_arguments(scope_block)
+      parameters = scope_block.parameters
+      return nil if parameters.any? { |kind, _name| kind == :rest }
+
+      parameters.count { |kind, _name| [:req, :opt].include?(kind) }
+    end
+
+    def scope_arity_matches?(range, provided)
+      return true if range.nil?
+
+      minimum, maximum = range
+      return provided >= minimum if maximum.nil?
+
+      provided.between?(minimum, maximum)
+    end
+
+    def scope_arity_description(range)
+      minimum, maximum = range
+      return "at least #{argument_count_description(minimum)}" if maximum.nil?
+      return "exactly #{argument_count_description(minimum)}" if minimum == maximum
+
+      "#{minimum} to #{argument_count_description(maximum)}"
+    end
+
+    def argument_count_description(count)
+      "#{count} #{count == 1 ? "argument" : "arguments"}"
+    end
   end
 end

data/lib/simple_query/clauses/aggregation_clause.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module SimpleQuery
+  class AggregationClause
+    attr_reader :aggregations
+
+    def initialize(table, model = ActiveRecord::Base)
+      @table = table
+      @model = model
+      @aggregations = []
+    end
+
+    def count(column = nil, alias_name: nil)
+      column_expr = column ? resolve_column(column) : "*"
+      alias_name ||= column ? "count_#{sanitize_alias(column)}" : "count"
+
+      add_aggregation("COUNT", column_expr, alias_name)
+    end
+
+    def sum(column, alias_name: nil)
+      raise ArgumentError, "Column is required for SUM aggregation" if column.nil?
+
+      column_expr = resolve_column(column)
+      alias_name ||= "sum_#{sanitize_alias(column)}"
+
+      add_aggregation("SUM", column_expr, alias_name)
+    end
+
+    def avg(column, alias_name: nil)
+      raise ArgumentError, "Column is required for AVG aggregation" if column.nil?
+
+      column_expr = resolve_column(column)
+      alias_name ||= "avg_#{sanitize_alias(column)}"
+
+      add_aggregation("AVG", column_expr, alias_name)
+    end
+
+    def min(column, alias_name: nil)
+      raise ArgumentError, "Column is required for MIN aggregation" if column.nil?
+
+      column_expr = resolve_column(column)
+      alias_name ||= "min_#{sanitize_alias(column)}"
+
+      add_aggregation("MIN", column_expr, alias_name)
+    end
+
+    def max(column, alias_name: nil)
+      raise ArgumentError, "Column is required for MAX aggregation" if column.nil?
+
+      column_expr = resolve_column(column)
+      alias_name ||= "max_#{sanitize_alias(column)}"
+
+      add_aggregation("MAX", column_expr, alias_name)
+    end
+
+    def custom(expression, alias_name)
+      if expression.nil? || alias_name.nil?
+        raise ArgumentError,
+              "Expression and alias are required for custom aggregation"
+      end
+
+      @aggregations << {
+        expression: expression,
+        alias: alias_name
+      }
+    end
+
+    # Statistical functions
+    def variance(column, alias_name: nil)
+      raise ArgumentError, "Column is required for VARIANCE aggregation" if column.nil?
+
+      column_expr = resolve_column(column)
+      alias_name ||= "variance_#{sanitize_alias(column)}"
+
+      add_aggregation("VARIANCE", column_expr, alias_name)
+    end
+
+    def stddev(column, alias_name: nil)
+      raise ArgumentError, "Column is required for STDDEV aggregation" if column.nil?
+
+      column_expr = resolve_column(column)
+      alias_name ||= "stddev_#{sanitize_alias(column)}"
+
+      add_aggregation("STDDEV", column_expr, alias_name)
+    end
+
+    # Group concatenation (database-specific)
+    def group_concat(column, separator: ",", alias_name: nil)
+      raise ArgumentError, "Column is required for GROUP_CONCAT aggregation" if column.nil?
+
+      column_expr = resolve_column(column)
+      alias_name ||= "group_concat_#{sanitize_alias(column)}"
+
+      # Use database-specific group concatenation
+      connection = @model.connection
+      adapter = connection.adapter_name.downcase
+      quoted_separator = connection.quote(separator.to_s)
+
+      expression = case adapter
+                   when /mysql/
+                     "GROUP_CONCAT(#{column_expr} SEPARATOR #{quoted_separator})"
+                   when /postgres/
+                     "STRING_AGG(#{column_expr}::text, #{quoted_separator})"
+                   when /sqlite/
+                     "GROUP_CONCAT(#{column_expr}, #{quoted_separator})"
+                   else
+                     # Fallback for other databases
+                     "GROUP_CONCAT(#{column_expr})"
+                   end
+
+      @aggregations << {
+        expression: expression,
+        alias: alias_name
+      }
+    end
+
+    def to_arel_expressions
+      @aggregations.map do |agg|
+        Arel.sql("#{agg[:expression]} AS #{agg[:alias]}")
+      end
+    end
+
+    def empty?
+      @aggregations.empty?
+    end
+
+    def clear
+      @aggregations.clear
+    end
+
+    private
+
+    def add_aggregation(function, column_expr, alias_name)
+      @aggregations << {
+        expression: "#{function}(#{column_expr})",
+        alias: alias_name
+      }
+    end
+
+    def resolve_column(column)
+      case column
+      when Symbol
+        "#{@table.name}.#{column}"
+      when String
+        # Allow table.column format or just column name
+        column.include?(".") ? column : "#{@table.name}.#{column}"
+      when Arel::Attributes::Attribute
+        column.to_sql
+      else
+        column.to_s
+      end
+    end
+
+    def sanitize_alias(column)
+      column.to_s.gsub(".", "_")
+    end
+  end
+end

data/lib/simple_query/clauses/group_having_clause.rb

@@ -4,8 +4,9 @@ module SimpleQuery
   class GroupHavingClause
     attr_reader :group_fields, :having_conditions
 
-    def initialize(table)
+    def initialize(table, model = ActiveRecord::Base)
       @table = table
+      @model = model
       @group_fields = []
       @having_conditions = []
     end
@@ -15,15 +16,14 @@ module SimpleQuery
     end
 
     def add_having(condition)
-      @having_conditions << condition
+      clause = WhereClause.new(@table, @model)
+      clause.add(condition)
+      @having_conditions.concat(clause.conditions)
     end
 
     def apply_to(query)
       @group_fields.each { |g| query.group(g) }
-      if @having_conditions.any?
-        combined = @having_conditions.inject { |c, a| c.and(a) }
-        query.having(combined)
-      end
+      query.having(WhereClause.combine(@having_conditions)) if @having_conditions.any?
       query
     end
   end

data/lib/simple_query/clauses/set_clause.rb

@@ -2,8 +2,9 @@
 
 module SimpleQuery
   class SetClause
-    def initialize(set_hash)
+    def initialize(set_hash, model = ActiveRecord::Base)
       @set_hash = set_hash
+      @model = model
     end
 
     def to_sql
@@ -15,11 +16,11 @@ module SimpleQuery
     private
 
     def quote_column(col)
-      ActiveRecord::Base.connection.quote_column_name(col)
+      @model.connection.quote_column_name(col)
     end
 
     def quote_value(val)
-      ActiveRecord::Base.connection.quote(val)
+      @model.connection.quote(val)
     end
   end
 end

data/lib/simple_query/clauses/where_clause.rb

@@ -4,8 +4,16 @@ module SimpleQuery
   class WhereClause
     attr_reader :conditions
 
-    def initialize(table)
+    def self.combine(conditions)
+      return nil if conditions.empty?
+      return conditions.first if conditions.one?
+
+      Arel::Nodes::And.new(conditions.map { |c| c.is_a?(Arel::Nodes::Grouping) ? c : Arel::Nodes::Grouping.new(c) })
+    end
+
+    def initialize(table, model = ActiveRecord::Base)
       @table = table
+      @model = model
       @conditions = []
     end
 
@@ -15,11 +23,7 @@ module SimpleQuery
     end
 
     def to_arel
-      return nil if @conditions.empty?
-
-      @conditions.inject do |combined, current|
-        combined.and(current)
-      end
+      self.class.combine(@conditions)
     end
 
     private
@@ -27,15 +31,36 @@ module SimpleQuery
     def parse_condition(condition)
       case condition
       when Hash
-        condition.map { |field, value| @table[field].eq(value) }
-      when Arel::Nodes::Node
+        condition.map { |field, value| hash_predicate(field, value) }
+      when Arel::Nodes::Node, Arel::Attributes::Attribute
         [condition]
       when Array
-        sanitized_sql = ActiveRecord::Base.send(:sanitize_sql_array, condition)
+        sanitized_sql = @model.send(:sanitize_sql_array, condition)
         [Arel.sql(sanitized_sql)]
       else
         [Arel.sql(condition.to_s)]
       end
     end
+
+    def hash_predicate(field, value)
+      attribute = @table[field]
+      return attribute.eq(value) if force_equality?(field, value)
+
+      case value
+      when Array
+        values = value.compact
+        predicate = attribute.in(values)
+        values.size == value.size ? predicate : predicate.or(attribute.eq(nil))
+      when Range
+        attribute.between(value)
+      else
+        attribute.eq(value)
+      end
+    end
+
+    # PostgreSQL array/range columns compare arrays and ranges by equality, like ActiveRecord does.
+    def force_equality?(field, value)
+      @table.able_to_type_cast? && @table.type_for_attribute(field.to_s).force_equality?(value)
+    end
   end
 end

data/lib/simple_query/stream/mysql_stream.rb

@@ -6,12 +6,17 @@ module SimpleQuery
       def stream_each_mysql(&block)
         select_sql = cached_sql
 
-        raw_conn = ActiveRecord::Base.connection.raw_connection
+        raw_conn = connection.raw_connection
 
         result = raw_conn.query(select_sql, stream: true, cache_rows: false, as: :hash)
-        result.each do |mysql_row|
-          record = build_row_object_mysql(mysql_row)
-          block.call(record)
+        begin
+          result.each do |mysql_row|
+            record = build_row_object_mysql(mysql_row)
+            block.call(record)
+          end
+        ensure
+          # Discards unread rows so the connection can run the next query after an error or break.
+          result.free
         end
       end