google-cloud-datastore 2.12.0 → 2.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8eddd9d4fceb6e041d7500b67922f0501aac4fef8bf151739a76cd5b7d244976
-  data.tar.gz: e16e145cca01e0cb0dd2eef3c48243592444bade8f9d7da6cb2836a7ef161957
+  metadata.gz: 96ae4fca8972cf097e7b6b10d73e709ecef3d409fc68c96cae5ebcb7058c2d1b
+  data.tar.gz: 43c974a4d78a4533403e854d4e6ead63b19307c390e1cd1ed87194562ddde1f0
 SHA512:
-  metadata.gz: b93ac90c3b8f2b2abcd70ae70be0b9a2ed2b162c425cbac57ab125a1569c9b67bd9d6f045c9a59cf8bf483fe39f565721d210193ee4963217107ede2ae712c69
-  data.tar.gz: 575f1f885078facd39cf006a5a218402f68add5e602bca839bd6cde28c8c4a068b46501a2371c1b89a3b2e0653d4ad522a56f5b23731087a06cd8179974c40a0
+  metadata.gz: ed233508a15ee0c5adeed09f82435be5c9517a045e3b48fe46bfc2503bac49f82863b085ea630a20419232ba852b785377572fbc61dc1ba6048c4bf54415347a
+  data.tar.gz: c79f29a8601d877a7f32860b173350977eb8c94a50a4cd2c2b3a1ae3145e90762b525a2603f949c98f6cc6cc96d54b1d4ac049e6f20a3538c64ae4f11bb1e32c

data/AUTHENTICATION.md

@@ -46,6 +46,12 @@ code.
 
 **Credentials** are discovered in the following order:
 
+> [!WARNING]
+> If you accept a credential configuration (JSON file or Hash) from an
+> external source for authentication to Google Cloud, you must validate it before
+> providing it to a Google API client library. Providing an unvalidated credential
+> configuration to Google APIs can compromise the security of your systems and data.
+
 1. Specify credentials in method arguments
 2. Specify credentials in configuration
 3. Discover credentials path in environment variables
@@ -100,11 +106,16 @@ The **Project ID** and the path to the **Credentials JSON** file can be configur
 instead of placing them in environment variables or providing them as arguments.
 
 ```ruby
+require "googleauth"
 require "google/cloud/datastore"
 
+credentials = ::Google::Auth::ServiceAccountCredentials.make_creds(
+  json_key_io: ::File.open("/path/to/keyfile.json")
+)
+
 Google::Cloud::Datastore.configure do |config|
   config.project_id  = "my-project-id"
-  config.credentials = "path/to/keyfile.json"
+  config.credentials = credentials
 end
 
 client = Google::Cloud::Datastore.new

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Release History
 
+### 2.13.1 (2025-11-04)
+
+#### Documentation
+
+* add warning about loading unvalidated credentials ([#32121](https://github.com/googleapis/google-cloud-ruby/issues/32121)) 
+
+### 2.13.0 (2025-07-24)
+
+#### Features
+
+* add explain query features to aggregate query in Cloud Datastore ([#30704](https://github.com/googleapis/google-cloud-ruby/issues/30704)) 
+
 ### 2.12.0 (2025-07-15)
 
 #### Features

data/OVERVIEW.md

@@ -14,11 +14,16 @@ your code or via environment variables. Read more about the options for
 connecting in the {file:AUTHENTICATION.md Authentication Guide}.
 
 ```ruby
+require "googleauth"
 require "google/cloud/datastore"
 
+credentials = ::Google::Auth::ServiceAccountCredentials.make_creds(
+  json_key_io: ::File.open("/path/to/keyfile.json")
+)
+
 datastore = Google::Cloud::Datastore.new(
   project_id: "my-todo-project",
-  credentials: "/path/to/keyfile.json"
+  credentials: credentials
 )
 
 task = datastore.find "Task", "sampleTask"

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

