Class: Parse::GroupBy

Inherits:
Object
  • Object
show all
Defined in:
lib/parse/query.rb

Overview

Helper class for handling group_by aggregations with method chaining. Supports count, sum, average, min, max operations on grouped data. Can optionally flatten array fields before grouping to count individual array elements.

Direct Known Subclasses

SortableGroupBy

Instance Method Summary collapse

Constructor Details

#initialize(query, group_field, flatten_arrays: false, return_pointers: false, mongo_direct: false) ⇒ GroupBy

Returns a new instance of GroupBy.

Parameters:

  • query (Parse::Query) —

    the base query to group

  • group_field (Symbol, String) —

    the field to group by

  • flatten_arrays (Boolean) (defaults to: false) —

    whether to flatten array fields before grouping

  • return_pointers (Boolean) (defaults to: false) —

    whether to return Parse::Pointer objects for pointer values

  • mongo_direct (Boolean) (defaults to: false) —

    whether to query MongoDB directly bypassing Parse Server



5734
5735
5736
5737
5738
5739
5740
5741
5742
 
# File 'lib/parse/query.rb', line 5734

def initialize(query, group_field, flatten_arrays: false, return_pointers: false, mongo_direct: false)
  @query = query
  @group_field = group_field
  @flatten_arrays = flatten_arrays
  @return_pointers = return_pointers
  @mongo_direct = mongo_direct
  @sort_target = nil    # nil | :key | :value | :size
  @sort_direction = nil # :asc | :desc
end

Instance Method Details

#average(field) ⇒ Hash Also known as: avg

Calculate average of a field for each group.

Examples:

Document.group_by(:category).average(:duration)
# => {"video" => 120.5, "audio" => 45.2}

Parameters:

  • field (Symbol, String) —

    the field to average within each group.

Returns:

  • (Hash) —

    a hash with group values as keys and averages as values.



5954
5955
5956
5957
5958
5959
5960
5961
 
# File 'lib/parse/query.rb', line 5954

def average(field)
  if field.nil? || !field.respond_to?(:to_s)
    raise ArgumentError, "Invalid field name passed to `average`."
  end

  formatted_field = @query.send(:format_aggregation_field, field)
  execute_group_aggregation("average", { "$avg" => "$#{formatted_field}" })
end

#count ⇒ Hash

Count the number of items in each group.

Examples:

Document.group_by(:category).count
# => {"image" => 45, "video" => 23, "audio" => 12}

Returns:

  • (Hash) —

    a hash with group values as keys and counts as values.



5929
5930
5931
 
# File 'lib/parse/query.rb', line 5929

def count
  execute_group_aggregation("count", { "$sum" => 1 })
end

#list ⇒ Hash{Object => Array<Parse::Object>}

Note:

On the Parse REST /aggregate path there is no ACL/CLP/protectedFields enforcement — that endpoint is master-key-only. On the mongo-direct path the SDK's ACL $match runs before $group, and both ACL redaction and protectedFields stripping recurse into pushed arrays, so scoped agents get correctly filtered records. The Array recursion that makes this safe lives in Parse::ACLScope#redact_subdocs! (lib/parse/acl_scope.rb) and Parse::CLPScope#walk_and_delete! (lib/parse/clp_scope.rb); if you change either of those, re-verify .list still strips correctly.

Collect every document of each group into an array of Parse::Object instances. Implemented as $push: "$$ROOT", so each group's value is the full set of underlying records (subject to the query's where constraints).

Use this when you want the actual records per group, not just an aggregated scalar. Combine with .order(size: :desc) to surface the largest groups first.

Examples:

Document.where(:status => "active").group_by(:category).list
# => {"image" => [<Document:...>, <Document:...>], "video" => [<Document:...>]}

Largest groups first

Document.group_by(:category).order(size: :desc).list

Returns:



6013
6014
6015
6016
6017
6018
6019
6020
6021
6022
6023
6024
6025
6026
6027
6028
6029
6030
6031
6032
6033
 
# File 'lib/parse/query.rb', line 6013

def list
  table = @query.instance_variable_get(:@table)
  # `$push: "$$ROOT"` pushes the raw MongoDB-storage-format document
  # into the result array on BOTH the REST and mongo-direct paths —
  # Parse Server's aggregate envelope only rewrites the outermost row's
  # `_id` to `objectId`, not nested arrays. So `_id`, `_p_<field>`
  # pointer strings, `_acl`/`_rperm`/`_wperm`, and `_created_at`/
  # `_updated_at` all survive into the pushed docs and have to be
  # normalized to Parse shape before `Parse::Object.build` will produce
  # an instance with the right id, associations, ACL, and timestamps.
  require_relative "mongodb"
  build_object = lambda do |doc|
    parse_doc = Parse::MongoDB.convert_document_to_parse(doc, table)
    parse_doc ? Parse::Object.build(parse_doc, table) : nil
  end

  execute_group_aggregation("list", { "$push" => "$$ROOT" }) do |docs|
    next [] unless docs.is_a?(Array)
    docs.map(&build_object).compact
  end
