Refine and document AggregateExec metrics

[kosiew]

Which issue does this PR close?

• Part of Add aggregate specific metrics #23570

Rationale for this change

Aggregate-specific metrics are a user-visible observability surface in EXPLAIN ANALYZE, but their phase boundaries and relationship to individual aggregate expressions need to be clear and consistent.

In particular, users should be able to understand what each aggregate timer measures, map indexed metrics such as agg_expr_0_arguments_time back to the corresponding expression in the operator's aggr=[...] list, and understand which metrics are available on different grouped aggregation paths without reading the implementation.

This PR also tightens the timing boundaries of the grouped aggregate metrics so that the documented metrics correspond more directly to the work they describe.

What changes are included in this PR?

• Documents AggregateExec operator-level and per-aggregate metrics, including their phase boundaries, indexed naming convention, aggregate expression labels, visibility, and path-specific coverage.

• Groups aggregate timing into explicit phases for:

  • group-key preparation,
  • aggregate argument and filter evaluation,
  • accumulator update / merge operations, and
  • output emission.

• Ensures accumulator aggregation_time measures a single interval containing the relevant accumulator operations rather than accumulating overlapping/prefix timing.

• Includes group interning and ordering setup in time_calculating_group_ids.

• Includes collectively evaluated aggregate filters in aggregate_arguments_time.

• Adds topk_maintenance_time for Grouped TopK priority-map maintenance and avoids registering aggregation_time for that accumulator-free path.

• Times grouped output materialization consistently with emitting_time.

• Adds EXPLAIN ANALYZE coverage demonstrating how indexed per-aggregate metrics map to multiple aggregate expressions and how expression labels appear in verbose output.

Are these changes tested?

Yes.

The patch adds and updates tests that verify:

• EXPLAIN ANALYZE reports agg_expr_0_arguments_time, agg_expr_1_arguments_time, and agg_expr_2_arguments_time for a query containing SUM(c5), SUM(c6), and COUNT(c7).
• EXPLAIN ANALYZE VERBOSE associates those indexed metrics with the corresponding rendered aggregate expressions.
• Grouped TopK reports topk_maintenance_time and time_calculating_group_ids while not registering aggregation_time.
• Regular aggregate paths do not report topk_maintenance_time.
• Aggregate execution without grouped emission does not report emitting_time.
• GroupByMetrics::new_topk does not register aggregation_time.

Are there any user-facing changes?

Yes. Aggregate metrics shown through EXPLAIN ANALYZE are clarified and their timing boundaries are made more consistent.

The metrics documentation now describes the AggregateExec operator-level metrics and per-expression timer phases, explains how indexed metrics map to aggregate expressions, and documents path-specific differences such as Grouped TopK and non-grouped aggregation.

These are observability and documentation changes; this PR does not introduce a public API change.

LLM-generated code disclosure

This PR includes LLM-generated code and comments. All LLM-generated content has been manually reviewed.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 77.18121% with 102 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.51%. Comparing base (c56a7ab) to head (608174b).
⚠️ Report is 6 commits behind head on main.

Files with missing lines	Patch %	Lines
...c/aggregates/aggregate_hash_table/partial_table.rs	2.22%	44 Missing ⚠️
...hysical-plan/src/aggregates/grouped_hash_stream.rs	81.92%	11 Missing and 19 partials ⚠️
.../aggregates/aggregate_hash_table/common_ordered.rs	80.00%	4 Missing and 10 partials ⚠️
...plan/src/aggregates/aggregate_hash_table/common.rs	82.69%	2 Missing and 7 partials ⚠️
...hysical-plan/src/aggregates/grouped_topk_stream.rs	90.19%	0 Missing and 5 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #24757      +/-   ##
==========================================
+ Coverage   81.47%   81.51%   +0.03%     
==========================================
  Files        1122     1123       +1     
  Lines      404140   405263    +1123     
  Branches   404140   405263    +1123     
==========================================
+ Hits       329284   330340    +1056     
- Misses      55546    55584      +38     
- Partials    19310    19339      +29     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.