[parquet] Add BloomFilterProperties builder API to make bloom filter configuration explicit

[alamb]

Is your feature request related to a problem or challenge?

This PR added bloom filter folding and improved the default sizing behavior for bloom filters.

• Add bloom filter folding to automatically size SBBF filters #9628

Today, BloomFilterProperties is still a public struct with public fields, which makes the API harder to evolve cleanly. @adriangb came up with a way to use implicit internal state to avoid breaking the public API but that is somewhat confusing and not explicit in the APIs

While reviewing #9628, I also found a related behavioral issue in the current builder flow: disabling and re-enabling bloom filters does not fully reset the hidden "explicit NDV was set" state. That means re-enabling can preserve stale configuration intent instead of returning to the default behavior. The relevant disable path is also not covered by tests, and the per-column implicit-NDV resolution path is currently uncovered as well.

Describe the solution you'd like

Add a BloomFilterPropertiesBuilder and make bloom filter configuration more explicit.

In particular, this follow-on change should aim to:

• introduce a dedicated builder for bloom filter configuration
• make the differences between these cases clear:
  • default NDV derived from row group sizing
  • explicitly configured NDV
  • explicitly configured FPP
  • enabling/disabling bloom filters
• Make BloomFilterProperties fields non pub
• add relevant accessors

Describe alternatives you've considered

Keep the current API and add more documentation around the current semantics.

For example, a more explicit API could look something like:

let props = WriterProperties::builder()
    .set_column_bloom_filter_properties(
        ColumnPath::from("col"),
        BloomFilterProperties::new()
            .with_fpp(0.01)
            .with_max_ndv(10_000) // new builder PAIs
    )
    .build();

Compared with direct public-field configuration, a builder like this would make it clearer which values are explicitly configured and which are left to defaults.

Additional context

Follow-on from PR #9628:

• Add bloom filter folding to automatically size SBBF filters #9628

Relevant review discussion:

• Add bloom filter folding to automatically size SBBF filters #9628 (comment)

Additional follow-up work for this issue should include regression tests for:

• disable -> re-enable bloom filter configuration
• column-specific bloom filter configuration with implicit NDV resolution
• explicit vs default NDV behavior

[CuteChuanChuan]

take

[alamb]

Nice -- thank you @CuteChuanChuan

[CuteChuanChuan]

Hi @alamb, Posting a plan and a few open questions before sending a draft PR.

I'm targeting 59.0.0 (May 2026) since this involves making BloomFilterProperties fields private, which is a breaking change. Let me know if that's the wrong release to aim for.

Plan

• Add BloomFilterPropertiesBuilder in parquet/src/file/properties.rs
• Make BloomFilterProperties fields private; add fpp() and ndv() accessors
• Migrate WriterPropertiesBuilder::set_bloom_filter_* to delegate to the builder internally
• Fix the disable → re-enable stale-state issue mentioned in the issue
• Add the regression tests called out in the issue (disable/re-enable, per-column implicit NDV, explicit vs default NDV)

Proposed API sketch

// Building
let props = BloomFilterProperties::builder()
    .with_fpp(0.01)
    .with_max_ndv(10_000)
    .build();

// Reading
assert_eq!(props.fpp(), 0.01);

// Per-column via WriterProperties
let writer_props = WriterProperties::builder()
    .set_column_bloom_filter_properties(
        ColumnPath::from("col"),
        BloomFilterProperties::builder().with_fpp(0.01).build(),
    )
    .build();

Open questions

1. Entry point: ::new() vs ::builder()
   The issue description shows BloomFilterProperties::new().with_fpp(...), but the rest of this crate consistently uses Foo::builder() to return the builder (e.g. WriterProperties::builder()). I'd lean toward BloomFilterProperties::builder() for consistency. OK to deviate from the issue example?

2. Validation: Result vs panic
   The existing set_bloom_filter_fpp panics on out-of-range input. I'd keep the same behavior in with_fpp/with_ndv (panic via assert!) so build() can return BloomFilterProperties directly without Result, matching WriterPropertiesBuilder::build(). Any reason to prefer Result here?

3. with_max_ndv naming
   Agreed with_max_ndv better reflects the post-folding semantics. For the existing WriterPropertiesBuilder::set_bloom_filter_ndv, want me to rename → set_bloom_filter_max_ndv (breaking) or keep the old name?

4. Internal state for enable/disable
   To fix the stale-state issue, I'm thinking of representing per-column config internally as Option<BloomFilterProperties> so disable cleanly resets to None. This may touch a few call sites — happy to go a different direction if you'd prefer keeping the separate enabled: bool flag.

I'll wait for direction on these before sending the PR. Thanks!

[alamb]

Entry point: ::new() vs ::builder()

I recommend both, personally

Validation: Result vs panic

I think keeping the same behavior is fine. We could also add a try_build or something that returnes a Result() so the user can pick between the options

keep the old name?

I would vote keep the old name and mark it deprecated and call to the new function. See deprecation guidelines in this crate

This may touch a few call sites — happy to go a different direction if you'd prefer keeping the separate enabled: bool flag.

I am not sure without seeing the code. Maybe we can try and fix the stale state thing as a subsequent PR 🤔

[alamb]

(thank you for working on this, BTW)