Repository navigation
Commit b6b2e0e
fix: keep the hash join build map reserved while the dynamic filter holds it (#26994)
## Which issue does this PR close?
- Closes #26980.
## Rationale for this change
A `Partitioned` hash join frees its build reservation when the
partition's stream ends, but the dynamic filter and the build
accumulator keep the build map until the plan is dropped, so a finished
join's maps stay allocated while the pool counts them as free. In a
query with several stages, later operators reserve the whole pool on top
of them, and the process can be killed by the OS instead of failing with
`ResourcesExhausted`. #26980 has the cause and the measurements.
This takes the first fix direction from the issue: the reservation
travels with the map, so the memory stays charged for as long as
anything holds the map. This does not reduce memory use or free the maps
sooner. A memory-limited query that only fit because a finished join's
maps were not counted can now fail with `ResourcesExhausted`, and the
finished join then shows up among the top consumers in the error.
## What changes are included in this PR?
- `ReservedMap` (`joins/mod.rs`): a `Map` and the reservation its memory
is charged to, in one `Arc`. `JoinBuildData`, `PushdownStrategy::Map`
and `HashTableLookupExpr` hold it in place of `Arc<Map>`, so every
holder of the map holds its charge.
- `build_in_memory`: charges the hash table or array map and the pruning
bitmap to a reservation created with `new_empty()` from the build
reservation, so the consumer name and error text do not change. The
batch, key arrays and visited bitmap stay on the build reservation and
are released with the stream as before.
- `HashTableLookupExpr::new`: keeps its signature and wraps each map
without a reservation, for the `datafusion-proto` and
`datafusion-pruning` tests. `new_reserved` is the crate-internal
constructor the join uses.
- `PreparedHashJoinBuild::reserved_bytes`: sums both reservations, so
its value is unchanged.
Not in this PR:
- Releasing the maps once every partition has finished probing, the
second fix direction in #26980, frees the memory sooner but changes when
the filter is updated, so it is left for a follow-up. I can open an
issue for it.
- `PushdownStrategy::InList` arrays share the prepared build batch and
have the same lifetime gap, bounded by
`hash_join_inlist_pushdown_max_size` (128 KiB per partition by default).
- *Added after merging #26249:* the hash tables that the routed lookup
builds from IN-list partitions (`in_list_hash_map`) and the merged
pruning bitmap are not reserved either. The hash tables grow with the IN
lists, which the same limit caps, and the bitmap is at most 128 KiB.
## What is the testing strategy for this PR?
- `build_map_stays_reserved_with_dynamic_filter` in `hash_join/exec.rs`,
over `CollectLeft` and `Partitioned`. After the join's stream is
dropped, `pool.reserved()` equals the map plus pruning bitmap bytes
(`Partitioned`) or the whole build (`CollectLeft`). After the plan is
dropped, the filter is the last holder and both modes equal the map plus
bitmap bytes. After the filter is dropped, it is 0. On `main` the
`Partitioned` case fails at the first assertion with 0 reserved against
136,288 expected; ~~`CollectLeft` passes on `main` too.~~ *Corrected in
review:* `CollectLeft` fails after the plan is dropped, with 0 reserved
against 136,288 expected, so the test also covers a filter that outlives
the plan.
- *Added in review:* `array_map_stays_reserved_with_dynamic_filter`,
over the same two modes. Its keys are dense, unlike the first test's, so
the build map is an array map without a pruning bitmap. After the plan
is dropped, `pool.reserved()` equals the `ArrayMap` estimate; after the
filter is dropped, it is 0. On `main` both modes fail after the plan is
dropped with 0 reserved against 160,000 expected. With only the
`array_map_key_range` argument reverted to the build reservation, this
test fails and the other 1,820 `joins::` tests pass.
- *Added after merging #26249:*
`routed_maps_stay_reserved_with_dynamic_filter` runs the `Partitioned`
join over two hash partitions, so the filter is the routed lookup. The
maps stay reserved after every stream ends, the amount does not change
when the plan is dropped, and it is 0 after the filter is dropped. On
`main` nothing is reserved once the streams end. If the routed lookup
holds the maps without their reservation, this test fails and no other
`joins::` test does.
- The test from #26980, run on this branch (not added here: it needs a
global allocator):
| Run | Allocated after the stream is dropped | Reserved | Reserved on
`main` |
|---|---|---|---|
| 1. `Partitioned`, dynamic filter off | 0.2 MiB | 0.0 MiB | 0.0 MiB |
| 2. `Partitioned`, dynamic filter on | 151.5 MiB | 151.3 MiB | 0.0 MiB
|
| 3. `CollectLeft`, dynamic filter on | 182.0 MiB | 181.8 MiB | 181.8
MiB |
Dropping the plan frees everything in all three runs.
## Are there any user-facing changes?
No API change; `HashTableLookupExpr::new` is unchanged. Under a memory
limit, a query whose finished joins' maps were not counted before can
now fail with `ResourcesExhausted`, and spilling operators under the
same limit can spill earlier.
AI assistance: written with Claude Code (Claude Fable 5.1). I reported
the original case, reproduced the issue, reviewed the diff and ran the
tests above.
---------
Co-authored-by: Jay Zhan <[email protected]>1 parent c28a6de commit b6b2e0e
5 files changed
Lines changed: 342 additions & 55 deletions
File tree
- datafusion/physical-plan/src/joins
- hash_join
- exec
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
33 | 33 | | |
34 | 34 | | |
35 | 35 | | |
36 | | - | |
| 36 | + | |
37 | 37 | | |
38 | 38 | | |
39 | 39 | | |
| |||
191 | 191 | | |
192 | 192 | | |
193 | 193 | | |
194 | | - | |
195 | | - | |
| 194 | + | |
| 195 | + | |
| 196 | + | |
196 | 197 | | |
197 | 198 | | |
198 | 199 | | |
| |||
3189 | 3190 | | |
3190 | 3191 | | |
3191 | 3192 | | |
| 3193 | + | |
| 3194 | + | |
| 3195 | + | |
3192 | 3196 | | |
3193 | 3197 | | |
3194 | 3198 | | |
3195 | 3199 | | |
3196 | 3200 | | |
3197 | 3201 | | |
3198 | | - | |
| 3202 | + | |
3199 | 3203 | | |
3200 | 3204 | | |
3201 | 3205 | | |
| |||
3218 | 3222 | | |
3219 | 3223 | | |
3220 | 3224 | | |
3221 | | - | |
| 3225 | + | |
3222 | 3226 | | |
3223 | 3227 | | |
3224 | 3228 | | |
| |||
3314 | 3318 | | |
3315 | 3319 | | |
3316 | 3320 | | |
3317 | | - | |
| 3321 | + | |
3318 | 3322 | | |
3319 | 3323 | | |
3320 | 3324 | | |
| |||
3358 | 3362 | | |
3359 | 3363 | | |
3360 | 3364 | | |
3361 | | - | |
3362 | | - | |
| 3365 | + | |
| 3366 | + | |
3363 | 3367 | | |
3364 | | - | |
| 3368 | + | |
3365 | 3369 | | |
3366 | 3370 | | |
3367 | 3371 | | |
| |||
3541 | 3545 | | |
3542 | 3546 | | |
3543 | 3547 | | |
3544 | | - | |
3545 | | - | |
3546 | | - | |
3547 | | - | |
3548 | | - | |
3549 | | - | |
3550 | | - | |
3551 | | - | |
| 3548 | + | |
| 3549 | + | |
| 3550 | + | |
| 3551 | + | |
| 3552 | + | |
| 3553 | + | |
| 3554 | + | |
| 3555 | + | |
| 3556 | + | |
| 3557 | + | |
| 3558 | + | |
| 3559 | + | |
| 3560 | + | |
| 3561 | + | |
| 3562 | + | |
3552 | 3563 | | |
3553 | 3564 | | |
3554 | 3565 | | |
| |||
3559 | 3570 | | |
3560 | 3571 | | |
3561 | 3572 | | |
3562 | | - | |
3563 | | - | |
| 3573 | + | |
| 3574 | + | |
| 3575 | + | |
| 3576 | + | |
| 3577 | + | |
| 3578 | + | |
| 3579 | + | |
| 3580 | + | |
| 3581 | + | |
| 3582 | + | |
| 3583 | + | |
| 3584 | + | |
| 3585 | + | |
| 3586 | + | |
| 3587 | + | |
| 3588 | + | |
3564 | 3589 | | |
3565 | 3590 | | |
3566 | 3591 | | |
| |||
3606 | 3631 | | |
3607 | 3632 | | |
3608 | 3633 | | |
| 3634 | + | |
| 3635 | + | |
| 3636 | + | |
| 3637 | + | |
| 3638 | + | |
| 3639 | + | |
| 3640 | + | |
| 3641 | + | |
| 3642 | + | |
| 3643 | + | |
| 3644 | + | |
| 3645 | + | |
| 3646 | + | |
| 3647 | + | |
| 3648 | + | |
| 3649 | + | |
| 3650 | + | |
| 3651 | + | |
| 3652 | + | |
| 3653 | + | |
| 3654 | + | |
| 3655 | + | |
| 3656 | + | |
| 3657 | + | |
| 3658 | + | |
| 3659 | + | |
| 3660 | + | |
| 3661 | + | |
| 3662 | + | |
| 3663 | + | |
| 3664 | + | |
| 3665 | + | |
| 3666 | + | |
| 3667 | + | |
| 3668 | + | |
| 3669 | + | |
| 3670 | + | |
| 3671 | + | |
| 3672 | + | |
| 3673 | + | |
| 3674 | + | |
| 3675 | + | |
| 3676 | + | |
| 3677 | + | |
| 3678 | + | |
| 3679 | + | |
| 3680 | + | |
| 3681 | + | |
| 3682 | + | |
| 3683 | + | |
| 3684 | + | |
| 3685 | + | |
| 3686 | + | |
| 3687 | + | |
| 3688 | + | |
| 3689 | + | |
| 3690 | + | |
| 3691 | + | |
| 3692 | + | |
| 3693 | + | |
| 3694 | + | |
| 3695 | + | |
| 3696 | + | |
| 3697 | + | |
| 3698 | + | |
| 3699 | + | |
| 3700 | + | |
| 3701 | + | |
| 3702 | + | |
| 3703 | + | |
| 3704 | + | |
| 3705 | + | |
| 3706 | + | |
| 3707 | + | |
| 3708 | + | |
| 3709 | + | |
| 3710 | + | |
| 3711 | + | |
| 3712 | + | |
| 3713 | + | |
| 3714 | + | |
| 3715 | + | |
| 3716 | + | |
| 3717 | + | |
| 3718 | + | |
| 3719 | + | |
| 3720 | + | |
| 3721 | + | |
| 3722 | + | |
| 3723 | + | |
| 3724 | + | |
| 3725 | + | |
| 3726 | + | |
| 3727 | + | |
| 3728 | + | |
| 3729 | + | |
| 3730 | + | |
| 3731 | + | |
| 3732 | + | |
| 3733 | + | |
| 3734 | + | |
| 3735 | + | |
| 3736 | + | |
| 3737 | + | |
| 3738 | + | |
| 3739 | + | |
| 3740 | + | |
| 3741 | + | |
| 3742 | + | |
| 3743 | + | |
| 3744 | + | |
| 3745 | + | |
| 3746 | + | |
| 3747 | + | |
| 3748 | + | |
| 3749 | + | |
| 3750 | + | |
| 3751 | + | |
| 3752 | + | |
| 3753 | + | |
| 3754 | + | |
| 3755 | + | |
| 3756 | + | |
| 3757 | + | |
| 3758 | + | |
| 3759 | + | |
| 3760 | + | |
| 3761 | + | |
| 3762 | + | |
| 3763 | + | |
| 3764 | + | |
| 3765 | + | |
| 3766 | + | |
| 3767 | + | |
| 3768 | + | |
| 3769 | + | |
| 3770 | + | |
| 3771 | + | |
| 3772 | + | |
| 3773 | + | |
| 3774 | + | |
| 3775 | + | |
| 3776 | + | |
| 3777 | + | |
| 3778 | + | |
| 3779 | + | |
| 3780 | + | |
| 3781 | + | |
| 3782 | + | |
| 3783 | + | |
| 3784 | + | |
| 3785 | + | |
| 3786 | + | |
| 3787 | + | |
| 3788 | + | |
| 3789 | + | |
| 3790 | + | |
| 3791 | + | |
| 3792 | + | |
| 3793 | + | |
| 3794 | + | |
| 3795 | + | |
| 3796 | + | |
| 3797 | + | |
| 3798 | + | |
| 3799 | + | |
| 3800 | + | |
| 3801 | + | |
| 3802 | + | |
| 3803 | + | |
| 3804 | + | |
| 3805 | + | |
| 3806 | + | |
| 3807 | + | |
3609 | 3808 | | |
3610 | 3809 | | |
3611 | 3810 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
45 | 45 | | |
46 | 46 | | |
47 | 47 | | |
48 | | - | |
| 48 | + | |
49 | 49 | | |
50 | 50 | | |
51 | 51 | | |
| |||
290 | 290 | | |
291 | 291 | | |
292 | 292 | | |
293 | | - | |
294 | | - | |
| 293 | + | |
| 294 | + | |
295 | 295 | | |
296 | 296 | | |
297 | 297 | | |
| |||
0 commit comments