end

#max(field) ⇒ Hash

Find maximum value of a field for each group.

Parameters:

  • field (Symbol, String) —

    the field to find maximum for within each group.

Returns:

  • (Hash) —

    a hash with group values as keys and maximum values as values.



5980
5981
5982
5983
5984
5985
5986
5987
 
# File 'lib/parse/query.rb', line 5980

def max(field)
  if field.nil? || !field.respond_to?(:to_s)
    raise ArgumentError, "Invalid field name passed to `max`."
  end

  formatted_field = @query.send(:format_aggregation_field, field)
  execute_group_aggregation("max", { "$max" => "$#{formatted_field}" })
end

#min(field) ⇒ Hash

Find minimum value of a field for each group.

Parameters:

  • field (Symbol, String) —

    the field to find minimum for within each group.

Returns:

  • (Hash) —

    a hash with group values as keys and minimum values as values.



5968
5969
5970
5971
5972
5973
5974
5975
 
# File 'lib/parse/query.rb', line 5968

def min(field)
  if field.nil? || !field.respond_to?(:to_s)
    raise ArgumentError, "Invalid field name passed to `min`."
  end

  formatted_field = @query.send(:format_aggregation_field, field)
  execute_group_aggregation("min", { "$min" => "$#{formatted_field}" })
end

#order(spec) ⇒ self

