Uh oh!
There was an error while loading. Please reload this page.
IN LIST: unify bitmap filter implementations - #23035
Merged
alamb merged 2 commits intoJun 29, 2026
Merged
Conversation
This was referenced Jun 19, 2026
geoffreyclaudeforce-pushed
the
perf/in_list_unify_bitmap_filters
branch
from
June 19, 2026 05:55
c5f4cbd to
8d99ad0Comparegeoffreyclaude
marked this pull request as draft
June 19, 2026 13:30
geoffreyclaudeforce-pushed
the
perf/in_list_unify_bitmap_filters
branch
3 times, most recently
from
June 22, 2026 16:03
3b0ff2a to
0db9c06Comparealamb added a commit
to alamb/datafusion
that referenced
this pull request
Jun 24, 2026
## Which issue does this PR close? - Part of apache#19241. - Stacked on apache#21927. - Next in stack: apache#23012. - Extracted from apache#19390. ## Rationale for this change `IN LIST` evaluates expressions like `x IN (1, 3, 7)`. The list on the right is fixed, so DataFusion can precompute a small lookup structure once and then reuse it for every input row. For `UInt8`, there are only 256 possible values: 0 through 255. That means the lookup can be a tiny checklist with one bit per possible value: - If the list contains `3`, set bit `3`. - If the list contains `7`, set bit `7`. - To check whether an input value is present, read that one bit. So instead of hashing each input value or comparing it against the list, membership becomes one indexed bit test. The bitmap is only 32 bytes, because 256 bits = 32 bytes. This PR adds the first specialized primitive path in the stack as a concrete `UInt8` filter. The `UInt16` version is added in apache#23012, and the shared bitmap abstraction is introduced only after both concrete implementations are visible in apache#23035. ## What changes are included in this PR? - Adds `UInt8BitmapFilter`, a 32-byte bitmap built from the non-null constants in the `IN` list. - Routes `UInt8` constant-list filtering to that bitmap path. - Keeps the same SQL null behavior as the generic path for both `IN` and `NOT IN`. - Moves shared dictionary-needle handling into `static_filter.rs`, so specialized filters can reuse it consistently. - Adds focused tests for `UInt8` null handling and dictionary-encoded needles. ## Are these changes tested? Yes. - `cargo fmt --all` - `cargo test -p datafusion-physical-expr bitmap_filter_u8 --lib` - `cargo test -p datafusion-physical-expr in_list_int_types --lib` - `cargo clippy -p datafusion-physical-expr --all-targets --all-features -- -D warnings` ## Are there any user-facing changes? No. This is an internal performance optimization only. <!-- codex-benchmark-start --> ## Local benchmark snapshot Benchmark command: ```bash cargo bench -p datafusion-physical-expr --profile release-nonlto --bench in_list_strategy -- --save-baseline <name> ``` Method: compare adjacent saved baselines using raw Criterion sample minima (`min(time / iters)`). Lower is better; changes within +/-5% are treated as noise. These numbers were not rerun after splitting the bitmap abstraction into apache#23035. Compared baselines: [apache#21927](apache#21927) -> [apache#23011](apache#23011) Relevant scope: UInt8 narrow-integer rows. Summary: 5 relevant rows, 5 faster, 0 slower, 0 within +/-5%. | Benchmark | Before | After | Change | |---|---:|---:|---:| | `narrow_integer/u8/list=16/match=0%` | 20.39 us | 3.94 us | -80.7% (5.18x faster) | | `narrow_integer/u8/list=16/match=50%` | 38.38 us | 3.98 us | -89.6% (9.65x faster) | | `narrow_integer/u8/list=4/match=0%` | 18.18 us | 3.93 us | -78.4% (4.62x faster) | | `narrow_integer/u8/list=4/match=50%` | 34.63 us | 3.96 us | -88.6% (8.75x faster) | | `nulls/narrow_integer/u8/list=16/match=50%/nulls=20%` | 37.12 us | 4.16 us | -88.8% (8.93x faster) | <!-- codex-benchmark-end --> --------- Co-authored-by: Andrew Lamb <andrew@nerdnetworks.org>
geoffreyclaudeforce-pushed
the
perf/in_list_unify_bitmap_filters
branch
from
June 24, 2026 20:49
0db9c06 to
b22909cCompareadriangb pushed a commit
to pydantic/datafusion
that referenced
this pull request
Jun 26, 2026
## Which issue does this PR close? - Part of apache#19241. - Stacked on apache#23011. - Next in stack: apache#23035. - Extracted from apache#19390. ## Rationale for this change apache#23011 uses a bitmap checklist for `UInt8`, where there are 256 possible values. `UInt16` is the same idea with a larger value range: 0 through 65,535. That is still small enough to represent directly. A `UInt16` bitmap needs one bit for each possible value: - 65,536 possible values - 65,536 bits total - 8 KB of memory Then a lookup is still simple: use the input value as the bit position and check whether that bit is set. For example, if the list contains `42`, bit `42` is set, and every input row with value `42` can be recognized with one bit test. This PR keeps the scope narrow: it adds the unsigned 2-byte bitmap path as a concrete `UInt16` filter. apache#23035 then unifies the `UInt8` and `UInt16` implementations, and apache#23013 uses that shared shape for signed same-width reinterpretation. ## What changes are included in this PR? - Adds `UInt16BitmapFilter`, backed by a heap-allocated 65,536-bit bitmap. - Routes `UInt16` constant-list filtering to that bitmap path. - Keeps the same `IN` / `NOT IN` null behavior as the generic path. - Adds focused coverage for `UInt16` boundary values, nulls, and `NOT IN`. ## Are these changes tested? Yes. - `cargo fmt --all` - `cargo test -p datafusion-physical-expr bitmap_filter_u16 --lib` - `cargo test -p datafusion-physical-expr in_list_int_types --lib` - `cargo test -p datafusion-physical-expr test_in_list_from_array_type_combinations --lib` - `cargo test -p datafusion-physical-expr test_in_list_dictionary_types --lib` - `cargo clippy -p datafusion-physical-expr --all-targets --all-features -- -D warnings` ## Are there any user-facing changes? No. This is an internal performance optimization only. <!-- codex-benchmark-start --> ## Benchmark note No local `in_list_strategy` numbers are included for this PR because the benchmark harness does not currently include a direct `UInt16` case. The available `i16` rows measure the signed reinterpretation path added in apache#23013 after the bitmap unification in apache#23035, not this PR's unsigned `UInt16` bitmap filter. <!-- codex-benchmark-end -->
geoffreyclaudeforce-pushed
the
perf/in_list_unify_bitmap_filters
branch
from
June 26, 2026 10:14
b22909c to
3085965Comparegeoffreyclaude
marked this pull request as ready for review
June 26, 2026 11:44
alamb
approved these changes
Jun 26, 2026
alamb
left a comment
Contributor
There was a problem hiding this comment.
Looks good to me --t ahnks @geoffreyclaude
I have some suggestions for comments, but we can do them as follow on PRs too
I'll kick off the benchmarks to make sure this doesn't change anything
| impl StaticFilter for UInt8BitmapFilter { | ||
| fn null_count(&self) -> usize { | ||
| self.null_count | ||
| pub(super) trait BitmapFilterConfig: Send + Sync + 'static { |
Contributor
There was a problem hiding this comment.
a few comments explaining what this trait is and why it is needed, I think would help future readers (it looks like a package of other types to make the generics on bitmap implementations simpler)
ContributorAuthor
There was a problem hiding this comment.
Added a few comments, which led me to realize the solution was way over-engineered. I'm refactoring the traits a bit into a simpler form.
ContributorAuthor
There was a problem hiding this comment.
Still not perfect, but much better I'd say! The LOC diff of the PR dropped, which is usually a good sign... I'm ok to merge as is 😃
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
alamb
commented
Jun 26, 2026
Contributor
run benchmark in_list_strategy |
adriangbot
commented
Jun 26, 2026
🤖 Benchmark running (GKE) | trigger CPU Details (lscpu)Comparing perf/in_list_unify_bitmap_filters (3085965) to bde8e5b (merge-base) diff using: in_list_strategy File an issue against this benchmark runner |
adriangbot
commented
Jun 26, 2026
🤖 Benchmark completed (GKE) | trigger Instance: CPU Details (lscpu)DetailsResource Usagein_list_strategy — base (merge-base)
in_list_strategy — branch
File an issue against this benchmark runner |
geoffreyclaudeforce-pushed
the
perf/in_list_unify_bitmap_filters
branch
from
June 26, 2026 15:14
a2c6588 to
87d96e2Comparegeoffreyclaudeforce-pushed
the
perf/in_list_unify_bitmap_filters
branch
from
June 26, 2026 16:21
87d96e2 to
a38a6ccComparealamb
commented
Jun 26, 2026
Contributor
run benchmark in_list_strategy |
adriangbot
commented
Jun 26, 2026
🤖 Benchmark running (GKE) | trigger CPU Details (lscpu)Comparing perf/in_list_unify_bitmap_filters (a38a6cc) to bde8e5b (merge-base) diff using: in_list_strategy File an issue against this benchmark runner |
adriangbot
commented
Jun 26, 2026
🤖 Benchmark completed (GKE) | trigger Instance: CPU Details (lscpu)DetailsResource Usagein_list_strategy — base (merge-base)
in_list_strategy — branch
File an issue against this benchmark runner |
alamb
approved these changes
Jun 26, 2026
| /// Arrow already defines the Rust value type as `T::Native`. This trait only | ||
| /// supplies the bitmap storage size for the two integer domains that are small | ||
| /// enough to represent with one bit per possible value. | ||
| pub(super) trait BitmapFilterType: |
Uh oh!
There was an error while loading. Please reload this page.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Which issue does this PR close?
INperformance with specialized implementations #19390.Rationale for this change
#23011 and #23012 intentionally introduce the
UInt8andUInt16bitmap filters as concrete implementations. With both widths visible, the shared shape is now clear: each filter builds a fixed-size bitmap from non-nullINlist values and probes it with the input value's integer bit pattern.This PR factors that duplicated bitmap machinery into one
BitmapFilter<T>, whereTis the Arrow primitive type (UInt8TypeorUInt16Type). Arrow remains the source of truth for the native Rust value throughT::Native; the only extra type-specific piece is the bitmap storage size, supplied by a small privateBitmapFilterTypetrait implemented for those two Arrow types.This does not add a new lookup strategy or change which data types use bitmap filters. The original follow-up #23013 was superseded by #23299, which adds direct Int8/Int16 bitmap support. #23311 continues the bitmap path for Float16.
What changes are included in this PR?
BitmapStoragefor fixed-size bitmap backing stores.BitmapFilterType, a private extension trait that supplies the bitmap storage size forUInt8TypeandUInt16Type.UInt8BitmapFilterandUInt16BitmapFilterimplementations withBitmapFilter<T>.T::Nativedirectly when setting and checking bit positions.UInt8andUInt16routing behavior unchanged.Are these changes tested?
Yes.
cargo fmt --allcargo test -p datafusion-physical-expr bitmap_filter_ --libcargo test -p datafusion-physical-expr in_list_int_types --libcargo test -p datafusion-physical-expr test_in_list_from_array_type_combinations --libcargo test -p datafusion-physical-expr test_in_list_dictionary_types --libcargo clippy -p datafusion-physical-expr --all-targets --all-features -- -D warningsAre there any user-facing changes?
No. This is an internal refactor only.
Benchmark note
No local benchmark numbers are included for this PR because it is intended to be a behavior-preserving refactor of the bitmap filter implementation. Benchmarks were not rerun for this stack split.