google-cloud-firestore 2.13.1 → 2.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30cb17b1e946e584cbe565b74143e0051f93bc4666f11a183a0f3f0a541b8a9d
-  data.tar.gz: 18b71ed2191e4f15e6bc667f8e6825e1c33d66dc3f98a7753536cd87a6dff177
+  metadata.gz: 9ff9b426ba1d870f0620a434f5e826f81cd878b09fa9aad5838d97245974b23c
+  data.tar.gz: 9f798211b2b5252f9992f1bf1f8c413cfd99154ee656c1b9d8e72ec6945fbc64
 SHA512:
-  metadata.gz: 539e3c8a868b4ece85550090a53829d615ba519bf4e0eaaea4e7ac5601977be51c5978fc8eb5ac12d2ea4e3e8c4b803c0a6a406111c381d45983516accafb3c0
-  data.tar.gz: a95df5fec2c114cbdde41bd78b6835664865d09a900b445f2b4deb595a4ba6cd761f777c9ce08746604b7289727d9f36b218033e3bde6261365f6835d4ab3df8
+  metadata.gz: 587f4928f11528d167b2f6649a1be0b43b29c109192c200c8825315e506671321345a4bd0880652be59d44ab3349dce5ea30dd84921a10d973539e9c67dfd691
+  data.tar.gz: 8df7d3795cc14f938b883877ee78940e2a0935b5494f799216676814533b2b77d35c66806a1677ada54a7430ed3868ce8be9b423a75dab7d60ea9b5444430040

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Release History
 
