google-cloud-firestore 3.0.0 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 308b67067868ac77277cef71c5d5fffcb80683344cf9e4e53c82dd7f94d0214e
-  data.tar.gz: 18549006ffbf3d7c31d691cd5aa08aca8365ce2462ae3459cc23e423e7017b59
+  metadata.gz: eadae80e15a9c84121d9d2966f27c4698b84582f1c3e4b8124d5676bf9583ffb
+  data.tar.gz: 688e905687f52e469da3325d60b7eb30112082bd8487a501743d3463b27ac0fb
 SHA512:
-  metadata.gz: a73c2637872557c0c295e5513d6f95f1e51271f1881ebcbce1b21797239f4a19e0672966e05bd1bfce01d6766c96760579a04c63db5c6b21a1dfb42e7159d7ee
-  data.tar.gz: 597ae0aa8b48466143524529533e8ebe5cc8512117550432cf1456c890d6cec98e3e60fe351dda4d9cbb3e00ceb778e537e0f1d04d952d0efb7bd4b1b7181334
+  metadata.gz: 4ea41f51137087f2e3a415b2fa5db3d5ca32f642be8ec60121f10fb4d685f44dd14d4ec12483f71740ff5bae9fe865cbad8ac2949fcb8c6a6eb4c6446509c66a
+  data.tar.gz: 9c704585160b7bfa428bb8e1da76309c2d033f873a6fa67739cc1459ccdd484e33dbbc377a6591755dbe22498734e012225c16c191e21388527427d22fe57fdb

data/.yardopts

@@ -11,6 +11,7 @@ OVERVIEW.md
 AUTHENTICATION.md
 EMULATOR.md
 LOGGING.md
+QUERY_PERFORMANCE.md
 CONTRIBUTING.md
 TROUBLESHOOTING.md
 CHANGELOG.md

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
@@ -99,11 +105,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/firestore"
 
+credentials = ::Google::Auth::ServiceAccountCredentials.make_creds(
+  json_key_io: ::File.open("/path/to/keyfile.json")
+)
+
 Google::Cloud::Firestore.configure do |config|
   config.project_id  = "my-project-id"
-  config.credentials = "path/to/keyfile.json"
+  config.credentials = credentials
 end
 
 client = Google::Cloud::Firestore.new

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Release History
 
