You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@datafusion.apache.org by gi...@apache.org on 2026/08/17 03:54:29 UTC
(datafusion) branch gh-readonly-queue/main/pr-24055-83be77c523fa114e8b9f3756721b25177894d209 created (now 9a83691aad)
This is an automated email from the ASF dual-hosted git repository.
github-merge-queue[bot] pushed a change to branch gh-readonly-queue/main/pr-24055-83be77c523fa114e8b9f3756721b25177894d209
in repository https://gitbox.apache.org/repos/asf/datafusion.git
at 9a83691aad docs: add HashJoinExec metrics to user guide (#24055)
This branch includes the following new commits:
new 9a83691aad docs: add HashJoinExec metrics to user guide (#24055)
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datafusion.apache.org
For additional commands, e-mail: commits-help@datafusion.apache.org
(datafusion) 01/01: docs: add HashJoinExec metrics to user guide (#24055)
Posted by gi...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
github-merge-queue[bot] pushed a commit to branch gh-readonly-queue/main/pr-24055-83be77c523fa114e8b9f3756721b25177894d209
in repository https://gitbox.apache.org/repos/asf/datafusion.git
commit 9a83691aadaadbf72bf4c8b7d87bd28af9dc68dd
Author: Yuwei Zhao <zh...@163.com>
AuthorDate: Mon Aug 17 03:54:08 2026 +0000
docs: add HashJoinExec metrics to user guide (#24055)
## Which issue does this PR close?
- Closes #19044.
## Rationale for this change
`HashJoinExec` exposes several operator-specific metrics, but the
metrics user guide did not document them yet. This PR follows the
metrics documentation tracking issue by adding the `HashJoinExec`
section.
## What changes are included in this PR?
- Adds `HashJoinExec` operator-specific metrics to
`docs/source/user-guide/metrics.md`.
- Adds a note near `BuildProbeJoinMetrics` to keep metric descriptions
in sync with the user guide.
- Clarifies that `join_time` covers join processing after build-side
collection.
- Clarifies that `probe_hit_rate` and `avg_fanout` measure join-key
matches before applying any join filter.
## Are these changes tested?
This is a documentation/comment-only change with no runtime behavior
change.
Checked locally:
- `git diff --check`
- `cargo fmt --check`
- `npx prettier@2.7.1 --check docs/source/user-guide/metrics.md`
- `./dev/rust_lint.sh`
- `cd docs && uv run --package datafusion-docs ./build.sh`
- DataFusion CLI `EXPLAIN ANALYZE` queries with and without a join
filter
## Are there any user-facing changes?
Yes. The metrics user guide now documents the existing `HashJoinExec`
metrics. There are no runtime behavior or public API changes.
## AI-assisted contribution note
This change is limited to documentation and comments. I verified the
metric names and semantics against `BuildProbeJoinMetrics`, the
`HashJoinExec` execution path, and local `EXPLAIN ANALYZE` output. I do
not have unknowns or assumptions to call out.
---
datafusion/physical-plan/src/joins/utils.rs | 9 ++++++---
docs/source/user-guide/metrics.md | 19 +++++++++++++++++++
2 files changed, 25 insertions(+), 3 deletions(-)
diff --git a/datafusion/physical-plan/src/joins/utils.rs b/datafusion/physical-plan/src/joins/utils.rs
index 20467a7ec5..ecf056560e 100644
--- a/datafusion/physical-plan/src/joins/utils.rs
+++ b/datafusion/physical-plan/src/joins/utils.rs
@@ -1754,6 +1754,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,
@@ -1763,15 +1764,17 @@ pub(crate) struct BuildProbeJoinMetrics {
pub(crate) build_input_rows: metrics::Count,
/// Memory used by build-side in bytes
pub(crate) build_mem_used: metrics::Gauge,
- /// Total time for joining probe-side batches to the build-side batches
+ /// Total time for join processing after build-side collection
pub(crate) join_time: metrics::Time,
/// Number of batches consumed by probe-side of this operator
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 with at least one build-side join-key match before
+ /// applying any join filter
pub(crate) probe_hit_rate: metrics::RatioMetrics,
- /// Average number of build matches per matched probe row
+ /// Average number of build-side join-key matches per matched probe row before
+ /// applying any join filter
pub(crate) avg_fanout: metrics::RatioMetrics,
}
diff --git a/docs/source/user-guide/metrics.md b/docs/source/user-guide/metrics.md
index 7e0363f4ce..306094c438 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
+subsequent join processing 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 tracked memory used by the build side, in bytes. |
+| join_time | Total time spent processing the join after build-side collection. |
+| 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 with a build-side join-key match before applying any join filter. |
+| avg_fanout | Average number of build-side join-key matches per matched probe-side row before applying any join filter. |
+| array_map_created_count | Number of times `HashJoinExec` created an `ArrayMap` for perfect hash join lookup execution. |
+
## TODO
Add metrics for the remaining operators
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datafusion.apache.org
For additional commands, e-mail: commits-help@datafusion.apache.org