+### 2.14.0 (2024-01-31)
+
+#### Features
+
+* Support sum & avg aggregate functions ([#23446](https://github.com/googleapis/google-cloud-ruby/issues/23446)) 
+
 ### 2.13.1 (2023-06-16)
 
 #### Documentation

data/lib/google/cloud/firestore/aggregate_query.rb

@@ -67,26 +67,39 @@ module Google
         attr_reader :parent_path
 
         ##
-        # @private The Google::Cloud::Firestore::V1::StructuredQuery object.
+        # @private The Google::Cloud::Firestore::Query object.
         attr_reader :query
 
         ##
-        # @private Array of Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation objects
-        attr_reader :aggregates
+        # @private Object of type
+        # Google::Cloud::Firestore::V1::StructuredAggregationQuery
+        attr_reader :grpc
+
+        # @private
+        DEFAULT_COUNT_ALIAS = "count".freeze
+
+        # @private
+        DEFAULT_SUM_ALIAS = "sum".freeze
+
+        # @private
+        DEFAULT_AVG_ALIAS = "avg".freeze
 
         ##
         # @private Creates a new AggregateQuery
-        def initialize query, parent_path, client, aggregates: []
+        def initialize query, parent_path, client
           @query = query
           @parent_path = parent_path
-          @aggregates = aggregates
           @client = client
+          @grpc = Google::Cloud::Firestore::V1::StructuredAggregationQuery.new(
+            structured_query: @query.query,
+            aggregations: []
+          )
         end
 
         ##
         # Adds a count aggregate.
         #
-        # @param [aggregate_alias] Alias to refer to the aggregate. Optional
+        # @param aggregate_alias [String] Alias to refer to the aggregate. Optional
         #
         # @return [AggregateQuery] A new aggregate query with the added count aggregate.
         #
@@ -106,13 +119,102 @@ module Google
         #   end
         #
         def add_count aggregate_alias: nil
-          aggregate_alias ||= ALIASES[:count]
-          new_aggregates = @aggregates.dup
-          new_aggregates << StructuredAggregationQuery::Aggregation.new(
-            count: StructuredAggregationQuery::Aggregation::Count.new,
+          aggregate_alias ||= DEFAULT_COUNT_ALIAS
+          new_aggregate = Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation.new(
+            count: Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation::Count.new,
+            alias: aggregate_alias
+          )
+
+          start new_aggregate
+        end
+
+        ##
+        # Adds a sum aggregate.
+        #
+        # @param field [String] The field to sum by
+        # @param aggregate_alias [String] Alias to refer to the aggregate
+        #
+        # @return [AggregateQuery] A new aggregate query with the added sum aggregate.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   query = firestore.col "cities"
+        #
+        #   # Create an aggregate query
+        #   aggregate_query = query.aggregate_query
+        #                          .add_sum("population")
+        #
+        #   aggregate_query.get do |aggregate_snapshot|
+        #     puts aggregate_snapshot.get
+        #   end
+        #
+        def add_sum field, aggregate_alias: nil
+          aggregate_alias ||= DEFAULT_SUM_ALIAS
+          field = FieldPath.parse field unless field.is_a? FieldPath
+          new_aggregate = Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation.new(
+            sum: Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation::Sum.new(
+              field: Google::Cloud::Firestore::V1::StructuredQuery::FieldReference.new(
+                field_path: field.formatted_string
+              )
+            ),
             alias: aggregate_alias
           )
-          AggregateQuery.start query, new_aggregates, parent_path, client
+
+          start new_aggregate
+        end
+
+        ##
+        # Adds an average aggregate.
+        #
+        # @param field [String] The field to apply average on
+        # @param aggregate_alias [String] Alias to refer to the aggregate
+        #
+        # @return [AggregateQuery] A new aggregate query with the added average aggregate.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   query = firestore.col "cities"
+        #
+        #   # Create an aggregate query
+        #   aggregate_query = query.aggregate_query
+        #                          .add_avg("population")
+        #
+        #   aggregate_query.get do |aggregate_snapshot|
+        #     puts aggregate_snapshot.get
+        #   end
+        #
+        def add_avg field, aggregate_alias: nil
+          aggregate_alias ||= DEFAULT_AVG_ALIAS
+          field = FieldPath.parse field unless field.is_a? FieldPath
+          new_aggregate = Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation.new(
+            avg: Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation::Avg.new(
+              field: Google::Cloud::Firestore::V1::StructuredQuery::FieldReference.new(
+                field_path: field.formatted_string
+              )
+            ),
+            alias: aggregate_alias
+          )
+
+          start new_aggregate
+        end
+
+        ##
+        # @private
+        def start new_aggregate
+          combined_aggregates = [].concat(grpc.aggregations).concat([new_aggregate])
+          new_grpc = Google::Cloud::Firestore::V1::StructuredAggregationQuery.new(
+            structured_query: @query.query,
+            aggregations: combined_aggregates
+          )
+          self.class.new(@query, @parent_path, @client).tap do |aq|
+            aq.instance_variable_set :@grpc, new_grpc
+          end
         end
 
         ##
@@ -143,7 +245,7 @@ module Google
 
           return enum_for :get unless block_given?
 
-          responses = service.run_aggregate_query @parent_path, structured_aggregation_query
+          responses = service.run_aggregate_query @parent_path, @grpc
           responses.each do |response|
             next if response.result.nil?
             yield AggregateQuerySnapshot.from_run_aggregate_query_response response
@@ -151,32 +253,13 @@ module Google
         end
 
         ##
-        # @private Creates a Google::Cloud::Firestore::V1::StructuredAggregationQuery object
-        def structured_aggregation_query
-          StructuredAggregationQuery.new(
-            structured_query: @query,
-            aggregations: @aggregates
-          )
-        end
-
-        ##
-        # @private Start a new AggregateQuery.
-        def self.start query, aggregates, parent_path, client
-          new query, parent_path, client, aggregates: aggregates
+        # @private
+        def to_grpc
+          @grpc
         end
 
         protected
 
-        ##
-        # @private
-        StructuredAggregationQuery = Google::Cloud::Firestore::V1::StructuredAggregationQuery
-
-        ##
-        # @private
-        ALIASES = {
-          count: "count"
-        }.freeze
-
         ##
         # @private Raise an error unless a database is available.
         def ensure_client!

data/lib/google/cloud/firestore/aggregate_query_snapshot.rb

@@ -53,6 +53,19 @@ module Google
       #     puts aggregate_snapshot.get('total')
       #   end
       class AggregateQuerySnapshot
+        ##
+        # @private Object of type [Hash{String => Object}]
+        #
+        # String can have the following values:
+        #   - an aggregate literal "sum", "avg", or "count"
+        #   - a custom aggregate alias
+        # Object can have the following types:
+        #   - Integer
+        #   - Float
+        #   - nil
+        #   - NaN
+        attr_reader :aggregate_fields
+
         ##
         # Retrieves the aggregate data.
         #
@@ -60,7 +73,9 @@ module Google
         #   the aggregate value. For an AggregateQuery with a
         #   single aggregate field, this parameter can be omitted.
         #
-        # @return [Integer] The aggregate value.
+        # @return [Integer, Float, nil, NaN] The aggregate value.
+        #   Returns `nil` if the aggregate_alias does not exist.
+        #   Returns `NaN` if the aggregate field contains one or more NaN values.
         #
         # @example
         #   require "google/cloud/firestore"
@@ -104,11 +119,21 @@ module Google
         # @private New AggregateQuerySnapshot from a
         # Google::Cloud::Firestore::V1::RunAggregationQueryResponse object.
         def self.from_run_aggregate_query_response response
+          # rubocop:disable Style/MapToHash
           aggregate_fields = response
                              .result
                              .aggregate_fields
-                             .to_h # convert from protobuf to ruby map
-                             .transform_values { |v| v[:integer_value] }
+                             .map do |aggregate_alias, value| # convert from protobuf to ruby map
+                               if value.has_integer_value?
+                                 [aggregate_alias, value.integer_value]
+                               elsif value.has_double_value?
+                                 [aggregate_alias, value.double_value]
+                               elsif value.has_null_value?
+                                 [aggregate_alias, nil]
+                               end
+                             end
+                             .to_h
+          # rubocop:enable Style/MapToHash
 
           new.tap do |s|
             s.instance_variable_set :@aggregate_fields, aggregate_fields

data/lib/google/cloud/firestore/query.rb

@@ -1018,7 +1018,7 @@ module Google
         #   aggregate_query = query.aggregate_query
         #
         def aggregate_query
-          AggregateQuery.new query, parent_path, client
+          AggregateQuery.new self, parent_path, client
         end
 
         ##

data/lib/google/cloud/firestore/transaction.rb

@@ -305,7 +305,7 @@ module Google
           return enum_for :get_aggregate, aggregate_query unless block_given?
 
           results = service.run_aggregate_query aggregate_query.parent_path,
-                                                aggregate_query.structured_aggregation_query,
+                                                aggregate_query.to_grpc,
                                                 transaction: transaction_or_create
           results.each do |result|
             extract_transaction_from_result! result

data/lib/google/cloud/firestore/version.rb

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Firestore
-      VERSION = "2.13.1".freeze
+      VERSION = "2.14.0".freeze
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-firestore
 version: !ruby/object:Gem::Version
-  version: 2.13.1
+  version: 2.14.0
 platform: ruby
 authors:
 - Google Inc
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-06-16 00:00:00.000000000 Z
+date: 2024-01-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -283,7 +283,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.2
+rubygems_version: 3.5.3
 signing_key: 
 specification_version: 4
 summary: API Client library for Google Cloud Firestore API