+### 3.1.1 (2025-10-31)
+
+#### Documentation
+
+* add warning about loading unvalidated credentials ([#32121](https://github.com/googleapis/google-cloud-ruby/issues/32121)) 
+
+### 3.1.0 (2025-08-07)
+
+#### Features
+
+* add AggregateQuery explanation features for RubyFirestore ([#30484](https://github.com/googleapis/google-cloud-ruby/issues/30484)) 
+* add Query explanation features for Ruby Firestore ([#29469](https://github.com/googleapis/google-cloud-ruby/issues/29469)) 
+* update routing headers to new format ([#30481](https://github.com/googleapis/google-cloud-ruby/issues/30481)) 
+
 ### 3.0.0 (2025-03-10)
 
 ### ⚠ BREAKING CHANGES

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

@@ -14,6 +14,7 @@
 
 require "google/cloud/firestore/v1"
 require "google/cloud/firestore/aggregate_query_snapshot"
+require "google/cloud/firestore/aggregate_query_explain_result"
 
 module Google
   module Cloud
@@ -252,6 +253,60 @@ module Google
           end
         end
 
+        ##
+        # Retrieves the query explanation for the aggregate query.
+        # By default, the query is only planned, not executed, returning only metrics from the
+        # planning stages. If `analyze` is set to `true` the query will be planned and executed,
+        # returning the `AggregateQuerySnapshot` alongside both planning and execution stage metrics.
+        #
+        # Unlike the enumerator returned from `AggregateQuery#get`, the `AggregateQueryExplainResult`
+        # caches its snapshot and metrics after the first access.
+        #
+        # @param [Boolean] analyze
+        #   Whether to execute the query and return the execution stage metrics
+        #     in addition to planning metrics.
+        #   If set to `false` the query will be planned only and will return planning
+        #      stage metrics without results.
+        #   If set to `true` the query will be executed, and will return the query results,
+        #     planning stage metrics, and execution stage metrics.
+        #   Defaults to `false`.
+        #
+        # @return [AggregateQueryExplainResult]
+        #
+        # @example Getting only the planning stage metrics for the aggregate query
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #   query = firestore.col(:cities).aggregate_query.add_count
+        #
+        #   explain_result = query.explain
+        #   metrics = explain_result.explain_metrics
+        #   puts "Plan summary: #{metrics.plan_summary}" if metrics&.plan_summary
+        #
+        # @example Getting planning and execution stage metrics, as well as aggregate query results
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #   query = firestore.col(:cities).aggregate_query.add_count
+        #
+        #   explain_result = query.explain analyze: true
+        #   metrics = explain_result.explain_metrics
+        #   puts "Plan summary: #{metrics.plan_summary}" if metrics&.plan_summary
+        #   puts "Results returned: #{metrics.execution_stats.results_returned}" if metrics&.execution_stats
+        #   snapshot = explain_result.snapshot
+        #   puts "Count: #{snapshot.get}" if snapshot
+        #
+        def explain analyze: false
+          ensure_service!
+          validate_analyze_option! analyze
+
+          explain_options = ::Google::Cloud::Firestore::V1::ExplainOptions.new analyze: analyze
+
+          responses_enum = service.run_aggregate_query @parent_path, @grpc, explain_options: explain_options
+
+          AggregateQueryExplainResult.new responses_enum
+        end
+
         ##
         # @private
         def to_grpc
@@ -279,6 +334,13 @@ module Google
           ensure_client!
           client.service
         end
+
+        # @private
+        # Validates the analyze option.
+        def validate_analyze_option! analyze_value
+          return if [true, false].include? analyze_value
+          raise ArgumentError, "analyze must be a boolean"
+        end
       end
     end
   end

data/lib/google/cloud/firestore/aggregate_query_explain_result.rb

@@ -0,0 +1,152 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "google/cloud/firestore/aggregate_query_snapshot"
+require "google/cloud/firestore/convert"
+require "google/cloud/firestore/v1" # For ExplainMetrics and AggregationResult types
+
+module Google
+  module Cloud
+    module Firestore
+      ##
+      # # AggregateQueryExplainResult
+      #
+      # Represents the result of a Firestore aggregate query explanation.
+      # This class provides access to the
+      # {Google::Cloud::Firestore::V1::ExplainMetrics}, which contain details
+      # about the query plan and execution statistics. If the explanation was
+      # run with `analyze: true`, it also provides access to the
+      # {AggregateQuerySnapshot}.
+      #
+      # The metrics and snapshot (if applicable) are fetched and cached upon
+      # the first call to either {#explain_metrics} or {#snapshot}.
+      #
+      # @see AggregateQuery#explain
+      #
+      # @example Getting planning and execution metrics with the snapshot
+      #   require "google/cloud/firestore"
+      #
+      #   firestore = Google::Cloud::Firestore.new
+      #   aggregate_query = firestore.col(:cities).aggregate_query.add_count
+      #
+      #   explain_result = aggregate_query.explain analyze: true
+      #
+      #   metrics = explain_result.explain_metrics
+      #   if metrics
+      #     puts "Plan summary: #{metrics.plan_summary&.to_json}"
+      #     puts "Execution stats: #{metrics.execution_stats&.to_json}"
+      #   end
+      #
+      #   snapshot = explain_result.snapshot
+      #   puts "Count: #{snapshot.get}" if snapshot
+      #
+      # @example Getting only planning metrics
+      #   require "google/cloud/firestore"
+      #
+      #   firestore = Google::Cloud::Firestore.new
+      #   aggregate_query = firestore.col(:cities).aggregate_query.add_count
+      #
+      #   explain_result = aggregate_query.explain analyze: false # Default
+      #
+      #   metrics = explain_result.explain_metrics
+      #   puts "Plan summary: #{metrics.plan_summary&.to_json}" if metrics
+      #
+      #   # Snapshot will be nil because analyze was false
+      #   puts "Snapshot is nil: #{explain_result.snapshot.nil?}"
+      #
+      class AggregateQueryExplainResult
+        # Indicates whether the metrics and snapshot (if applicable) have been
+        # fetched from the server response and cached.
+        # This becomes `true` after the first call to {#explain_metrics} or
+        # {#snapshot}.
+        #
+        # @return [Boolean] `true` if data has been fetched, `false` otherwise.
+        attr_reader :metrics_fetched
+        alias metrics_fetched? metrics_fetched
+
+        ##
+        # @private Creates a new AggregateQueryExplainResult.
+        #
+        # @param responses_enum [Enumerable<Google::Cloud::Firestore::V1::RunAggregationQueryResponse>]
+        #   The enum of response objects from the gRPC call.
+        #
+        def initialize responses_enum
+          @responses_enum = responses_enum
+
+          @metrics_fetched = false
+          @explain_metrics = nil
+          @snapshot = nil
+        end
+
+        # The metrics from planning and potentially execution stages of the
+        # aggregate query.
+        #
+        # Calling this method for the first time will process the server
+        # responses to extract and cache the metrics (and snapshot if
+        # `analyze: true` was used). Subsequent calls return the cached metrics.
+        #
+        # @return [Google::Cloud::Firestore::V1::ExplainMetrics, nil]
+        #   The query explanation metrics, or `nil` if no metrics were returned
+        #   by the server.
+        #
+        def explain_metrics
+          ensure_fetched!
+          @explain_metrics
+        end
+
+        # The {AggregateQuerySnapshot} containing the aggregation results.
+        #
+        # This is only available if the explanation was run with `analyze: true`.
+        # If `analyze: false` was used, or if the query yielded no results
+        # even with `analyze: true`, this method returns `nil`.
+        #
+        # Calling this method for the first time will process the server
+        # responses to extract and cache the snapshot (and metrics).
+        # Subsequent calls return the cached snapshot.
+        #
+        # @return [AggregateQuerySnapshot, nil]
+        #   The aggregate query snapshot if `analyze: true` was used and results
+        #   are available, otherwise `nil`.
+        #
+        def snapshot
+          ensure_fetched!
+          @snapshot
+        end
+
+        private
+
+        # Processes the responses from the server to populate metrics and,
+        # if applicable, the snapshot. This method is called internally by
+        # {#explain_metrics} and {#snapshot} and ensures that processing
+        # happens only once.
+        # @private
+        def ensure_fetched!
+          return if @metrics_fetched
+
+          @responses_enum.each do |response|
+            if @explain_metrics.nil? && response.explain_metrics
+              @explain_metrics = response.explain_metrics
+            end
+
+            if @snapshot.nil? && response.result
+              @snapshot = AggregateQuerySnapshot.from_run_aggregate_query_response response
+            end
+          end
+
+          @metrics_fetched = true
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/firestore/query.rb

@@ -20,6 +20,7 @@ require "google/cloud/firestore/convert"
 require "google/cloud/firestore/aggregate_query"
 require "google/cloud/firestore/filter"
 require "json"
+require "google/cloud/firestore/query_explain_result"
 
 module Google
   module Cloud
@@ -79,6 +80,12 @@ module Google
 
         ##
         # @private Creates a new Query.
+        #
+        # @param [Google::Cloud::Firestore::V1::StructuredQuery] query The structured query object.
+        # @param [String] parent_path The parent path for the query.
+        # @param [Google::Cloud::Firestore::Client] client The firestore client object.
+        # @param [Symbol] limit_type (Optional) The type of limit query (:first or :last).
+        #   Defaults to `nil` if not provided.
         def initialize query, parent_path, client, limit_type: nil
           query ||= StructuredQuery.new
           @query = query
@@ -135,7 +142,7 @@ module Google
             new_query.select.fields << field_ref
           end
 
-          Query.start new_query, parent_path, client, limit_type: limit_type
+          start_new_query new_query
         end
 
         ##
@@ -171,7 +178,7 @@ module Google
 
           new_query.from.last.all_descendants = true
 
-          Query.start new_query, parent_path, client, limit_type: limit_type
+          start_new_query new_query
         end
 
         ##
@@ -207,7 +214,7 @@ module Google
 
           new_query.from.last.all_descendants = false
 
-          Query.start new_query, parent_path, client, limit_type: limit_type
+          start_new_query new_query
         end
 
         ##
@@ -305,7 +312,7 @@ module Google
             add_filters_to_query new_query, new_filter.filter
           end
 
-          Query.start new_query, parent_path, client, limit_type: limit_type
+          start_new_query new_query
         end
 
         ##
@@ -373,7 +380,7 @@ module Google
             direction: order_direction(direction)
           )
 
-          Query.start new_query, parent_path, client, limit_type: limit_type
+          start_new_query new_query
         end
         alias order_by order
 
@@ -406,7 +413,7 @@ module Google
 
           new_query.offset = num
 
-          Query.start new_query, parent_path, client, limit_type: limit_type
+          start_new_query new_query
         end
 
         ##
@@ -443,7 +450,7 @@ module Google
 
           new_query.limit = Google::Protobuf::Int32Value.new value: num
 
-          Query.start new_query, parent_path, client, limit_type: :first
+          start_new_query new_query, limit_type_override: :first
         end
 
         ##
@@ -503,7 +510,7 @@ module Google
 
           new_query.limit = Google::Protobuf::Int32Value.new value: num
 
-          Query.start new_query, parent_path, client, limit_type: :last
+          start_new_query new_query, limit_type_override: :last
         end
 
         ##
@@ -611,7 +618,7 @@ module Google
           cursor.before = true
           new_query.start_at = cursor
 
-          Query.start new_query, parent_path, client, limit_type: limit_type
+          start_new_query new_query
         end
 
         ##
@@ -720,7 +727,7 @@ module Google
           cursor.before = false
           new_query.start_at = cursor
 
-          Query.start new_query, parent_path, client, limit_type: limit_type
+          start_new_query new_query
         end
 
         ##
@@ -829,7 +836,7 @@ module Google
           cursor.before = true
           new_query.end_at = cursor
 
-          Query.start new_query, parent_path, client, limit_type: limit_type
+          start_new_query new_query
         end
 
         ##
@@ -938,7 +945,7 @@ module Google
           cursor.before = false
           new_query.end_at = cursor
 
-          Query.start new_query, parent_path, client, limit_type: limit_type
+          start_new_query new_query
         end
 
         ##
@@ -1001,6 +1008,83 @@ module Google
         end
         alias run get
 
+        ##
+        # Retrieves the query explanation for the query.
+        # By default the query is only planned, not executed. returning only metrics from the
+        # planning stages. If `analyze` is set to `true` the query will be planned and executed,
+        # returning the full query results alongside both planning and execution stage metrics.
+        #
+        # Unlike the Enumerator object that is returned from the `Query#get`,
+        # iterating over QueryExplainResult multiple times will not result in
+        # multiple requests to the server. The first set of results will be saved
+        # and re-used instead.
+        # This is to avoid the situations where the metrics change unpredictably when results are looked at.
+        #
+        # @param [Time] read_time Reads documents as they were at the given time.
+        #   This may not be older than 270 seconds. Optional
+        #
+        # @param [Boolean] analyze
+        #   Whether to execute the query and return the execution stage metrics
+        #     in addition to planning metrics.
+        #   If set to `false` the query will be planned only and will return planning
+        #      stage metrics without results.
+        #   If set to `true` the query will be executed, and will return the query results,
+        #     planning stage metrics, and execution stage metrics.
+        #   Defaults to `false`.
+        #
+        # @example Iterating over results multiple times
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #   query = firestore.col(:cities).where(:population, :>, 100000)
+        #   explanation_result = query.explain analyze: true
+        #   results = explanation_result.to_a
+        #   results_2 = explanation_result.to_a # same results, no re-query
+        #
+        # @return [QueryExplainResult]
+        #
+        # @example Getting only the planning stage metrics for the query
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #   query = firestore.col(:cities).where(:population, :>, 100000)
+        #
+        #   # Get the execution plan without running the query
+        #   explain_result = query.explain
+        #   metrics = explain_result.explain_metrics
+        #   puts "Plan summary: #{metrics.plan_summary}" if metrics&.plan_summary
+        #
+        # @example Getting planning and execution stage metrics, as well as query results
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #   query = firestore.col(:cities).where(:population, :>, 100000)
+        #
+        #   # Run the query and return metrics from the planning and execution stages
+        #   explain_result = query.explain analyze: true
+        #   metrics = explain_result.explain_metrics
+        #   puts "Plan summary: #{metrics.plan_summary}" if metrics&.plan_summary
+        #   puts "Results returned: #{metrics.execution_stats.results_returned}" if metrics&.execution_stats
+        #   results = explain_result.to_a
+        #
+        def explain read_time: false, analyze: false
+          ensure_service!
+
+          # Validate analyze parameter
+          unless [true, false].include? analyze
+            raise ArgumentError, "analyze must be a boolean"
+          end
+
+          explain_options = ::Google::Cloud::Firestore::V1::ExplainOptions.new
+          explain_options.analyze = analyze
+
+          results = service.run_query parent_path, @query, read_time: read_time, explain_options: explain_options
+
+          # Reverse the results for Query#limit_to_last queries since that method reversed the order_by directions.
+          results = results.to_a.reverse if limit_type == :last
+          QueryExplainResult.new results, client
+        end
+
         ##
         # Creates an AggregateQuery object for the query.
         #
@@ -1117,12 +1201,41 @@ module Google
 
         ##
         # @private Start a new Query.
+        #
+        # This method creates and returns a new `Query` instance, initializing it with the provided parameters.
+        #
+        # @param [Google::Cloud::Firestore::V1::StructuredQuery] query
+        #   The structured query object representing the query to be executed.
+        # @param [String] parent_path
+        #   The parent path of the collection or document the query is operating on.
+        # @param [Google::Cloud::Firestore::Client] client
+        #   The Firestore client instance.
+        # @param [Symbol, nil] limit_type
+        #   (Optional) The type of limit to apply to the query results, either `:first` or `:last`.
+        #   Defaults to `nil` if no limit is applied.
+        # @return [Google::Cloud::Firestore::Query]
+        #   A new `Query` instance initialized with the given parameters.
         def self.start query, parent_path, client, limit_type: nil
           new query, parent_path, client, limit_type: limit_type
         end
 
         protected
 
+        ##
+        # @private Helper for starting a new query copying existing parameters.
+        #
+        # @param [Google::Cloud::Firestore::V1::StructuredQuery] new_query
+        #    The new structured query object.
+        # @param [Symbol] limit_type_override The limit type override for the new query
+        #
+        # @return [Query] A new query
+        def start_new_query new_query, limit_type_override: nil
+          Query.start(new_query,
+                      parent_path,
+                      client,
+                      limit_type: limit_type_override || limit_type)
+        end
+
         ##
         # @private
         StructuredQuery = Google::Cloud::Firestore::V1::StructuredQuery

data/lib/google/cloud/firestore/query_explain_result.rb

@@ -0,0 +1,130 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+module Google
+  module Cloud
+    module Firestore
+      ##
+      # # QueryExplainResult
+      #
+      # Represents the result of a Firestore query explanation. This class
+      # provides an enumerable interface to iterate over the {DocumentSnapshot}
+      # results (if the explanation was run with `analyze: true`) and allows
+      # access to the {Google::Cloud::Firestore::V1::ExplainMetrics} which
+      # contain details about the query plan and execution statistics.
+      #
+      # Unlike the Enumerator object that is returned from the `Query#get`,
+      # iterating over QueryExplainResult multiple times will not result in
+      # multiple requests to the server. The first set of results will be saved
+      # and re-used instead.
+      #
+      # This is to avoid the situations where the metrics do not correspond to the results
+      # if results are partially re-enumerated
+      #
+      # @see Query#explain
+      #
+      # @example Iterating over results and accessing metrics
+      #   require "google/cloud/firestore"
+      #
+      #   firestore = Google::Cloud::Firestore.new
+      #   query = firestore.col(:cities).where(:population, :>, 100000)
+      #
+      #   # Run the query and return metrics from the planning and execution stages
+      #   explanation_result = query.explain analyze: true
+      #
+      #   explanation_result.each do |city_snapshot|
+      #     puts "City: #{city_snapshot.document_id}, Population: #{city_snapshot[:population]}"
+      #   end
+      #
+      #   metrics = explanation_result.explain_metrics
+      #   puts "Results returned: #{metrics.execution_stats.results_returned}" if metrics&.execution_stats
+      #
+      # @example Fetching metrics directly (which also iterates internally if needed)
+      #   require "google/cloud/firestore"
+      #
+      #   firestore = Google::Cloud::Firestore.new
+      #   query = firestore.col(:cities).where(:population, :>, 100000)
+      #
+      #   # Get the execution plan without running the query (or with analyze: true)
+      #   explanation_result = query.explain analyze: false # or true
+      #
+      #   metrics = explanation_result.explain_metrics
+      #   puts "Plan summary: #{metrics.plan_summary}" if metrics&.plan_summary
+      #   puts "Results returned: #{metrics.execution_stats.results_returned}" if metrics&.execution_stats
+      #
+      # @example Iterating over results multiple times
+      #   require "google/cloud/firestore"
+      #
+      #   firestore = Google::Cloud::Firestore.new
+      #   query = firestore.col(:cities).where(:population, :>, 100000)
+      #   explanation_result = query.explain analyze: true
+      #   results = explanation_result.to_a
+      #   results_2 = explanation_result.to_a # same results, no re-query
+      #
+      ##
+      class QueryExplainResult
+        include Enumerable
+
+        # Indicates whether the {#explain_metrics} have been populated.
+        # This becomes `true` after iterating through the results (e.g., via {#each})
+        # or by explicitly calling {#explain_metrics}.
+        #
+        # @return [Boolean] `true` if metrics are populated, `false` otherwise.
+        attr_reader :metrics_fetched
+        alias metrics_fetched? metrics_fetched
+
+        # @private Creates a new QueryRunResult.
+        def initialize results_enum, client
+          @results_enum = results_enum
+          @client = client
+          @metrics_fetched = false
+        end
+
+        # The metrics from planning and execution stages of the query.
+        # Calling this the first time will enumerate and cache all results as well as cache the metrics.
+        #
+        # Subsequent calls will return the cached value.
+        #
+        # @return [Google::Cloud::Firestore::V1::ExplainMetrics] The query explanation metrics.
+        def explain_metrics
+          # rubocop:disable Lint/EmptyBlock
+          each {} unless metrics_fetched?
+          # rubocop:enable Lint/EmptyBlock
+          @explain_metrics
+        end
+
+        # Iterates over the document snapshots returned by the query explanation
+        # if `analyze: true` was used. If `analyze: false` was used, this
+        # method will still iterate but will not yield any documents, though it
+        # will populate the query explanation metrics.
+        #
+        # @yieldparam [DocumentSnapshot] snapshot A document snapshot from the query results.
+        # @return [Enumerator] If no block is given.
+        def each
+          return enum_for :each unless block_given?
+          @results ||= @results_enum.to_a
+
+          @results.each do |result|
+            @explain_metrics ||= result.explain_metrics if result.explain_metrics
+            @metrics_fetched = !@explain_metrics.nil?
+            next if result.document.nil?
+
+            yield DocumentSnapshot.from_query_result(result, @client)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "cgi/escape"
 
 require "google/cloud/env"
 require "google/cloud/errors"
@@ -52,7 +53,8 @@ module Google
               config.endpoint = host if host
               config.lib_name = "gccl"
               config.lib_version = Google::Cloud::Firestore::VERSION
-              config.metadata = { "google-cloud-resource-prefix": "projects/#{@project}/databases/#{@database}" }
+              routing_val = CGI.escapeURIComponent "projects/#{@project}/databases/#{@database}"
+              config.metadata = { "x-goog-request-params": "database=#{routing_val}" }
             end
           end
         end
@@ -120,26 +122,32 @@ module Google
           paged_enum.response
         end
 
-        def run_query path, query_grpc, transaction: nil, read_time: nil
+        def run_query path, query_grpc, transaction: nil, read_time: nil, explain_options: nil
           run_query_req = {
             parent:           path,
             structured_query: query_grpc
           }
+
           if transaction.is_a? String
             run_query_req[:transaction] = transaction
           elsif transaction
             run_query_req[:new_transaction] = transaction
           end
+
           if read_time
             run_query_req[:read_time] = read_time_to_timestamp(read_time)
           end
 
+          if explain_options
+            run_query_req[:explain_options] = explain_options
+          end
+
           firestore.run_query run_query_req, call_options(parent: database_path)
         end
 
         ##
         # Returns Google::Cloud::Firestore::V1::RunAggregationQueryResponse
-        def run_aggregate_query parent, structured_aggregation_query, transaction: nil
+        def run_aggregate_query parent, structured_aggregation_query, transaction: nil, explain_options: nil
           request = Google::Cloud::Firestore::V1::RunAggregationQueryRequest.new(
             parent: parent,
             structured_aggregation_query: structured_aggregation_query
@@ -149,6 +157,9 @@ module Google
           elsif transaction
             request.new_transaction = transaction
           end
+          if explain_options
+            request.explain_options = explain_options
+          end
           firestore.run_aggregation_query request
         end
 
@@ -227,7 +238,8 @@ module Google
 
         def default_headers parent = nil
           parent ||= database_path
-          { "google-cloud-resource-prefix" => parent }
+          routing_val = CGI.escapeURIComponent parent
+          { "x-goog-request-params" => "database=#{routing_val}" }
         end
 
         def call_options parent: nil, token: nil

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Firestore
-      VERSION = "3.0.0".freeze
+      VERSION = "3.1.1".freeze
     end
   end
 end

data/lib/google/cloud/firestore.rb

@@ -43,9 +43,27 @@ module Google
       #
       # @param [String] project_id Identifier for a Firestore 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 {Firestore::Credentials})
+      # @param [Google::Auth::Credentials] credentials A Google::Auth::Credentials
+      #   object. (See {Firestore::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")
+      #     )
+      #
+      #     firestore = Google::Cloud::Firestore.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-firestore.rb

@@ -91,9 +91,25 @@ module Google
     #
     # @param [String] project_id Identifier for a Firestore 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 {Firestore::Credentials})
+    # @param [Google::Auth::Credentials] credentials A Google::Auth::Credentials
+    #   object. (See {Firestore::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")
+    #     )
+    #
+    #     firestore = Google::Cloud::Firestore.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,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-firestore
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.1
 platform: ruby
 authors:
 - Google Inc
 bindir: bin
 cert_chain: []
-date: 2025-03-10 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -99,6 +99,7 @@ files:
 - lib/google-cloud-firestore.rb
 - lib/google/cloud/firestore.rb
 - lib/google/cloud/firestore/aggregate_query.rb
+- lib/google/cloud/firestore/aggregate_query_explain_result.rb
 - lib/google/cloud/firestore/aggregate_query_snapshot.rb
 - lib/google/cloud/firestore/batch.rb
 - lib/google/cloud/firestore/bulk_commit_batch.rb
@@ -125,6 +126,7 @@ files:
 - lib/google/cloud/firestore/generate.rb
 - lib/google/cloud/firestore/promise/future.rb
 - lib/google/cloud/firestore/query.rb
+- lib/google/cloud/firestore/query_explain_result.rb
 - lib/google/cloud/firestore/query_listener.rb
 - lib/google/cloud/firestore/query_partition.rb
 - lib/google/cloud/firestore/query_snapshot.rb
@@ -155,7 +157,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 Firestore API
 test_files: []