google-cloud-datastore 2.11.0 → 2.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0e7a2aaa0b31449724820d409981bc786ff520231f30e11d3f43fe5cd587e86
-  data.tar.gz: 3546b3b9d18c0c79c5c73927b1d4b1a3fad4bc523ee075caab61c287cfc5838d
+  metadata.gz: 00f4895cedca98c329cdcccad6094e454ba6884afc5f18b2b765660c5df92da6
+  data.tar.gz: 500ab2a00f401e8a69da2e4edb838072da922a149340fb56ecd148bf5aabfa1a
 SHA512:
-  metadata.gz: 326efcbff7b5b3b3d5982795b1408f87ee5225f5b7a25eedfdc1fe9403302e6bd39957737ff13faa16f438b3f5f32aa6538bddd9deb026844ac3935b40218505
-  data.tar.gz: cfbfc92c743af8fa804760fb8360c38b3756ea27f49ee60b1090cc4d563074aa6b5844dc5e10983884035993f0ba32490a1b885313fca7978a80a2b7ab8cc1b8
+  metadata.gz: 43730b11a7bbd83b69f2b495140fa752d8fee8deb6a729435fc99a7ff9e7d88f81628f209f7a852985d91b77cb3b9ca689edd09595ac9f71a49661bd57e0caef
+  data.tar.gz: 5a6d3307d349f0fcfeb115d73ead84a76f053f65b64b4398e943ee2d641a2a6e6dcb58c715bbee563fa48bb2f20e83b6fe71a78125019eac57c017eb5795ae8a

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Release History
 
