Cloud Firestore API - Class Google::Cloud::Firestore::QueryExplainResult (v3.1.0)

Reference documentation and code samples for the Cloud Firestore API class Google::Cloud::Firestore::QueryExplainResult.

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 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

Inherits

  • Object

Includes

  • Enumerable

Examples

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

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

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

Methods

#each

def each() { |snapshot| ... } -> Enumerator

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.

Yield Parameter
Returns
  • (Enumerator) — If no block is given.

#explain_metrics

def explain_metrics() -> Google::Cloud::Firestore::V1::ExplainMetrics

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.

Returns
  • (Google::Cloud::Firestore::V1::ExplainMetrics) — The query explanation metrics.

#metrics_fetched

def metrics_fetched() -> Boolean
Aliases

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.

Returns
  • (Boolean) — true if metrics are populated, false otherwise.

#metrics_fetched?

def metrics_fetched?() -> Boolean
Alias Of: #metrics_fetched

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.

Returns
  • (Boolean) — true if metrics are populated, false otherwise.