@@ -57,9 +57,24 @@ module Google
           # @return [Google::Protobuf::Timestamp]
           attr_reader :read_time
 
+          # Query explain metrics. This is only present when the `explain_options`
+          # are provided to {Google::Cloud::Datastore::Dataset#run_aggregation}.
+          # It is sent only once with the response.
+          #
+          # @return [Google::Cloud::Datastore::V1::ExplainMetrics, nil]
+          attr_reader :explain_metrics
+
+          ##
+          # The options for query explanation.
+          #
+          # This is a copy of the input parameter supplied to the {Dataset#run_aggregation} function.
+          #
+          # @return [Google::Cloud::Datastore::V1::ExplainOptions, nil]
+          attr_reader :explain_options
+
           ##
           # @private
-          attr_writer :aggregate_fields, :read_time
+          attr_writer :aggregate_fields, :read_time, :explain_metrics, :explain_options
 
           ##
           # Retrieves the aggregate data.
@@ -113,22 +128,33 @@ module Google
           ##
           # @private New AggregateQueryResults from a
           # Google::Cloud::Datastore::V1::RunAggregationQueryResponse object.
-          def self.from_grpc aggregate_query_response
-            aggregate_fields = aggregate_query_response
-                               .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
+          def self.from_grpc aggregate_query_response, explain_options
+            # If the aggregate query is run with explain_options and analyze = false,
+            # the RunAggregationQueryResponse will not have batch results
+            # only explain metrics.
+            aggregate_fields = {}
+            read_time = nil
+
+            if aggregate_query_response.batch
+              aggregate_fields = aggregate_query_response
+                                 .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
+              read_time = aggregate_query_response.batch.read_time
+            end
 
             new.tap do |aq_result|
+              aq_result.explain_options = explain_options
+              aq_result.explain_metrics = aggregate_query_response.explain_metrics
               aq_result.aggregate_fields = aggregate_fields.to_h
-              aq_result.read_time = aggregate_query_response.batch.read_time
+              aq_result.read_time = read_time
             end
           end
         end

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

@@ -549,6 +549,10 @@ module Google
         #   [Eventual Consistency in Google Cloud
         #   Datastore](https://cloud.google.com/datastore/docs/articles/balancing-strong-and-eventual-consistency-with-google-cloud-datastore/#h.tf76fya5nqk8)
         #   for more information.
+        # @param [Hash, Google::Cloud::Datastore::V1::ExplainOptions] explain_options The options for query explanation.
+        #   Provide this argument to enable explain metrics. If this argument is left unset,
+        #   the results will not include explain metrics.
+        #   See {Google::Cloud::Datastore::V1::ExplainOptions} for details. Optional.
         #
         # @return [Google::Cloud::Datastore::Dataset::AggregateQueryResults]
         #
@@ -607,15 +611,32 @@ module Google
         #                             done: false
         #   res = datastore.run_aggregation gql_query, namespace: "example-ns"
         #
-        def run_aggregation aggregate_query, namespace: nil, consistency: nil, read_time: nil
+        # @example Run the aggregate query with explain options to get query plan and execution statistics.
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   query = datastore.query("Task")
+        #   aggregate_query = query.aggregate_query.add_count aggregate_alias: "total"
+        #   results = datastore.run_aggregation aggregate_query, explain_options: { analyze: true }
+        #
+        #   if results.explain_metrics
+        #     stats = results.explain_metrics.execution_stats
+        #     puts "Read operations: #{stats.read_operations}"
+        #   end
+        #
+        def run_aggregation aggregate_query, namespace: nil, consistency: nil, read_time: nil, explain_options: nil
           ensure_service!
           unless aggregate_query.is_a?(AggregateQuery) || aggregate_query.is_a?(GqlQuery)
             raise ArgumentError, "Cannot run a #{aggregate_query.class} object."
           end
           check_consistency! consistency
           aggregate_query_res = service.run_aggregation_query aggregate_query.to_grpc, namespace,