+### 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
+
+* query explanation features for Cloud Datastore ([#30588](https://github.com/googleapis/google-cloud-ruby/issues/30588)) 
+
 ### 2.11.0 (2025-03-04)
 
 #### Features

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

@@ -40,22 +40,42 @@ module Google
         #
         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
+          # The result of the aggregation query, returned as a hash of key-value
+          # pairs. The key is the alias of the aggregate function, and the value
+          # is the result of the aggregation.
+          #
+          # The alias of the aggregate function can be:
+          #    - an aggregate literal "sum", "avg", or "count"
+          #    - a custom aggregate alias
+          #
+          # @return [Hash{String => Integer, Float}]
           attr_reader :aggregate_fields
 
           ##
-          # Read timestamp the query was done on the database at.
+          # The time when the query was executed.
           #
-          # @return Google::Protobuf::Timestamp
+          # @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, :explain_metrics, :explain_options
+
           ##
           # Retrieves the aggregate data.
           #
@@ -108,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 |s|
-              s.instance_variable_set :@aggregate_fields, aggregate_fields.to_h
-              s.instance_variable_set :@read_time, aggregate_query_response.batch.read_time
+            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 = read_time
             end
           end
         end

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

@@ -20,12 +20,12 @@ module Google
     module Datastore
       class Dataset
         ##
-        # LookupResults is a special case Array with additional values.
-        # A LookupResults object is returned from Dataset#find_all and
+        # {LookupResults} is a special case Array with additional values.
+        # A {LookupResults} object is returned from {Dataset#find_all} and
         # contains the entities as well as the Keys that were deferred from
         # the results and the Entities that were missing in the dataset.
         #
-        # Please be cautious when treating the QueryResults as an Array.
+        # Please be cautious when treating the {LookupResults} as an Array.
         # Many common Array methods will return a new Array instance.
         #
         # @example
@@ -55,21 +55,32 @@ module Google
         class LookupResults < DelegateClass(::Array)
           ##
           # The time at which these entities were read or found missing.
+          # @return [Google::Protobuf::Timestamp]
           attr_reader :response_read_time
 
           ##
           # Time at which the entities are being read. This would not be
           # older than 270 seconds.
+          #
+          # This is a copy of the input parameter supplied to the {Dataset#find_all} function.
+          #
+          # @return [Time, nil]
           attr_reader :read_time
 
           ##
           # Keys that were not looked up due to resource constraints.
+          # @return [Array<Google::Cloud::Datastore::Key>]
           attr_accessor :deferred
 
           ##
           # Entities not found, with only the key populated.
+          # @return [Array<Google::Cloud::Datastore::Entity>]
           attr_accessor :missing
 
+          ##
+          # @private
+          attr_writer :service, :consistency, :transaction, :response_read_time, :read_time
+
           ##
           # @private Create a new LookupResults with an array of values.
           def initialize arr = []
@@ -196,18 +207,19 @@ module Google
           ##
           # @private New Dataset::LookupResults from a
           # Google::Dataset::V1::LookupResponse object.
-          def self.from_grpc lookup_res, service, consistency = nil, transaction = nil, read_time = nil
-            entities = to_gcloud_entities lookup_res.found
-            deferred = to_gcloud_keys lookup_res.deferred
-            missing  = to_gcloud_entities lookup_res.missing
-            new(entities).tap do |lr|
-              lr.instance_variable_set :@service,     service
-              lr.instance_variable_set :@consistency, consistency
-              lr.instance_variable_set :@transaction, transaction
-              lr.instance_variable_set :@read_time, read_time
-              lr.instance_variable_set :@response_read_time, lookup_res.read_time
-              lr.instance_variable_set :@deferred,    deferred
-              lr.instance_variable_set :@missing,     missing
+          def self.from_grpc lookup_resp, service, consistency = nil, transaction = nil, read_time = nil
+            entities = to_gcloud_entities lookup_resp.found
+            deferred = to_gcloud_keys lookup_resp.deferred
+            missing  = to_gcloud_entities lookup_resp.missing
+
+            new(entities).tap do |lookup_results|
+              lookup_results.service = service
+              lookup_results.consistency = consistency
+              lookup_results.transaction = transaction
+              lookup_results.read_time = read_time
+              lookup_results.response_read_time = lookup_resp.read_time
+              lookup_results.deferred = deferred
+              lookup_results.missing = missing
             end
           end
 

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

@@ -70,6 +70,7 @@ module Google
           # * `:MORE_RESULTS_AFTER_LIMIT`
           # * `:MORE_RESULTS_AFTER_CURSOR`
           # * `:NO_MORE_RESULTS`
+          # @return [Symbol]
           attr_reader :more_results
 
           ##
@@ -83,20 +84,45 @@ module Google
           # is valid for all preceding batches.
           # This value will not be set for eventually consistent queries in Cloud
           # Datastore.
+          # @return [Google::Protobuf::Timestamp]
           attr_reader :batch_read_time
 
+          # Query explain metrics. This is only present when the
+          # [RunQueryRequest.explain_options][google.datastore.v1.RunQueryRequest.explain_options]
+          # is provided, and it is sent only once with or after the last QueryResults batch.
+          #
+          # To retrieve metrics, iterate over all QueryResults (e.g. with `next`). The explain_metrics
+          # field will be set on final QueryResults object.
+          #
+          # @return [Google::Cloud::Datastore::V1::ExplainMetrics, nil]
+          attr_reader :explain_metrics
+
           ##
           # Time at which the entities are being read. This would not be
           # older than 270 seconds.
+          #
+          # This is a copy of the input parameter supplied to the {Dataset#run} function.
+          #
+          # @return [Time, nil]
           attr_reader :read_time
 
+          ##
+          # The options for query explanation.
+          #
+          # This is a copy of the input parameter supplied to the {Dataset#run} function.
+          #
+          # @return [Google::Cloud::Datastore::V1::ExplainOptions, nil]
+          attr_reader :explain_options
+
           ##
           # @private
           attr_accessor :service, :namespace, :cursors, :query
 
           ##
           # @private
-          attr_writer :end_cursor, :more_results
+          attr_writer :end_cursor, :more_results, :explain_metrics, :read_time, :batch_read_time, :explain_options
+
+          ##
 
           ##
           # Convenience method for determining if the `more_results` value
@@ -153,6 +179,8 @@ module Google
             not_finished?
           end
 
+          # rubocop:disable Metrics/AbcSize
+
           ##
           # Retrieve the next page of results.
           #
@@ -180,10 +208,12 @@ module Google
               # Reduce the limit by the number of entities returned in the current batch
               query.limit.value -= count
             end
-            query_res = service.run_query query, namespace, read_time: read_time
-            self.class.from_grpc query_res, service, namespace, query, read_time
+            query_res = service.run_query query, namespace, read_time: read_time, explain_options: explain_options
+            self.class.from_grpc query_res, service, namespace, query, read_time, explain_options
           end
 
+          # rubocop:enable Metrics/AbcSize
+
           ##
           # Retrieve the {Cursor} for the provided result.
           #
@@ -375,27 +405,39 @@ module Google
             end
           end
 
+          # rubocop:disable Metrics/AbcSize
+
           ##
           # @private New Dataset::QueryResults from a
           # Google::Dataset::V1::RunQueryResponse object.
-          def self.from_grpc query_res, service, namespace, query, read_time = nil
-            r, c = Array(query_res.batch.entity_results).map do |result|
-              [Entity.from_grpc(result.entity), Cursor.from_grpc(result.cursor)]
-            end.transpose
+          def self.from_grpc query_res, service, namespace, query, read_time = nil, explain_options = nil
+            if query_res.batch
+              r, c = Array(query_res.batch.entity_results).map do |result|
+                [Entity.from_grpc(result.entity), Cursor.from_grpc(result.cursor)]
+              end.transpose
+            end
             r ||= []
             c ||= []
+
+            next_more_results = query_res.batch.more_results if query_res.batch
+            next_more_results ||= :NO_MORE_RESULTS
+
             new(r).tap do |qr|
               qr.cursors = c
-              qr.end_cursor = Cursor.from_grpc query_res.batch.end_cursor
-              qr.more_results = query_res.batch.more_results
+              qr.explain_metrics = query_res.explain_metrics
+              qr.end_cursor = Cursor.from_grpc query_res.batch.end_cursor if query_res.batch
+              qr.more_results = next_more_results
+              qr.read_time = read_time
+              qr.batch_read_time = query_res.batch.read_time if query_res.batch
+              qr.explain_options = explain_options
               qr.service = service
               qr.namespace = namespace
               qr.query = query_res.query || query
-              qr.instance_variable_set :@read_time, read_time
-              qr.instance_variable_set :@batch_read_time, query_res.batch.read_time
             end
           end
 
+          # rubocop:enable Metrics/AbcSize
+
           protected
 
           ##

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

@@ -416,7 +416,11 @@ module Google
         #   Datastore](https://cloud.google.com/datastore/docs/articles/balancing-strong-and-eventual-consistency-with-google-cloud-datastore/#h.tf76fya5nqk8)
         #   for more information.
         # @param [Time] read_time Reads entities as they were at the given time.
-        #   This may not be older than 270 seconds. Optional
+        #   This may not be older than 270 seconds. Optional.
+        # @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::QueryResults]
         #
@@ -467,16 +471,65 @@ module Google
         #                             done: false
         #   tasks = datastore.run gql_query, namespace: "example-ns"
         #
-        def run query, namespace: nil, consistency: nil, read_time: nil
+        # @example Run the query with explain options to get query plan and execution statistics.
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   query = datastore.query("Task")
+        #   results = datastore.run query, explain_options: { analyze: true }
+        #
+        #   # The explain_metrics are available on the results object only after
+        #   # all results have been retrieved. You must iterate through all
+        #   # pages of results to get the metrics.
+        #   all_tasks = []
+        #   loop do
+        #     results.each { |task| all_tasks << task }
+        #     break unless results.next?
+        #     results = results.next
+        #   end
+        #
+        #   # The `results` object now holds the last page of results,
+        #   # and contains the explain_metrics.
+        #   if results.explain_metrics
+        #     stats = results.explain_metrics.execution_stats
+        #     puts "Results returned: #{stats.results_returned}"
+        #     puts "Read operations: #{stats.read_operations}"
+        #   end
+        #
+        # @example Run the query with explain options using a `Google::Cloud::Datastore::V1::ExplainOptions` object.
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   query = datastore.query("Task")
+        #   explain_options = Google::Cloud::Datastore::V1::ExplainOptions.new
+        #   results = datastore.run query, explain_options: explain_options
+        #
+        #   # You must iterate through all pages of results to get the metrics.
+        #   loop do
+        #     break unless results.next?
+        #     results = results.next
+        #   end
+        #
+        #   if results.explain_metrics
+        #     stats = results.explain_metrics.execution_stats
+        #     puts "Read operations: #{stats.read_operations}"
+        #   end
+        #
+        def run query, namespace: nil, consistency: nil, read_time: nil, explain_options: nil
           ensure_service!
           unless query.is_a?(Query) || query.is_a?(GqlQuery)
             raise ArgumentError, "Cannot run a #{query.class} object."
           end
           check_consistency! consistency
+
           query_res = service.run_query query.to_grpc, namespace,
-                                        consistency: consistency, read_time: read_time
+                                        consistency: consistency, read_time: read_time,
+                                        explain_options: explain_options
+
           QueryResults.from_grpc query_res, service, namespace,
-                                 query.to_grpc.dup, read_time
+                                 query.to_grpc.dup, read_time, explain_options
         end
         alias run_query run
 
@@ -496,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]
         #
@@ -554,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

@@ -138,8 +138,11 @@ module Google
         # Retrieve entities specified by a Query. The query is run within the
         # transaction.
         #
-        # @param [Query] query The Query object with the search criteria.
+        # @param [Query, GqlQuery] query The query 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::QueryResults]
         #
@@ -154,15 +157,60 @@ module Google
         #     tasks = tx.run query
         #   end
         #
-        def run query, namespace: nil
+        # @example Run the query with explain options:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   datastore.read_only_transaction do |tx|
+        #     query = tx.query("Task")
+        #     results = tx.run query, explain_options: { analyze: true }
+        #
+        #     # You must iterate through all pages of results to get the metrics.
+        #     loop do
+        #       break unless results.next?
+        #       results = results.next
+        #     end
+        #
+        #     if results.explain_metrics
+        #       stats = results.explain_metrics.execution_stats
+        #       puts "Read operations: #{stats.read_operations}"
+        #     end
+        #   end
+        #
+        # @example Run the query with explain options using a `Google::Cloud::Datastore::V1::ExplainOptions` object.
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   datastore.read_only_transaction do |tx|
+        #     query = tx.query("Task")
+        #     explain_options = Google::Cloud::Datastore::V1::ExplainOptions.new
+        #     results = tx.run query, explain_options: explain_options
+        #
+        #     # You must iterate through all pages of results to get the metrics.
+        #     loop do
+        #       break unless results.next?
+        #       results = results.next
+        #     end
+        #
+        #     if results.explain_metrics
+        #       stats = results.explain_metrics.execution_stats
+        #       puts "Read operations: #{stats.read_operations}"
+        #     end
+        #   end
+        #
+        def run query, namespace: nil, explain_options: nil
           ensure_service!
           unless query.is_a?(Query) || query.is_a?(GqlQuery)
             raise ArgumentError, "Cannot run a #{query.class} object."
           end
           query_res = service.run_query query.to_grpc, namespace,
+                                        explain_options: explain_options,
                                         transaction: @id
+
           Dataset::QueryResults.from_grpc query_res, service, namespace,
-                                          query.to_grpc.dup
+                                          query.to_grpc.dup, nil, explain_options
         end
         alias run_query run
 
@@ -188,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"
         #
-        def run_aggregation aggregate_query, namespace: nil
+        #   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, 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

@@ -70,7 +70,12 @@ module Google
         end
 
         # Query for entities.
-        def run_query query, namespace = nil, consistency: nil, transaction: nil, read_time: nil
+        def run_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
@@ -88,11 +93,20 @@ module Google
                             partition_id: partition_id,
                             read_options: read_options,
                             query: query,
-                            gql_query: gql_query
+                            gql_query: gql_query,
+                            explain_options: explain_options
         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
@@ -109,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
 
         ##
@@ -174,6 +189,17 @@ module Google
           nil
         end
 
+        ##
+        # @private Converts a time-like object to a Google::Protobuf::Timestamp.
+        #
+        #   Any object that responds to `#to_time` is a valid input.
+        #
+        # @param time [Time, DateTime, Google::Protobuf::Timestamp, nil] The
+        #   time object to convert. If `nil`, `nil` will be returned.
+        #
+        # @return [Google::Protobuf::Timestamp, nil] The converted Protobuf timestamp,
+        #   or `nil` if the input was `nil`.
+        #
         def read_time_to_timestamp time
           return nil if time.nil?
 

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

@@ -225,8 +225,11 @@ module Google
         # Retrieve entities specified by a Query. The query is run within the
         # transaction.
         #
-        # @param [Query] query The Query object with the search criteria.
+        # @param [Query, GqlQuery] query The query 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::QueryResults]
         #
@@ -251,18 +254,115 @@ module Google
         #     tasks = tx.run query, namespace: "example-ns"
         #   end
         #
-        def run query, namespace: nil
+        # @example Run the query with explain options:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   datastore.transaction do |tx|
+        #     query = datastore.query("Task")
+        #     results = tx.run query, explain_options: { analyze: true }
+        #
+        #     # You must iterate through all pages of results to get the metrics.
+        #     loop do
+        #       break unless results.next?
+        #       results = results.next
+        #     end
+        #
+        #     if results.explain_metrics
+        #       stats = results.explain_metrics.execution_stats
+        #       puts "Read operations: #{stats.read_operations}"
+        #     end
+        #   end
+        #
+        # @example Run the query with explain options using a `Google::Cloud::Datastore::V1::ExplainOptions` object.
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   datastore.transaction do |tx|
+        #     query = datastore.query("Task")
+        #     explain_options = Google::Cloud::Datastore::V1::ExplainOptions.new
+        #     results = tx.run query, explain_options: explain_options
+        #
+        #     # You must iterate through all pages of results to get the metrics.
+        #     loop do
+        #       break unless results.next?
+        #       results = results.next
+        #     end
+        #
+        #     if results.explain_metrics
+        #       stats = results.explain_metrics.execution_stats
+        #       puts "Read operations: #{stats.read_operations}"
+        #     end
+        #   end
+        #
+        def run query, namespace: nil, explain_options: nil
           ensure_service!
           unless query.is_a?(Query) || query.is_a?(GqlQuery)
             raise ArgumentError, "Cannot run a #{query.class} object."
           end
           query_res = service.run_query query.to_grpc, namespace,
+                                        explain_options: explain_options,
                                         transaction: @id
           QueryResults.from_grpc query_res, service, namespace,
-                                 query.to_grpc.dup
+                                 query.to_grpc.dup, nil, explain_options
         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.11.0".freeze
+      VERSION = "2.13.0".freeze
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-datastore
 version: !ruby/object:Gem::Version
-  version: 2.11.0
+  version: 2.13.0
 platform: ruby
 authors:
 - Mike Moore
 - Chris Smith
 bindir: bin
 cert_chain: []
-date: 2025-03-04 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -102,7 +102,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.5
+rubygems_version: 3.6.9
 specification_version: 4
 summary: API Client library for Google Cloud Datastore
 test_files: []