Class: Google::Cloud::Firestore::QueryExplainResult

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/google/cloud/firestore/query_explain_result.rb

Overview

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

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

See Also:

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#metrics_fetched ⇒ Boolean (readonly) Also known as: 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.



85
86
87
 
# File 'lib/google/cloud/firestore/query_explain_result.rb', line 85

def metrics_fetched
  @metrics_fetched
end

Instance Method Details

#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 Parameters:



115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/google/cloud/firestore/query_explain_result.rb', line 115

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

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



101
102
103
104
105
106
 
# File 'lib/google/cloud/firestore/query_explain_result.rb', line 101

def explain_metrics
  # rubocop:disable Lint/EmptyBlock
  each {} unless metrics_fetched?
  # rubocop:enable Lint/EmptyBlock
  @explain_metrics
end