-                                                              consistency: consistency, read_time: read_time
-          AggregateQueryResults.from_grpc aggregate_query_res
+                                                              consistency: consistency,
+                                                              read_time: read_time,
+                                                              explain_options: explain_options
+
+          AggregateQueryResults.from_grpc aggregate_query_res, explain_options
         end
 
         ##

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

@@ -236,14 +236,34 @@ module Google
         #                            .add_count
         #     res = tx.run_aggregation aggregate_query
         #   end
+        # @example Run the aggregate query with explain options:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   datastore.read_only_transaction do |tx|
+        #     query = tx.query("Task")
+        #     aggregate_query = query.aggregate_query.add_count aggregate_alias: "total"
+        #     results = tx.run_aggregation aggregate_query, explain_options: { analyze: true }
+        #
+        #     if results.explain_metrics
+        #       stats = results.explain_metrics.execution_stats
+        #       puts "Read operations: #{stats.read_operations}"
+        #     end
+        #   end
         #
-        def run_aggregation aggregate_query, namespace: nil
+        def run_aggregation aggregate_query, namespace: nil, explain_options: nil
           ensure_service!
           unless aggregate_query.is_a?(AggregateQuery) || aggregate_query.is_a?(GqlQuery)
             raise ArgumentError, "Cannot run a #{aggregate_query.class} object."
           end
-          aggregate_query_results = service.run_aggregation_query aggregate_query.to_grpc, namespace, transaction: @id
-          Dataset::AggregateQueryResults.from_grpc aggregate_query_results
+
+          aggregate_query_results = service.run_aggregation_query aggregate_query.to_grpc,
+                                                                  namespace,
+                                                                  transaction: @id,
+                                                                  explain_options: explain_options
+
+          Dataset::AggregateQueryResults.from_grpc aggregate_query_results, explain_options
         end
 
         ##

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

@@ -98,7 +98,15 @@ module Google
         end
 
         ## Query for aggregates
-        def run_aggregation_query query, namespace = nil, consistency: nil, transaction: nil, read_time: nil
+        def run_aggregation_query query, namespace = nil, consistency: nil, transaction: nil, read_time: nil,
+                                  explain_options: nil
+          if explain_options
+            explain_options = ::Gapic::Protobuf.coerce(
+              explain_options,
+              to: ::Google::Cloud::Datastore::V1::ExplainOptions
+            )
+          end
+
           gql_query = nil
           if query.is_a? Google::Cloud::Datastore::V1::GqlQuery
             gql_query = query
@@ -115,7 +123,8 @@ module Google
                                         partition_id: partition_id,
                                         read_options: read_options,
                                         aggregation_query: query,
-                                        gql_query: gql_query
+                                        gql_query: gql_query,
+                                        explain_options: explain_options
         end
 
         ##

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

@@ -310,6 +310,59 @@ module Google
         end
         alias run_query run
 
+        ##
+        # Retrieve aggregate query results specified by an AggregateQuery. The query is run within the
+        # transaction.
+        #
+        # @param [AggregateQuery, GqlQuery] aggregate_query The Query object
+        #   with the search criteria.
+        # @param [String] namespace The namespace the query is to run within.
+        # @param [Hash, Google::Cloud::Datastore::V1::ExplainOptions] explain_options
+        #   The options for query explanation. See {Google::Cloud::Datastore::V1::ExplainOptions}
+        #   for details. Optional.
+        #
+        # @return [Google::Cloud::Datastore::Dataset::AggregateQueryResults]
+        #
+        # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   datastore.transaction do |tx|
+        #     query = tx.query("Task")
+        #               .where("done", "=", false)
+        #     aggregate_query = query.aggregate_query
+        #                            .add_count
+        #     res = tx.run_aggregation aggregate_query
+        #   end
+        #
+        # @example Run the aggregate query with explain options:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   datastore.transaction do |tx|
+        #     query = tx.query("Task")
+        #     aggregate_query = query.aggregate_query.add_count aggregate_alias: "total"
+        #     results = tx.run_aggregation aggregate_query, explain_options: { analyze: true }
+        #
+        #     if results.explain_metrics
+        #       stats = results.explain_metrics.execution_stats
+        #       puts "Read operations: #{stats.read_operations}"
+        #     end
+        #   end
+        #
+        def run_aggregation aggregate_query, namespace: nil, explain_options: nil
+          ensure_service!
+          unless aggregate_query.is_a?(AggregateQuery) || aggregate_query.is_a?(GqlQuery)
+            raise ArgumentError, "Cannot run a #{aggregate_query.class} object."
+          end
+          aggregate_query_results = service.run_aggregation_query aggregate_query.to_grpc, namespace,
+                                                                  transaction: @id,
+                                                                  explain_options: explain_options
+          Dataset::AggregateQueryResults.from_grpc aggregate_query_results, explain_options
+        end
+
         ##
         # Begins a transaction.
         # This method is run when a new Transaction is created.

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

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

