Class: Google::Cloud::Firestore::AggregateQueryExplainResult

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/firestore/aggregate_query_explain_result.rb

Overview

AggregateQueryExplainResult

Represents the result of a Firestore aggregate query explanation. This class provides access to the 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.

Examples:

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

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?}"

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

Returns:

  • (Boolean) —

    true if data has been fetched, false otherwise.



75
76
77
 
# File 'lib/google/cloud/firestore/aggregate_query_explain_result.rb', line 75

def metrics_fetched
  @metrics_fetched
end

Instance Method Details

#explain_metrics ⇒ Google::Cloud::Firestore::V1::ExplainMetrics?

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.

Returns:

  • (Google::Cloud::Firestore::V1::ExplainMetrics, nil) —

    The query explanation metrics, or nil if no metrics were returned by the server.



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

def explain_metrics
  ensure_fetched!
  @explain_metrics
end

#snapshot ⇒ AggregateQuerySnapshot?

The Google::Cloud::Firestore::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.

Returns:

  • (AggregateQuerySnapshot, nil) —

    The aggregate query snapshot if analyze: true was used and results are available, otherwise nil.



122
123
124
125
 
# File 'lib/google/cloud/firestore/aggregate_query_explain_result.rb', line 122

def snapshot
  ensure_fetched!
  @snapshot
end