google-cloud-datastore 2.11.0 → 2.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0e7a2aaa0b31449724820d409981bc786ff520231f30e11d3f43fe5cd587e86
-  data.tar.gz: 3546b3b9d18c0c79c5c73927b1d4b1a3fad4bc523ee075caab61c287cfc5838d
+  metadata.gz: 8eddd9d4fceb6e041d7500b67922f0501aac4fef8bf151739a76cd5b7d244976
+  data.tar.gz: e16e145cca01e0cb0dd2eef3c48243592444bade8f9d7da6cb2836a7ef161957
 SHA512:
-  metadata.gz: 326efcbff7b5b3b3d5982795b1408f87ee5225f5b7a25eedfdc1fe9403302e6bd39957737ff13faa16f438b3f5f32aa6538bddd9deb026844ac3935b40218505
-  data.tar.gz: cfbfc92c743af8fa804760fb8360c38b3756ea27f49ee60b1090cc4d563074aa6b5844dc5e10983884035993f0ba32490a1b885313fca7978a80a2b7ab8cc1b8
+  metadata.gz: b93ac90c3b8f2b2abcd70ae70be0b9a2ed2b162c425cbac57ab125a1569c9b67bd9d6f045c9a59cf8bf483fe39f565721d210193ee4963217107ede2ae712c69
+  data.tar.gz: 575f1f885078facd39cf006a5a218402f68add5e602bca839bd6cde28c8c4a068b46501a2371c1b89a3b2e0653d4ad522a56f5b23731087a06cd8179974c40a0

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Release History
 
+### 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,27 @@ module Google
         #
         class AggregateQueryResults
           ##
-          # @private Object of type [Hash{String => Object}].
+          # 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.
           #
-          # 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 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
 
+          ##
+          # @private
+          attr_writer :aggregate_fields, :read_time
+
           ##
           # Retrieves the aggregate data.
           #
@@ -121,9 +126,9 @@ module Google
                                  end
                                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.aggregate_fields = aggregate_fields.to_h
+              aq_result.read_time = aggregate_query_response.batch.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
 

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
 

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,7 +93,8 @@ 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
@@ -174,6 +180,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,15 +254,59 @@ 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
 

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Datastore
-      VERSION = "2.11.0".freeze
+      VERSION = "2.12.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.12.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: []