data/lib/google/cloud/datastore.rb

@@ -58,9 +58,27 @@ module Google
       #
       # @param [String] project_id Identifier for a Datastore project. If not
       #   present, the default project for the credentials is used.
-      # @param [String, Hash, Google::Auth::Credentials] credentials The path to
-      #   the keyfile as a String, the contents of the keyfile as a Hash, or a
-      #   Google::Auth::Credentials object. (See {Datastore::Credentials})
+      # @param [Google::Auth::Credentials] credentials A Google::Auth::Credentials
+      #   object. (See {Datastore::Credentials})
+      #   @note Warning: Passing a `String` to a keyfile path or a `Hash` of credentials
+      #     is deprecated. Providing an unvalidated credential configuration to
+      #     Google APIs can compromise the security of your systems and data.
+      #
+      #   @example
+      #
+      #     # The recommended way to provide credentials is to use the `make_creds` method
+      #     # on the appropriate credentials class for your environment.
+      #
+      #     require "googleauth"
+      #
+      #     credentials = ::Google::Auth::ServiceAccountCredentials.make_creds(
+      #       json_key_io: ::File.open("/path/to/keyfile.json")
+      #     )
+      #
+      #     datastore = Google::Cloud::Datastore.new(
+      #       project_id: "my-project-id",
+      #       credentials: credentials
+      #     )
       # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling
       #   the set of resources and operations that the connection can access.
       #   See [Using OAuth 2.0 to Access Google

data/lib/google-cloud-datastore.rb

@@ -84,9 +84,25 @@ module Google
     #
     # @param [String] project_id Identifier for a Datastore project. If not
     #   present, the default project for the credentials is used.
-    # @param [String, Hash, Google::Auth::Credentials] credentials The path to
-    #   the keyfile as a String, the contents of the keyfile as a Hash, or a
-    #   Google::Auth::Credentials object. (See {Datastore::Credentials})
+    # @param [Google::Auth::Credentials] credentials A Google::Auth::Credentials
+    #   object. (See {Datastore::Credentials})
+    #   @note Warning: Passing a `String` to a keyfile path or a `Hash` of credentials
+    #     is deprecated. Providing an unvalidated credential configuration to
+    #     Google APIs can compromise the security of your systems and data.
+    #
+    #   @example
+    #
+    #     # The recommended way to provide credentials is to use the `make_creds` method
+    #     # on the appropriate credentials class for your environment.
+    #
+    #     credentials = ::Google::Auth::ServiceAccountCredentials.make_creds(
+    #       json_key_io: ::File.open("/path/to/keyfile.json")
+    #     )
+    #
+    #     datastore = Google::Cloud::Datastore.new(
+    #       project_id: "my-project-id",
+    #       credentials: credentials
+    #     )
     # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
     #   set of resources and operations that the connection can access. See
     #   [Using OAuth 2.0 to Access Google

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-datastore
 version: !ruby/object:Gem::Version
-  version: 2.12.0
+  version: 2.13.1
 platform: ruby
 authors:
 - Mike Moore