Query Explain methods allows you receive detailed performance statistics on backend query execution. It functions like theEXPLAIN[ANALYZE] operation in relational database systems. Theexplainmethod, available on bothQueryandAggregateQueryobjects, is the primary way to access this information.
Query#explain
Theexplainmethod on aQueryinstance allows you to retrieve planning and execution metrics for your standard document queries.
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 asread_timeparameter on regularQuery.getReads documents as they were at the given time. This may not be older than 270 seconds.
TheQueryExplainResultobject is enumerable and provides access to:
explain_metrics: AGoogle::Cloud::Firestore::V1::ExplainMetricsobject containing plan summaries and, ifanalyze: true, execution statistics.
Document snapshots: Ifanalyze: true, you can iterate over theQueryExplainResultto get theDocumentSnapshotobjects returned by the query.
Example:
require"google/cloud/firestore"firestore=Google::Cloud::Firestore.newquery=firestore.col(:cities).where(:population,:>,100000)# Get only planning metricsplan_only_result=query.explainputs"Plan Summary:#{plan_only_result.explain_metrics.plan_summary}"# Get planning, execution metrics, and resultsfull_explain_result=query.explainanalyze:trueputs"Execution Stats:#{full_explain_result.explain_metrics.execution_stats}"full_explain_result.eachdo|city_doc|puts"City:#{city_doc.document_id}"end
AggregateQuery#explain
Similarly, theexplainmethod on anAggregateQueryinstance 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 theAggregateQuerySnapshot.
snapshot: AnAggregateQuerySnapshotcontaining the aggregation result (e.g., the count value), available ifanalyze: trueand the query yielded a result.
Example:
require"google/cloud/firestore"firestore=Google::Cloud::Firestore.newaggregate_query=firestore.col(:cities).where(:population,:>,100000).aggregate_query.add_count# Get only planning metricsplan_only_result=aggregate_query.explainputs"Plan Summary:#{plan_only_result.explain_metrics.plan_summary}"# Get planning, execution metrics, and resultsfull_explain_result=aggregate_query.explainanalyze:trueputs"Execution Stats:#{full_explain_result.explain_metrics.execution_stats}"puts"Total cities:#{full_explain_result.snapshot.get}"
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[],[],null,["Version latestkeyboard_arrow_down\n\n- [3.1.0 (latest)](/ruby/docs/reference/google-cloud-firestore/latest/QUERY-PERFORMANCE)\n- [3.0.0](/ruby/docs/reference/google-cloud-firestore/3.0.0/QUERY-PERFORMANCE)\n- [2.16.1](/ruby/docs/reference/google-cloud-firestore/2.16.1/QUERY-PERFORMANCE)\n- [2.15.1](/ruby/docs/reference/google-cloud-firestore/2.15.1/QUERY-PERFORMANCE)\n- [2.14.0](/ruby/docs/reference/google-cloud-firestore/2.14.0/QUERY-PERFORMANCE)\n- [2.13.1](/ruby/docs/reference/google-cloud-firestore/2.13.1/QUERY-PERFORMANCE)\n- [2.12.0](/ruby/docs/reference/google-cloud-firestore/2.12.0/QUERY-PERFORMANCE)\n- [2.11.0](/ruby/docs/reference/google-cloud-firestore/2.11.0/QUERY-PERFORMANCE)\n- [2.10.1](/ruby/docs/reference/google-cloud-firestore/2.10.1/QUERY-PERFORMANCE)\n- [2.9.1](/ruby/docs/reference/google-cloud-firestore/2.9.1/QUERY-PERFORMANCE)\n- [2.8.0](/ruby/docs/reference/google-cloud-firestore/2.8.0/QUERY-PERFORMANCE)\n- [2.7.2](/ruby/docs/reference/google-cloud-firestore/2.7.2/QUERY-PERFORMANCE)\n- [2.6.6](/ruby/docs/reference/google-cloud-firestore/2.6.6/QUERY-PERFORMANCE) \n\nUnderstanding Query Performance\n===============================\n\nQuery 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.\n\nQuery#explain\n-------------\n\nThe `explain` method on a `Query` instance allows you to retrieve planning and execution metrics for your standard document queries.\n\n**Method Signature:** `explain(analyze: false, read_time: nil)`\n\n- `analyze` (Boolean, optional):\n - `false` (default): Returns only planning-stage metrics. The query is not executed, and no documents are returned.\n - `true`: Executes the query and returns both planning and execution-stage metrics, along with the actual query results (document snapshots).\n- `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.\n\n**Returns:** `Google::Cloud::Firestore::QueryExplainResult`\n\nThe `QueryExplainResult` object is enumerable and provides access to:\n\n- `explain_metrics`: A `Google::Cloud::Firestore::V1::ExplainMetrics` object containing plan summaries and, if `analyze: true`, execution statistics.\n- Document snapshots: If `analyze: true`, you can iterate over the `QueryExplainResult` to get the `DocumentSnapshot` objects returned by the query.\n\n**Example:** \n\n```ruby\nrequire \"google/cloud/firestore\"\n\nfirestore = Google::Cloud::Firestore.new\nquery = firestore.col(:cities).where(:population, :\u003e, 100000)\n\n# Get only planning metrics\nplan_only_result = query.explain\nputs \"Plan Summary: #{plan_only_result.explain_metrics.plan_summary}\"\n\n# Get planning, execution metrics, and results\nfull_explain_result = query.explain analyze: true\nputs \"Execution Stats: #{full_explain_result.explain_metrics.execution_stats}\"\nfull_explain_result.each do |city_doc|\n puts \"City: #{city_doc.document_id}\"\nend\n```\n\nAggregateQuery#explain\n----------------------\n\nSimilarly, the `explain` method on an `AggregateQuery` instance provides performance insights for your aggregation queries (e.g., `count`, `sum`, `avg`).\n\n**Method Signature:** `explain(analyze: false)`\n\n- `analyze` (Boolean, optional):\n - `false` (default): Returns only planning-stage metrics. The aggregation query is not executed.\n - `true`: Executes the aggregation query and returns both planning and execution-stage metrics, along with the `AggregateQuerySnapshot`.\n\n**Returns:** `Google::Cloud::Firestore::AggregateQueryExplainResult`\n\nThe `AggregateQueryExplainResult` object provides access to:\n\n- `explain_metrics`: A `Google::Cloud::Firestore::V1::ExplainMetrics` object.\n- `snapshot`: An `AggregateQuerySnapshot` containing the aggregation result (e.g., the count value), available if `analyze: true` and the query yielded a result.\n\n**Example:** \n\n```ruby\nrequire \"google/cloud/firestore\"\n\nfirestore = Google::Cloud::Firestore.new\naggregate_query = firestore.col(:cities).where(:population, :\u003e, 100000).aggregate_query.add_count\n\n# Get only planning metrics\nplan_only_result = aggregate_query.explain\nputs \"Plan Summary: #{plan_only_result.explain_metrics.plan_summary}\"\n\n# Get planning, execution metrics, and results\nfull_explain_result = aggregate_query.explain analyze: true\nputs \"Execution Stats: #{full_explain_result.explain_metrics.execution_stats}\"\nputs \"Total cities: #{full_explain_result.snapshot.get}\"\n```"]]
