google-cloud-datastore 2.7.0 → 2.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b372b670c25604994c20b79779906b9a7c00b21bdf3ada9a23eb2cbb5968d053
-  data.tar.gz: 2cb8cac3d2de7b1b631d1c9ee7332b7391a73a720968bf09dc0608430de2a472
+  metadata.gz: 6c062edd7866b2d8f56365618cdbfca915d1df66440e9bdfca54d4e85bbc0133
+  data.tar.gz: c4085c6ba18cd98c6ec7f38b6487dfbab56dd00030eb3dcad70afa184772056e
 SHA512:
-  metadata.gz: dba07c333a2230e08f4c315dce2b8e28c748a082561c0692d9e419ba47565496b4b47463912e6cebea34ca3c33732df257ec6b4bcd9419b664cc16a4338b9b76
-  data.tar.gz: e817d031036cefd768ccf202a291435c6a710f69292ea61f2349bd5456732b3e0253ce94c75006abbcbc231c6c6e664bd4340dd2836f20978542dc2bb30b3b45
+  metadata.gz: 9621f21518ea67ebedcd0230f16b240976152d99133b2e0e4ecb7a770e92079e47a44868925cb7ac4aaeef8030a6138ef2842836749b4274c9a5ada151eeae28
+  data.tar.gz: 0dbf0d457be8a4b94e6be54a7eaae13ea31113d818025ed59905fc3c7bbd64c3c10bff2fbb36519f3a94cd17f0b901bfb9029d837e5a4c36f73282ef39012997

data/AUTHENTICATION.md

