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

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

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.

Inherits

  • Object

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

Methods

#explain_metrics

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

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.

#metrics_fetched

def metrics_fetched() -> Boolean
Aliases

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.

#metrics_fetched?

def metrics_fetched?() -> Boolean
Alias Of: #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.

#snapshot

def snapshot() -> AggregateQuerySnapshot, nil

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.

Returns
  • (AggregateQuerySnapshot, nil) — The aggregate query snapshot if analyze: true was used and results are available, otherwise nil.