simple_query 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a62c7c2fe2d6c43a27b9cc2dd22e7ddcf14a01f9ca335144b472db1559f4b0a
-  data.tar.gz: 172eddfa79634dcf78d3547031af80a9f1e008dc9e0414c0f5671c66b4264617
+  metadata.gz: 856dc1549df83e6c82a7105b3dfa97b9c6f4e69b86f6c2f9ad653ae1f322d1e8
+  data.tar.gz: c10490e13ffbc3da9c629081cde483188efbc0ec3fbdcf27070d565947cc723a
 SHA512:
-  metadata.gz: abbd8b5034e7b3a9a72b5de79f0d522a1ba2ac2b066bcc78387fb068ad9647b685c006318f6efafd31b5b616b48bd18ea677a5c74e7c25647a38c062a934109b
-  data.tar.gz: e499597efd33f703d136b0e053006ef109dea762e19148acd6bb5dcf6717f14f8b63845d61a3ea7b770353dd37e17178ca8b51ef7785e0714828ee78bda1fb8e
+  metadata.gz: 627f5f7fe8a02a9bdf949f8b4d681fc811a6081b0dc2666f60baacff55d6136a3e28512d8c44a1d5cca1699a6529716b36daa4aca455a1ed070efdca935b078a
+  data.tar.gz: 056dbe8add051110bc32cb79264128e87804d4839b0e1f74172353d6f205a59080a54ed463f04ae82efb239237f4d3d0e4ad8f03bc96bdbc607f1c1a0ec68ff9

data/README.md

@@ -104,6 +104,94 @@ User.simple_query
     .execute
 ```
 
+## Enhanced Aggregation Support
+
+SimpleQuery provides a comprehensive set of aggregation methods that are more convenient and readable than writing raw SQL:
+
+### Basic Aggregations
+
+```ruby
+# Count records
+User.simple_query.count.execute
+# => #<struct count=1000>
+
+# Count specific column (non-null values)
+User.simple_query.count(:email).execute
+# => #<struct count_email=995>
+
+# Sum values
+Company.simple_query.sum(:annual_revenue).execute
+# => #<struct sum_annual_revenue=50000000>
+
+# Average values
+Company.simple_query.avg(:annual_revenue).execute
+# => #<struct avg_annual_revenue=1000000.5>
+
+# Find minimum and maximum
+Company.simple_query.min(:annual_revenue).max(:annual_revenue).execute
+# => #<struct min_annual_revenue=100000, max_annual_revenue=5000000>
+```
+
+### Statistical Functions
+
+```ruby
+# Variance and standard deviation
+User.simple_query.variance(:score).stddev(:score).execute
+# => #<struct variance_score=125.67, stddev_score=11.21>
+
+# Database-specific group concatenation
+User.simple_query
+    .select(:department)
+    .group_concat(:name, separator: ", ")
+    .group(:department)
+    .execute
+# => #<struct department="Engineering", group_concat_name="Alice, Bob, Charlie">
+```
+
+### Advanced Aggregation Features
+
+```ruby
+# Get comprehensive statistics for a column
+Company.simple_query.stats(:annual_revenue).execute
+# => #<struct 
+#      annual_revenue_count=100,
+#      annual_revenue_sum=50000000,
+#      annual_revenue_avg=500000,
+#      annual_revenue_min=100000,
+#      annual_revenue_max=2000000
+#    >
+
+# Custom aggregations
+Company.simple_query
+        .custom_aggregation("COUNT(DISTINCT industry)", "unique_industries")
+        .execute
+# => #<struct unique_industries=5>
+
+# Combining with other features
+Company.simple_query
+        .select(:industry)
+        .count
+        .sum(:annual_revenue)
+        .group(:industry)
+        .execute
+# => [
+#      #<struct industry="Technology", count=50, sum_annual_revenue=25000000>,
+#      #<struct industry="Finance", count=30, sum_annual_revenue=20000000>
+#    ]
+```
+
+### Custom Aliases
+
+All aggregation methods support custom aliases:
+
+```ruby
+User.simple_query
+    .count(:id, alias_name: "total_users")
+    .sum(:score, alias_name: "total_score")
+    .execute
+# => #<struct total_users=1000, total_score=85000>
+```
+
 ## Custom Read Models
 By default, SimpleQuery returns results as `Struct` objects for maximum speed. However, you can also define a lightweight model class for more explicit attribute handling or custom logic.
 

data/lib/simple_query/builder.rb

@@ -18,6 +18,7 @@ module SimpleQuery
       @orders = OrderClause.new(@arel_table)
       @limits = LimitOffsetClause.new
       @distinct_flag = DistinctClause.new
+      @aggregations = AggregationClause.new(@arel_table)
 
       @query_cache = {}
       @query_built = false
@@ -91,6 +92,98 @@ 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)})",
+                         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
@@ -145,7 +238,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,6 +256,23 @@ module SimpleQuery
 
     private
 
+    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 build_where_sql
       condition = @wheres.to_arel
       return "" unless condition
@@ -182,7 +295,8 @@ 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
@@ -267,6 +381,17 @@ module SimpleQuery
       end
     end
 
+    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, &block)
       if (scope_block = find_scope(method_name))
         instance_exec(*args, &scope_block)

data/lib/simple_query/clauses/aggregation_clause.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module SimpleQuery
+  class AggregationClause
+    attr_reader :aggregations
+
+    def initialize(table)
+      @table = table
+      @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
+      adapter = ActiveRecord::Base.connection.adapter_name.downcase
+
+      expression = case adapter
+                   when /mysql/
+                     "GROUP_CONCAT(#{column_expr} SEPARATOR '#{separator}')"
+                   when /postgres/
+                     "STRING_AGG(#{column_expr}::text, '#{separator}')"
+                   when /sqlite/
+                     "GROUP_CONCAT(#{column_expr}, '#{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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SimpleQuery
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/simple_query.rb

@@ -14,6 +14,7 @@ require_relative "simple_query/clauses/distinct_clause"
 require_relative "simple_query/clauses/limit_offset_clause"
 require_relative "simple_query/clauses/group_having_clause"
 require_relative "simple_query/clauses/set_clause"
+require_relative "simple_query/clauses/aggregation_clause"
 
 module SimpleQuery
   extend ActiveSupport::Concern

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple_query
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Alex Kholodniak
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-03-15 00:00:00.000000000 Z
+date: 2025-08-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -44,6 +44,7 @@ files:
 - README.md
 - lib/simple_query.rb
 - lib/simple_query/builder.rb
+- lib/simple_query/clauses/aggregation_clause.rb
 - lib/simple_query/clauses/distinct_clause.rb
 - lib/simple_query/clauses/group_having_clause.rb
 - lib/simple_query/clauses/join_clause.rb