Allow configuring DELTA_BINARY_PACKED block layout

[emecii]

Which issue does this PR close?

• Closes Override DeltaBitPackEncoder Defaults #2282.

Rationale for this change

The DELTA_BINARY_PACKED encoder currently fixes its layout at 128 values per block and four mini blocks for INT32, and 256 values per block and four mini blocks for INT64. The Parquet stream records this layout, and representative workloads can benefit from different compression and throughput trade-offs.

What changes are included in this PR?

This adds validated DeltaBinaryPackedEncoderOptions and global/per-column WriterProperties setters. The column writer passes the full resolved column properties to the encoder factory. Custom layouts now configure direct DELTA_BINARY_PACKED values as well as the length, prefix-length, and suffix-length integer encoders inside DELTA_LENGTH_BYTE_ARRAY and DELTA_BYTE_ARRAY.

The custom encoder constructor is infallible because it only accepts already validated options. Existing get_encoder callers and type-specific defaults remain unchanged. Public documentation links to the Parquet format and explains the block-size and mini-block trade-offs.

Benchmark evidence

The committed Criterion benchmark compares four layouts on 16,384 deterministic INT32 values and reports encoded bytes in each benchmark ID. On this arm64 macOS host, comparing the INT32 default 128/4 layout with 256/4:

• Uniform-width random deltas: 66,699 to 66,123 bytes (0.86% smaller), median encode time 66.76 to 62.71 us (6.1% faster), and median decode time 9.71 to 9.16 us (5.7% faster).
• Locally varying bit widths: 35,131 to 42,161 bytes (20.0% larger), median encode time was effectively unchanged at 61.70 versus 61.68 us, and median decode time fell from 10.59 to 9.22 us (12.9% faster).

These results support retaining the defaults generally. A larger layout can help long inputs with stable delta distributions, but bursty local ranges can materially increase size; users should benchmark representative data. Results are machine and workload specific.

Benchmark command:

cargo bench --locked -p parquet --bench bit_packing --features "experimental default" -- delta_binary_packed_layout --sample-size 20 --warm-up-time 1 --measurement-time 2

Are these changes tested?

Yes.

• cargo test --locked -p parquet --all-features --lib --tests
• cargo clippy --locked -p parquet --all-targets --all-features -- -D warnings
• cargo fmt --all -- --check
• git diff --check
• The focused layout benchmark above

Are there any user-facing changes?

Yes. This adds an additive public configuration API for all encoders that use DELTA_BINARY_PACKED internally. Existing defaults and behavior are unchanged unless users opt in.

AI assistance

This PR was prepared with OpenAI Codex assistance for investigation, implementation, benchmark construction, test execution, and review-response drafting.

[etseidl]

Thanks @emecii, this looks interesting. I've left a few suggestions.

I think we'd want some recommendations on when one would want to change the defaults, with some numbers (encoding/decoding benchmarks and compression stats) to back up the recommendations.

[emecii]

Addressed in df45969. I added a deterministic Criterion benchmark that reports encoded bytes plus encode/decode timings. In one 20-sample local run over 16,384 INT32 values, moving from 128/4 to 256/4 reduced stable-width output from 66,699 to 66,123 bytes, encode time from 66.76 to 62.71 us, and decode time from 9.71 to 9.16 us. For locally varying widths, output grew from 35,131 to 42,161 bytes while decode time fell from 10.59 to 9.22 us. The public docs and PR body now use these results to recommend retaining defaults unless representative data shows a worthwhile compression/throughput trade-off.