google-cloud-firestore 2.13.0 → 2.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99ee040593be1625729cd2eae0d3a8bda03185c53692bec5fdfe18a32c2021f1
-  data.tar.gz: 26ff29bf53e07708590e92e9db03955ce1c1c60d671f7cf7fbd4dad52b3b8eab
+  metadata.gz: 9ff9b426ba1d870f0620a434f5e826f81cd878b09fa9aad5838d97245974b23c
+  data.tar.gz: 9f798211b2b5252f9992f1bf1f8c413cfd99154ee656c1b9d8e72ec6945fbc64
 SHA512:
-  metadata.gz: 56a3248b0d03ec14935cc78aa2e0ca6fcf63b810f1800dc96ba3d19b56c1546e914e7449c30cf56b8460d81c1b2e2210bdfaaf035405cf8c7e9909d05d7a9fba
-  data.tar.gz: 3cb3a0a89e2ef1d3707e4f30097e2019d62fee21354e6f1575cf29b5bd61121415945a2ff23735c8611af849c5399b6f30f01e58bd1c03f591baa55359f7cd1f
+  metadata.gz: 587f4928f11528d167b2f6649a1be0b43b29c109192c200c8825315e506671321345a4bd0880652be59d44ab3349dce5ea30dd84921a10d973539e9c67dfd691
+  data.tar.gz: 8df7d3795cc14f938b883877ee78940e2a0935b5494f799216676814533b2b77d35c66806a1677ada54a7430ed3868ce8be9b423a75dab7d60ea9b5444430040

data/AUTHENTICATION.md

@@ -124,15 +124,6 @@ To configure your system for this, simply:
 **NOTE:** This is _not_ recommended for running in production. The Cloud SDK
 *should* only be used during development.
 
-[gce-how-to]: https://cloud.google.com/compute/docs/authentication#using
-[dev-console]: https://console.cloud.google.com/project
-
-[enable-apis]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/enable-apis.png
-
-[create-new-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account.png
-[create-new-service-account-existing-keys]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account-existing-keys.png
-[reuse-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/reuse-service-account.png
-
 ## Creating a Service Account
 
 Google Cloud requires a **Project ID** and **Service Account Credentials** to
@@ -143,31 +134,22 @@ If you are not running this client within [Google Cloud Platform
 environments](#google-cloud-platform-environments), you need a Google
 Developers service account.
 
-1. Visit the [Google Developers Console][dev-console].
+1. Visit the [Google Cloud Console](https://console.cloud.google.com/project).
 1. Create a new project or click on an existing project.
-1. Activate the slide-out navigation tray and select **API Manager**. From
+1. Activate the menu in the upper left and select **APIs & Services**. From
    here, you will enable the APIs that your application requires.
 
-   ![Enable the APIs that your application requires][enable-apis]
-
    *Note: You may need to enable billing in order to use these services.*
 
 1. Select **Credentials** from the side navigation.
 
-   You should see a screen like one of the following.
-
-   ![Create a new service account][create-new-service-account]
-
-   ![Create a new service account With Existing Keys][create-new-service-account-existing-keys]
-
-   Find the "Add credentials" drop down and select "Service account" to be
-   guided through downloading a new JSON key file.
-
-   If you want to re-use an existing service account, you can easily generate a
-   new key file. Just select the account you wish to re-use, and click "Generate
-   new JSON key":
+   Find the "Create credentials" drop down near the top of the page, and select
+   "Service account" to be guided through downloading a new JSON key file.
 
-   ![Re-use an existing service account][reuse-service-account]
+   If you want to re-use an existing service account, you can easily generate 
+   a new key file. Just select the account you wish to re-use click the pencil
+   tool on the right side to edit the service account, select the **Keys** tab,
+   and then select **Add Key**.
 
    The key file you download will be used by this library to authenticate API
    requests and should be stored in a secure location.

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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
+
+* Fixed broken links in authentication documentation ([#21619](https://github.com/googleapis/google-cloud-ruby/issues/21619)) 
+
 ### 2.13.0 (2023-05-10)
 
 #### Features

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/convert.rb

@@ -365,7 +365,7 @@ module Google
               write.current_document = \
                 Google::Cloud::Firestore::V1::Precondition.new({
                   exists: exists, update_time: time_to_timestamp(update_time)
-                }.delete_if { |_, v| v.nil? })
+                }.compact)
             end
 
             write

data/lib/google/cloud/firestore/promise/future.rb

@@ -77,7 +77,7 @@ module Google
           #
           # @return [Future]
           # @yield [reason, *args] to the task.
-          def then(*args, &task)
+          def then *args, &task
             Future.new @future.then(*args, &task)
           end
 
@@ -87,7 +87,7 @@ module Google
           #
           # @return [Future]
           # @yield [reason, *args] to the task.
-          def rescue(*args, &task)
+          def rescue *args, &task
             Future.new @future.rescue(*args, &task)
           end
         end

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/service.rb

@@ -234,7 +234,7 @@ module Google
           Gapic::CallOptions.new(**{
             metadata:   default_headers(parent),
             page_token: token
-          }.delete_if { |_, v| v.nil? })
+          }.compact)
         end
 
         def document_mask mask

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.0".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.0
+  version: 2.14.0
 platform: ruby
 authors:
 - Google Inc
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-05-15 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