@@ -125,15 +125,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
@@ -144,31 +135,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.8.0 (2023-09-12)
+
+#### Features
+
+* Support sum & avg aggregate functions ([#22884](https://github.com/googleapis/google-cloud-ruby/issues/22884)) 
+
+### 2.7.1 (2023-05-18)
+
+#### Documentation
+
+* Fixed broken links in authentication documentation ([#21619](https://github.com/googleapis/google-cloud-ruby/issues/21619)) 
+
 ### 2.7.0 (2023-04-12)
 
 #### Features

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

@@ -56,19 +56,30 @@ module Google
       #   puts aggregate_query_results.get('total')
       #
       class AggregateQuery
-        ##
-        # @private The Google::Cloud::Datastore::V1::Query object.
-        attr_reader :query
+        # @private
+        DEFAULT_COUNT_AGGREGATE_ALIAS = "count".freeze
+
+        # @private
+        DEFAULT_SUM_AGGREGATE_ALIAS = "sum".freeze
+
+        # @private
+        DEFAULT_AVG_AGGREGATE_ALIAS = "avg".freeze
 
         ##
-        # @private Array of Google::Cloud::Datastore::V1::AggregationQuery::Aggregation objects
-        attr_reader :aggregates
+        # @private The Google::Cloud::Datastore::V1::AggregationQuery object.
+        attr_reader :grpc
 
         ##
-        # @private Creates a new AggregateQuery
+        # @private
+        #
+        # Returns a new AggregateQuery object
+        #
+        # @param query [Google::Cloud::Datastore::V1::Query]
         def initialize query
-          @query = query
-          @aggregates = []
+          @grpc = Google::Cloud::Datastore::V1::AggregationQuery.new(
+            nested_query: query,
+            aggregations: []
+          )
         end
 
         ##
@@ -111,8 +122,8 @@ module Google
         #   puts aggregate_query_results.get('total')
         #
         def add_count aggregate_alias: nil
-          aggregate_alias ||= ALIASES[:count]
-          aggregates << Google::Cloud::Datastore::V1::AggregationQuery::Aggregation.new(
+          aggregate_alias ||= DEFAULT_COUNT_AGGREGATE_ALIAS
+          @grpc.aggregations << Google::Cloud::Datastore::V1::AggregationQuery::Aggregation.new(
             count: Google::Cloud::Datastore::V1::AggregationQuery::Aggregation::Count.new,
             alias: aggregate_alias
           )
@@ -120,19 +131,118 @@ module Google
           self
         end
 
-        # @private
-        def to_grpc
-          Google::Cloud::Datastore::V1::AggregationQuery.new(
-            nested_query: query,
-            aggregations: aggregates
+        ##
+        # Adds a sum aggregate.
+        #
+        # @param name [String] The property to sum by.
+        # @param aggregate_alias [String] Alias to refer to the aggregate. Optional
+        #
+        # @return [AggregateQuery] The modified aggregate query object with the added SUM aggregate.
+        #
+        # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   query = Google::Cloud::Datastore::Query.new
+        #   query.kind("Task")
+        #        .where("done", "=", false)
+        #
+        #   Create an aggregate query
+        #   aggregate_query = query.aggregate_query
+        #                          .add_sum("score")
+        #
+        #   aggregate_query_results = dataset.run_aggregation aggregate_query
+        #   puts aggregate_query_results.get
+        #
+        # @example Alias an aggregate SUM query
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   query = Google::Cloud::Datastore::Query.new
+        #   query.kind("Task")
+        #        .where("done", "=", false)
+        #
+        #   # Create an aggregate query
+        #   aggregate_query = query.aggregate_query
+        #                          .add_sum("score", aggregate_alias: 'total_score')
+        #
+        #   aggregate_query_results = dataset.run_aggregation aggregate_query
+        #   puts aggregate_query_results.get('total_score')
+        #
+        def add_sum name, aggregate_alias: nil
+          aggregate_alias ||= DEFAULT_SUM_AGGREGATE_ALIAS
+          @grpc.aggregations << Google::Cloud::Datastore::V1::AggregationQuery::Aggregation.new(
+            sum: Google::Cloud::Datastore::V1::AggregationQuery::Aggregation::Sum.new(
+              property: Google::Cloud::Datastore::V1::PropertyReference.new(
+                name: name
+              )
+            ),
+            alias: aggregate_alias
           )
+
+          self
         end
 
         ##
+        # Adds an average aggregate.
+        #
+        # @param name [String] The property to apply average on.
+        # @param aggregate_alias [String] Alias to refer to the aggregate. Optional
+        #
+        # @return [AggregateQuery] The modified aggregate query object with the added AVG aggregate.
+        #
+        # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   query = Google::Cloud::Datastore::Query.new
+        #   query.kind("Task")
+        #        .where("done", "=", false)
+        #
+        #   Create an aggregate query
+        #   aggregate_query = query.aggregate_query
+        #                          .add_avg("score")
+        #
+        #   aggregate_query_results = dataset.run_aggregation aggregate_query
+        #   puts aggregate_query_results.get
+        #
+        # @example Alias an aggregate AVG query
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   query = Google::Cloud::Datastore::Query.new
+        #   query.kind("Task")
+        #        .where("done", "=", false)
+        #
+        #   # Create an aggregate query
+        #   aggregate_query = query.aggregate_query
+        #                          .add_avg("score", aggregate_alias: 'avg_score')
+        #
+        #   aggregate_query_results = dataset.run_aggregation aggregate_query
+        #   puts aggregate_query_results.get('avg_score')
+        #
+        def add_avg name, aggregate_alias: nil
+          aggregate_alias ||= DEFAULT_AVG_AGGREGATE_ALIAS
+          @grpc.aggregations << Google::Cloud::Datastore::V1::AggregationQuery::Aggregation.new(
+            avg: Google::Cloud::Datastore::V1::AggregationQuery::Aggregation::Avg.new(
+              property: Google::Cloud::Datastore::V1::PropertyReference.new(
+                name: name
+              )
+            ),
+            alias: aggregate_alias
+          )
+
+          self
+        end
+
         # @private
-        ALIASES = {
-          count: "count"
-        }.freeze
+        def to_grpc
+          @grpc
+        end
       end
     end
   end

data/lib/google/cloud/datastore/dataset/aggregate_query_results.rb

@@ -39,6 +39,17 @@ module Google
         #   puts aggregate_query_results.get
         #
         class AggregateQueryResults
+          ##
+          # @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
+          attr_reader :aggregate_fields
+
           ##
           # Read timestamp the query was done on the database at.
           #
@@ -52,7 +63,8 @@ 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] The aggregate value. Returns `nil`
+          # if the aggregate_alias does not exist.
           #
           # @example
           #   require "google/cloud/datastore"
@@ -101,8 +113,15 @@ module Google
                                .batch
                                .aggregation_results[0]
                                .aggregate_properties
+                               .map do |aggregate_alias, value|
+                                 if value.has_integer_value?
+                                   [aggregate_alias, value.integer_value]
+                                 else
+                                   [aggregate_alias, value.double_value]
+                                 end
+                               end
                                .to_h
-                               .transform_values { |v| v[:integer_value] }
+
             new.tap do |s|
               s.instance_variable_set :@aggregate_fields, aggregate_fields
               s.instance_variable_set :@read_time, aggregate_query_response.batch.read_time

data/lib/google/cloud/datastore/dataset.rb

@@ -987,8 +987,8 @@ module Google
         #
         # @param name [String] The property to filter by.
         # @param operator [String] The operator to filter by. Defaults to nil.
-        # @param value The value to compare the property to. Defaults to nil.
-        #       Possible values are:
+        # @param value [Object] The value to compare the property to. Defaults
+        #       to nil. Possible values are:
         #         - Integer
         #         - Float/BigDecimal
         #         - String

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Datastore
-      VERSION = "2.7.0".freeze
+      VERSION = "2.8.0".freeze
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-datastore
 version: !ruby/object:Gem::Version
-  version: 2.7.0
+  version: 2.8.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-04-12 00:00:00.000000000 Z
+date: 2023-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -238,7 +238,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.2
+rubygems_version: 3.4.19
 signing_key: 
 specification_version: 4
 summary: API Client library for Google Cloud Datastore