Understanding Query Performance

Query Explain methods allows you receive detailed performance statistics on backend query execution. It functions like the EXPLAIN [ANALYZE] operation in relational database systems. The explain method, available on both Query and AggregateQuery objects, is the primary way to access this information.

Query#explain

The explain method on a Query instance allows you to retrieve planning and execution metrics for your standard document queries.

Method Signature: explain(analyze: false, read_time: nil)

  • analyze (Boolean, optional):
    • false (default): Returns only planning-stage metrics. The query is not executed, and no documents are returned.
    • true: Executes the query and returns both planning and execution-stage metrics, along with the actual query results (document snapshots).
  • read_time (Time, optional): This is same as read_time parameter on regular Query.get Reads documents as they were at the given time. This may not be older than 270 seconds.

Returns: Google::Cloud::Firestore::QueryExplainResult

The QueryExplainResult object is enumerable and provides access to:

  • explain_metrics: A Google::Cloud::Firestore::V1::ExplainMetrics object containing plan summaries and, if analyze: true, execution statistics.
  • Document snapshots: If analyze: true, you can iterate over the QueryExplainResult to get the DocumentSnapshot objects returned by the query.

Example:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
query = firestore.col(:cities).where(:population, :>, 100000)

# Get only planning metrics
plan_only_result = query.explain
puts "Plan Summary: #{plan_only_result.explain_metrics.plan_summary}"

# Get planning, execution metrics, and results
full_explain_result = query.explain analyze: true
puts "Execution Stats: #{full_explain_result.explain_metrics.execution_stats}"
full_explain_result.each do |city_doc|
  puts "City: #{city_doc.document_id}"
end

AggregateQuery#explain

Similarly, the explain method on an AggregateQuery instance provides performance insights for your aggregation queries (e.g., count, sum, avg).

Method Signature: explain(analyze: false)

  • analyze (Boolean, optional):
    • false (default): Returns only planning-stage metrics. The aggregation query is not executed.
    • true: Executes the aggregation query and returns both planning and execution-stage metrics, along with the AggregateQuerySnapshot.

Returns: Google::Cloud::Firestore::AggregateQueryExplainResult

The AggregateQueryExplainResult object provides access to:

  • explain_metrics: A Google::Cloud::Firestore::V1::ExplainMetrics object.
  • snapshot: An AggregateQuerySnapshot containing the aggregation result (e.g., the count value), available if analyze: true and the query yielded a result.

Example:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
aggregate_query = firestore.col(:cities).where(:population, :>, 100000).aggregate_query.add_count

# Get only planning metrics
plan_only_result = aggregate_query.explain
puts "Plan Summary: #{plan_only_result.explain_metrics.plan_summary}"

# Get planning, execution metrics, and results
full_explain_result = aggregate_query.explain analyze: true
puts "Execution Stats: #{full_explain_result.explain_metrics.execution_stats}"
puts "Total cities: #{full_explain_result.snapshot.get}"