Order grouped results by the group key, the aggregated value, or (for #list) the size of the per-group array. The ordering is pushed down into the aggregation pipeline as a $sort stage (plus a $addFields helper for :size), so MongoDB does the sort and the returned Hash preserves the order via Ruby's insertion semantics.

Examples:

Biggest groups first

Document.group_by(:category).order(value: :desc).count

Alphabetical group keys

Document.group_by(:category).order(key: :asc).count

Groups with the most members first

Document.group_by(:category).order(size: :desc).list

Parameters:

  • spec (Hash, Symbol) —

    one of:

    • { key: :asc | :desc } — sort by the group key
    • { value: :asc | :desc } — sort by the aggregated value (count/sum/avg/min/max)
    • { size: :asc | :desc } — sort by the length of the pushed array (only meaningful with #list)
    • :asc or :desc — shorthand for { key: direction }, matching Ruby's Hash#sort default of sorting by key.

Returns:

  • (self) 


5765
5766
5767
5768
5769
5770
5771
5772
5773
5774
5775
5776
5777
5778
5779
5780
5781
5782
5783
5784
5785
5786
5787
5788
5789
5790
 
# File 'lib/parse/query.rb', line 5765

def order(spec)
  target, direction =
    case spec
    when Symbol
      [:key, spec]
    when Hash
      unless spec.size == 1
        raise ArgumentError, "order(...) expects a single pair, e.g. {value: :desc} (got #{spec.inspect})"
      end
      k, v = spec.first
      [k.to_sym, v.to_sym]
    else
      raise ArgumentError, "order(...) expects {key:|value:|size: => :asc|:desc} or :asc/:desc (got #{spec.inspect})"
    end

  unless %i[key value size].include?(target)
    raise ArgumentError, "order(...) target must be :key, :value, or :size (got #{target.inspect})"
  end
  unless %i[asc desc].include?(direction)
    raise ArgumentError, "order(...) direction must be :asc or :desc (got #{direction.inspect})"
  end

  @sort_target = target
  @sort_direction = direction
  self
end

#pipeline ⇒ Array<Hash>

Returns the MongoDB aggregation pipeline that would be used for a count operation. This is useful for debugging and understanding the generated pipeline.

Examples:

Post.where(:author_workspace.eq => workspace).group_by(:last_action).pipeline
# => [{"$match"=>{"authorWorkspace"=>"Workspace$abc123"}}, {"$group"=>{"_id"=>"$lastAction", "count"=>{"$sum"=>1}}}, {"$project"=>{"_id"=>0, "objectId"=>"$_id", "count"=>1}}]

Returns:

  • (Array<Hash>) —

    the MongoDB aggregation pipeline



5817
5818
5819
5820
5821
5822
5823
5824
5825
5826
5827
5828
5829
5830
5831
5832
5833
5834
5835
5836
5837
5838
5839
5840
5841
5842
5843
5844
5845
5846
5847
5848
5849
5850
5851
5852
5853
5854
5855
5856
5857
5858
5859
5860
5861
5862
5863
5864
5865
5866
5867
5868
5869
5870
5871
5872
5873
5874
5875
5876
5877
5878
5879
5880
5881
5882
5883
5884
5885
5886
5887
5888
5889
5890
5891
5892
5893
5894
5895
5896
5897
5898
5899
5900
5901
5902
5903
5904
 
# File 'lib/parse/query.rb', line 5817

def pipeline
  # This introspection builds the same shape as the count execution
  # path (`$sum: 1`), so reject order/aggregation combinations that
  # the count path would reject at runtime — otherwise the preview
  # silently produces a pipeline the SDK would never actually run.
  validate_sort_target_for_operation!("count")

  # Format the group field name
  formatted_group_field = @query.send(:format_aggregation_field, @group_field)

  # Build the aggregation pipeline (same logic as execute_group_aggregation)
  pipeline = []

  # Add match stage if there are where conditions. `compile_where`
  # is already marker-free; use `compile_markers` to extract
  # __aggregation_pipeline stages.
  compiled_where = @query.send(:compile_where)
  markers = @query.send(:compile_markers)
  if compiled_where.present? || markers.key?("__aggregation_pipeline")
    # Collect all match conditions to merge into a single $match stage
    match_conditions = []
    non_match_stages = []

    # `compiled_where` is marker-free already.
    regular_constraints = compiled_where
    if regular_constraints.present?
      aggregation_where = @query.send(:convert_constraints_for_aggregation, regular_constraints)
      stringified_where = @query.send(:convert_dates_for_aggregation, aggregation_where)
      match_conditions << stringified_where
    end

    # Extract aggregation pipeline stages and merge $match stages
    if markers.key?("__aggregation_pipeline")
      markers["__aggregation_pipeline"].each do |stage|
        if stage.is_a?(Hash) && stage.key?("$match")
          # Extract the $match condition for merging
          match_conditions << stage["$match"]
        else
          # Non-$match stages go directly to pipeline
          non_match_stages << stage
        end
      end
    end

    # Combine all match conditions into a single $match stage
    if match_conditions.any?
      if match_conditions.length == 1
        pipeline << { "$match" => match_conditions.first }
      else
        # Use $and to combine multiple match conditions
        pipeline << { "$match" => { "$and" => match_conditions } }
      end
    end

    # Add any non-$match stages from the aggregation pipeline
    pipeline.concat(non_match_stages)
  end

  # Add unwind stage if flatten_arrays is enabled
  if @flatten_arrays
    pipeline << { "$unwind" => "$#{formatted_group_field}" }
  end

  # Add group stage (using count as example aggregation)
  pipeline << {
    "$group" => {
      "_id" => "$#{formatted_group_field}",
      "count" => { "$sum" => 1 },
    },
  }

  # Add $addFields + $sort stages if ordering was configured. Sort happens
  # before $project so we can reference `_id` (pre-rename) for :key sorts.
  add_fields = size_addfields_stage
  pipeline << add_fields if add_fields
  sort = sort_stage
  pipeline << sort if sort

  pipeline << {
    "$project" => {
      "_id" => 0,
      "objectId" => "$_id",
      "count" => 1,
    },
  }

  pipeline
end

#raw(operation, aggregation_expr) ⇒ Array<Hash>

Returns raw unprocessed aggregation results

Parameters:

  • operation (String) —

    the aggregation operation

  • aggregation_expr (Hash) —

    the MongoDB aggregation expression

Returns:



5910
5911
5912
5913
5914
5915
5916
5917
5918
5919
5920
5921
5922
 
# File 'lib/parse/query.rb', line 5910

def raw(operation, aggregation_expr)
  formatted_group_field = @query.send(:format_aggregation_field, @group_field)
  pipeline = build_pipeline(formatted_group_field, aggregation_expr)

  response = @query.client.aggregate_pipeline(
    @query.instance_variable_get(:@table),
    pipeline,
    headers: {},
    **@query.send(:_opts),
  )

  response.result || []
end

#sort(direction = :asc) ⇒ self

Sort grouped results by the group key. Alias for order(key: direction), mirroring Ruby's Hash#sort default. For value-based ordering use #order explicitly (e.g. .order(value: :desc)).

Note the asymmetry with chaining: .sort.count pushes the sort into the aggregation pipeline and returns a Hash keyed by group, while .count.sort first materializes the Hash and then calls Hash#sort, which returns an Array<[key, value]>. Both order by key ascending by default; this method exists so the pipeline form is also available.

Examples:

Document.group_by(:category).sort.count        # group keys ascending
Document.group_by(:category).sort(:desc).count # group keys descending

Parameters:

  • direction (Symbol) (defaults to: :asc) —

    :asc (default) or :desc

Returns:

  • (self) 


5807
5808
5809
 
# File 'lib/parse/query.rb', line 5807

def sort(direction = :asc)
  order(direction)
end

#sum(field) ⇒ Hash

Sum a field for each group.

Examples:

Document.group_by(:project).sum(:file_size)
# => {"Project1" => 1024000, "Project2" => 512000}

Parameters:

  • field (Symbol, String) —

    the field to sum within each group.

Returns:

  • (Hash) —

    a hash with group values as keys and sums as values.



5939
5940
5941
5942
5943
5944
5945
5946
 
# File 'lib/parse/query.rb', line 5939

def sum(field)
  if field.nil? || !field.respond_to?(:to_s)
    raise ArgumentError, "Invalid field name passed to `sum`."
  end

  formatted_field = @query.send(:format_aggregation_field, field)
  execute_group_aggregation("sum", { "$sum" => "$#{formatted_field}" })
end