Skip to content

Commit c9a142d

Browse files
committed
Simplify prepared hash join construction and regression coverage
1 parent 0d00612 commit c9a142d

5 files changed

Lines changed: 150 additions & 277 deletions

File tree

‎datafusion/physical-plan/src/joins/hash_join/exec.rs‎

Lines changed: 40 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1184,10 +1184,6 @@ impl HashJoinExec {
11841184
Optimizer rules that reorder join inputs must run before optimizer rules `FilterPushdown::new_post_optimization()`"
11851185
);
11861186

1187-
assert_or_internal_err!(
1188-
self.prepared_build.is_none(),
1189-
"Cannot swap a prepared hash join"
1190-
);
11911187
let left = self.left();
11921188
let right = self.right();
11931189
let new_join = self
@@ -1552,7 +1548,7 @@ impl ExecutionPlan for HashJoinExec {
15521548
Arc::clone(context.session_config().options()),
15531549
self.null_equality,
15541550
array_map_created_count,
1555-
None,
1551+
false,
15561552
))
15571553
})?,
15581554
PartitionMode::Partitioned => {
@@ -1574,7 +1570,7 @@ impl ExecutionPlan for HashJoinExec {
15741570
Arc::clone(context.session_config().options()),
15751571
self.null_equality,
15761572
array_map_created_count,
1577-
None,
1573+
false,
15781574
))
15791575
}
15801576
PartitionMode::Auto => {
@@ -2297,7 +2293,7 @@ fn should_collect_min_max_for_perfect_hash(
22972293
#[expect(clippy::too_many_arguments)]
22982294
async fn collect_left_input(
22992295
random_state: RandomState,
2300-
left_stream: SendableRecordBatchStream,
2296+
mut left_stream: SendableRecordBatchStream,
23012297
on_left: Vec<PhysicalExprRef>,
23022298
metrics: BuildProbeJoinMetrics,
23032299
reservation: MemoryReservation,
@@ -2307,47 +2303,53 @@ async fn collect_left_input(
23072303
config: Arc<ConfigOptions>,
23082304
null_equality: NullEquality,
23092305
array_map_created_count: Count,
2310-
prepared_input_bytes: Option<usize>,
2306+
prepared: bool,
23112307
) -> Result<JoinLeftData> {
23122308
let schema = left_stream.schema();
23132309

23142310
let should_collect_min_max_for_phj =
23152311
should_collect_min_max_for_perfect_hash(&on_left, &schema)?;
23162312

2317-
let initial = BuildSideState::try_new(
2313+
let mut state = BuildSideState::try_new(
23182314
metrics,
23192315
reservation,
23202316
on_left.clone(),
23212317
&schema,
23222318
should_compute_dynamic_filters || should_collect_min_max_for_phj,
23232319
)?;
23242320

2325-
let state = left_stream
2326-
.try_fold(initial, |mut state, batch| async move {
2327-
// Update accumulators if computing bounds
2328-
if let Some(ref mut accumulators) = state.bounds_accumulators {
2329-
for accumulator in accumulators {
2330-
accumulator.update_batch(&batch)?;
2331-
}
2332-
}
2333-
2334-
// Decide if we spill or not
2335-
let batch_size = state.memory_counter.count_batch(&batch);
2336-
// Reserve memory for incoming batch
2337-
if prepared_input_bytes.is_none() {
2338-
state.reservation.try_grow(batch_size)?;
2321+
let mut concat_values = if prepared {
2322+
vec![0; schema.fields().len()]
2323+
} else {
2324+
vec![]
2325+
};
2326+
while let Some(batch) = left_stream.try_next().await? {
2327+
if prepared {
2328+
prepared::check_byte_concat_sizes(&batch, &mut concat_values)?;
2329+
}
2330+
if let Some(accumulators) = &mut state.bounds_accumulators {
2331+
for accumulator in accumulators {
2332+
accumulator.update_batch(&batch)?;
23392333
}
2340-
// Update metrics
2341-
state.metrics.build_mem_used.add(batch_size);
2342-
state.metrics.build_input_batches.add(1);
2343-
state.metrics.build_input_rows.add(batch.num_rows());
2344-
// Update row count
2345-
state.num_rows += batch.num_rows();
2346-
// Push batch to output
2347-
state.batches.push(batch);
2348-
Ok(state)
2349-
})
2350-
.await?;
2334+
}
2335+
let batch_size = state.memory_counter.count_batch(&batch);
2336+
state.reservation.try_grow(batch_size)?;
2337+
state.metrics.build_mem_used.add(batch_size);
2338+
state.metrics.build_input_batches.add(1);
2339+
state.metrics.build_input_rows.add(batch.num_rows());
2340+
state.num_rows += batch.num_rows();
2341+
state.batches.push(batch);
2342+
}
2343+
drop(left_stream);
2344+
if prepared && state.batches.is_empty() {
2345+
// Even empty UTF-8 output retains an offset buffer.
2346+
let empty = RecordBatch::new_empty(Arc::clone(&schema));
2347+
state
2348+
.reservation
2349+
.try_grow(state.memory_counter.count_batch(&empty))?;
2350+
state.batches.push(empty);
2351+
}
2352+
let input_bytes = state.memory_counter.memory_usage();
23512353

23522354
// Bind the reservation first so error paths release allocations before their charge.
23532355
let BuildSideState {
@@ -2361,7 +2363,7 @@ async fn collect_left_input(
23612363

23622364
// Admit concatenation copies while the original batches are retained.
23632365
// Arrow keeps a single batch as an inexpensive slice.
2364-
let copy_bytes = if prepared_input_bytes.is_some() && batches.len() > 1 {
2366+
let copy_bytes = if prepared && batches.len() > 1 {
23652367
let bytes = batches.iter().try_fold(0usize, |total, batch| {
23662368
total
23672369
.checked_add(prepared::prepared_copy_bytes(batch)?)
@@ -2413,7 +2415,7 @@ async fn collect_left_input(
24132415
// Use `u32` indices for the JoinHashMap when num_rows ≤ u32::MAX, otherwise use the
24142416
// `u64` indice variant
24152417
// Arc is used instead of Box to allow sharing with SharedBuildAccumulator for hash map pushdown
2416-
if prepared_input_bytes.is_some() {
2418+
if prepared {
24172419
// new_join_hashmap accounts for buckets but not its row-index chain.
24182420
let index_width = if num_rows > u32::MAX as usize {
24192421
size_of::<u64>()
@@ -2442,7 +2444,7 @@ async fn collect_left_input(
24422444
};
24432445

24442446
let scratch_reservation = reservation.new_empty();
2445-
let mut hashes_buffer = if prepared_input_bytes.is_some() {
2447+
let mut hashes_buffer = if prepared {
24462448
let rows = batches.iter().map(RecordBatch::num_rows).max().unwrap_or(0);
24472449
// Combining nullable keys can hold an old and a new validity
24482450
// bitmap at once. NullArray also materializes logical validity.
@@ -2556,7 +2558,7 @@ async fn collect_left_input(
25562558
bounds = None;
25572559
}
25582560

2559-
if let Some(input_bytes) = prepared_input_bytes {
2561+
if prepared {
25602562
drop(batches);
25612563
let retained = RecordBatchMemoryCounter::new().count_batch(&batch);
25622564
let allowance = input_bytes.checked_add(copy_bytes).ok_or_else(|| {

‎datafusion/physical-plan/src/joins/hash_join/exec/prepared.rs‎

Lines changed: 13 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,6 @@
1818
//! Explicit immutable build reuse for embedding executors.
1919
2020
use super::*;
21-
use crate::memory::MemoryStream;
2221
use arrow::array::{Array, AsArray};
2322
use datafusion_common::exec_datafusion_err;
2423
use datafusion_execution::memory_pool::MemoryPool;
@@ -40,7 +39,6 @@ use datafusion_execution::memory_pool::MemoryPool;
4039
/// use hash-table membership filters instead of copying range or IN-list values.
4140
pub struct PreparedHashJoinBuild {
4241
build: Arc<JoinBuildData>,
43-
schema: SchemaRef,
4442
keys: Vec<usize>,
4543
null_equality: NullEquality,
4644
}
@@ -49,7 +47,7 @@ impl fmt::Debug for PreparedHashJoinBuild {
4947
/// Describe immutable metadata without dumping table contents.
5048
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
5149
f.debug_struct("PreparedHashJoinBuild")
52-
.field("schema", &self.schema)
50+
.field("schema", &self.build.batch.schema())
5351
.field("keys", &self.keys)
5452
.field("rows", &self.num_rows())
5553
.field("reserved_bytes", &self.reserved_bytes())
@@ -84,7 +82,7 @@ impl PreparedHashJoinBuild {
8482
/// consuming input or modifying either plan. Cache identity is caller-owned.
8583
pub(super) fn validate(&self, join: &HashJoinExec) -> Result<()> {
8684
let keys = prepared_key_indices(join)?;
87-
if join.left.schema() != self.schema
85+
if join.left.schema() != self.build.batch.schema()
8886
|| keys != self.keys
8987
|| join.null_equality != self.null_equality
9088
{
@@ -130,7 +128,7 @@ impl HashJoinExec {
130128
/// each consuming join publishes them into its own dynamic filter.
131129
pub async fn prepare_build(
132130
&self,
133-
mut input: SendableRecordBatchStream,
131+
input: SendableRecordBatchStream,
134132
pool: Arc<dyn MemoryPool>,
135133
config: Arc<ConfigOptions>,
136134
) -> Result<Arc<PreparedHashJoinBuild>> {
@@ -161,28 +159,6 @@ impl HashJoinExec {
161159
let count = MetricBuilder::new(&metrics_set)
162160
.counter(ARRAY_MAP_CREATED_COUNT_METRIC_NAME, 0);
163161
let reservation = MemoryConsumer::new("PreparedHashJoinBuild").register(&pool);
164-
// Retain each shared input buffer only once. The collector admits an
165-
// independent copy only when it actually concatenates buffered batches.
166-
// Ordinary task-local joins retain their existing accounting policy.
167-
let mut input_memory = RecordBatchMemoryCounter::new();
168-
let mut batches = Vec::new();
169-
// Reject cumulative UTF-8 offset overflow before Arrow allocates a compact build.
170-
let mut concat_values = vec![0usize; schema.fields().len()];
171-
while let Some(batch) = input.try_next().await? {
172-
check_byte_concat_sizes(&batch, &mut concat_values)?;
173-
reservation.try_grow(input_memory.count_batch(&batch))?;
174-
batches.push(batch);
175-
}
176-
drop(input);
177-
if batches.is_empty() {
178-
// Empty UTF-8 arrays still retain an offset buffer.
179-
let batch = RecordBatch::new_empty(Arc::clone(&schema));
180-
reservation.try_grow(input_memory.count_batch(&batch))?;
181-
batches.push(batch);
182-
}
183-
let retained_input_bytes = input_memory.memory_usage();
184-
drop(input_memory);
185-
let input = Box::pin(MemoryStream::try_new(batches, Arc::clone(&schema), None)?);
186162
let data = collect_left_input(
187163
self.random_state.random_state().clone(),
188164
input,
@@ -195,12 +171,11 @@ impl HashJoinExec {
195171
config,
196172
self.null_equality,
197173
count,
198-
Some(retained_input_bytes),
174+
true,
199175
)
200176
.await?;
201177
Ok(Arc::new(PreparedHashJoinBuild {
202178
build: data.build,
203-
schema,
204179
keys,
205180
null_equality: self.null_equality,
206181
}))
@@ -245,11 +220,14 @@ fn utf8_value_span(array: &dyn Array) -> usize {
245220
/// Add `batch`'s byte-column spans to `totals`, one entry per schema column, before
246221
/// an eventual single-batch concat. Reject offset overflow before allocating
247222
/// the value buffer; fixed-width columns leave their totals unchanged.
248-
fn check_byte_concat_sizes(batch: &RecordBatch, totals: &mut [usize]) -> Result<()> {
223+
pub(super) fn check_byte_concat_sizes(
224+
batch: &RecordBatch,
225+
totals: &mut [usize],
226+
) -> Result<()> {
249227
for (array, total) in batch.columns().iter().zip(totals) {
250228
if matches!(array.data_type(), DataType::Utf8) {
251229
*total = total.checked_add(utf8_value_span(array.as_ref()))
252-
.filter(|&sum| sum <= i32::MAX as usize)
230+
.filter(|&sum| i32::try_from(sum).is_ok())
253231
.ok_or_else(|| exec_datafusion_err!(
254232
"Prepared hash-join UTF-8 column exceeds its offset limit; a compact build is required"
255233
))?;
@@ -261,8 +239,8 @@ fn check_byte_concat_sizes(batch: &RecordBatch, totals: &mut [usize]) -> Result<
261239
impl HashJoinExecBuilder {
262240
/// Attach a fully prepared build to a fresh, compatible join execution.
263241
///
264-
/// Validates before mutation, replaces any task-local build future and
265-
/// resets execution metrics. A previously attached task-local dynamic filter
242+
/// [`Self::build`] validates compatibility. Attaching resets the build future
243+
/// and execution metrics. A previously attached task-local dynamic filter
266244
/// keeps its expression handle (also referenced by the probe plan), while
267245
/// its build-report accumulator is reset. The caller must provide a fresh
268246
/// filter expression/probe plan for each independent task.
@@ -276,18 +254,14 @@ impl HashJoinExecBuilder {
276254
/// preserve it. Probe-only rewrites must retain the attached join's `left()`.
277255
/// Replacing that child or changing to incompatible join keys fails; other
278256
/// incompatible join-mode/type changes fail validation in `build`.
279-
pub fn with_prepared_build(
280-
mut self,
281-
prepared: Arc<PreparedHashJoinBuild>,
282-
) -> Result<Self> {
283-
prepared.validate(&self.exec)?;
257+
pub fn with_prepared_build(mut self, prepared: Arc<PreparedHashJoinBuild>) -> Self {
284258
// This removes the ignored child's ordering/equivalences and preserves
285259
// its identity through plan resets.
286260
self.exec.left = Arc::new(crate::empty::EmptyExec::new(self.exec.left.schema()));
287261
self.reset_prepared_runtime_state();
288262
self.exec.prepared_build = Some(prepared);
289263
self.preserve_properties = false;
290-
Ok(self)
264+
self
291265
}
292266
}
293267

0 commit comments

Comments
 (0)