From dfab728a5fe523c43f24dc7f00729bad7bc84b0b Mon Sep 17 00:00:00 2001 From: Yuwei Zhao Date: Mon, 3 Aug 2026 00:33:23 +0800 Subject: [PATCH] docs: add HashJoinExec metrics to user guide --- datafusion/physical-plan/src/joins/utils.rs | 3 ++- docs/source/user-guide/metrics.md | 19 +++++++++++++++++++ 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/datafusion/physical-plan/src/joins/utils.rs b/datafusion/physical-plan/src/joins/utils.rs index 654d873ae1b0e..a495dd446b1af 100644 --- a/datafusion/physical-plan/src/joins/utils.rs +++ b/datafusion/physical-plan/src/joins/utils.rs @@ -1758,6 +1758,7 @@ fn append_probe_indices_in_order( /// Metrics for build & probe joins #[derive(Clone, Debug)] pub(crate) struct BuildProbeJoinMetrics { + // Keep these metric descriptions in sync with docs/source/user-guide/metrics.md. pub(crate) baseline: BaselineMetrics, /// Total time for collecting build-side of join pub(crate) build_time: metrics::Time, @@ -1773,7 +1774,7 @@ pub(crate) struct BuildProbeJoinMetrics { pub(crate) input_batches: metrics::Count, /// Number of rows consumed by probe-side this operator pub(crate) input_rows: metrics::Count, - /// Fraction of probe rows that found more than one match + /// Fraction of probe rows that found at least one match pub(crate) probe_hit_rate: metrics::RatioMetrics, /// Average number of build matches per matched probe row pub(crate) avg_fanout: metrics::RatioMetrics, diff --git a/docs/source/user-guide/metrics.md b/docs/source/user-guide/metrics.md index 7e0363f4ceb9b..64bf4f8b1ba8a 100644 --- a/docs/source/user-guide/metrics.md +++ b/docs/source/user-guide/metrics.md @@ -42,6 +42,25 @@ DataFusion operators expose runtime metrics so you can understand where time is | ----------- | ----------------------------------------------------------------- | | selectivity | Selectivity of the filter, calculated as output_rows / input_rows | +### HashJoinExec + +`HashJoinExec` also exposes the common `BaselineMetrics`. Its +`elapsed_compute` metric is the sum of the build-side collection time and the +probe-side join time. + +| Metric | Description | +| ----------------------- | -------------------------------------------------------------------------------------------- | +| build_time | Total time spent collecting and building the build side of the join. | +| build_input_batches | Number of input batches consumed from the build side. | +| build_input_rows | Number of input rows consumed from the build side. | +| build_mem_used | Peak memory used by the build side, in bytes. | +| join_time | Total time spent joining probe-side batches against the build side. | +| input_batches | Number of input batches consumed from the probe side. | +| input_rows | Number of input rows consumed from the probe side. | +| probe_hit_rate | Fraction of probe-side rows that matched at least one build-side row. | +| avg_fanout | Average number of build-side matches per matched probe-side row. | +| array_map_created_count | Number of times `HashJoinExec` created an `ArrayMap` for perfect hash join lookup execution. | + ## TODO Add metrics for the remaining operators