Skip to content

Keep the DecimalByteParts MSP at its logical integer width - #11354

Closed
connortsui20 wants to merge 9 commits into
developfrom
ct/dbp-integer-child
Closed

connortsui20 wants to merge 9 commits into
developfrom
ct/dbp-integer-child

Conversation

@connortsui20

Copy link
Copy Markdown
Member

Summary

#10905 decoded a narrow MSP into a decimal Widen, which needed a precision label and a min_max scan to choose it. CodSpeed reported decoding 4.7x to 8.4x slower with that design. This PR removes the scan by fixing the MSP's logical dtype from the decimal precision: the signed integer at the canonical width W(p), capped at i64. Narrower storage is an integer Widen. Since W(p) is the smallest width that holds 10^p - 1, every value of a narrower signed integer fits Decimal(p), so decoding only needs to sign-extend.

This replaces the closed #10905 and #10992, covering CD5 with CD7 folded in. It depends on #11303 and must merge after it. The base remains ct/cuda-widen until then.

Changes

The writer stores the Widen child rather than the wrapper, so the wire remains readable by old readers.

On read, a narrower stored MSP gets an integer Widen without a scan. Only a wider legacy MSP gets an eager checked cast on the host, rather than trusting that its valid values fit. Device buffers are rejected for that legacy conversion.

CPU and GPU decoding peel the Widen and widen straight to the canonical decimal width, avoiding a copy to the logical MSP width followed by another widening copy.

The compressor uses WidenArray::encode to narrow every MSP, including one next to lower parts, then compresses the narrow child before rewrapping it. Passing the wrapper to compress_child would canonicalize it and lose the narrow storage.

split_decimal always returns the MSP at its logical width rather than inheriting the decimal buffer's width, so decimals with narrower or wider storage still encode.

With lower parts, compare_constant_wide loses its whole-answer shortcut when the constant's MSP word is outside the narrow child's range. The follow-up is to check against the Widen child's range. Lower parts remain unsupported on the GPU, and the CUDA tests only run in GPU CI. CodSpeed's dbp_compute decode benchmark should show a single widening copy with no scan. Benchmark results for this PR are pending.

New tests cover legacy decimal storage in both width directions, decoding a wrapped MSP with and without lower parts, wire round trips, checked overflow, and invalid values in null lanes. The golden trees now expose the integer Widen node.

API Changes

  • DecimalByteParts::try_new and try_new_with_lower_parts, and DecimalBytePartsData::validate, now require the logical MSP dtype fixed by the precision, with matching decimal nullability. Lower parts must be non-nullable u64, and their count is bounded by the precision.
  • split_decimal now takes an explicit lower-part count. Callers can obtain the smallest count from the new lower_part_count function, which considers valid values only.
  • vortex_array::arrays::decimal::narrowed_decimal is removed.
  • The public, hidden _benchmarking::assemble_decimal helper now requires the validated DBP part layout and always returns canonical-width decimal storage.
Validation

Checked tip 8025ec3490 on #11303 at 712a4a337e.

  • cargo clippy with --all-targets --all-features -- -D warnings passed for vortex-decimal-byte-parts, vortex-btrblocks, vortex-compat, vortex-array, vortex-arrow, vortex-duckdb, vortex, and vortex-cuda.
  • cargo +nightly-2026-09-10 fmt --all --check passed.
  • cargo nextest run -p vortex-decimal-byte-parts -p vortex-btrblocks -p vortex-compat passed all 717 tests, with none skipped.
  • uv run vortex-test/compat-gen/scripts/compat.py check --mode last passed all 43 v0.93.0 files, with no failures or skips. Both old DBP files passed, including the narrow and wide legacy MSP cases in decimal_byte_parts_narrow_msp.vortex.
  • CUDA runtime tests require GPU CI and were not run locally.

Device-resident Widen arrays cannot use the CPU fallback. Restore their logical width on the device so narrow integer and decimal children can execute through CUDA.

Progress towards #11284.

Signed-off-by: Connor Tsui <connor.tsui20@gmail.com>

Signed-off-by: Alexander Droste <alexander.droste@protonmail.com>
Signed-off-by: Connor Tsui <connor.tsui20@gmail.com>
Signed-off-by: Connor Tsui <connor.tsui20@gmail.com>
Signed-off-by: Connor Tsui <connor.tsui20@gmail.com>
Signed-off-by: Connor Tsui <connor.tsui20@gmail.com>
Signed-off-by: Connor Tsui <connor.tsui20@gmail.com>
Signed-off-by: Connor Tsui <connor.tsui20@gmail.com>
Signed-off-by: Connor Tsui <connor.tsui20@gmail.com>
Signed-off-by: Connor Tsui <connor.tsui20@gmail.com>
@connortsui20 connortsui20 added the changelog/break A breaking API change label Nov 9, 2026
Base automatically changed from ct/cuda-widen to develop November 10, 2026 10:58
@connortsui20

Copy link
Copy Markdown
Member Author

Replaced by a stack of smaller PRs, #11456 to #11460. The core change from this PR is now #11459.

@connortsui20 connortsui20 mentioned this pull request Nov 17, 2026
33 of 36 tasks
connortsui20 added a commit that referenced this pull request Nov 17, 2026
## Summary

- Tracking Issue: #10701
- Replaces #11354

#10701 needs one buffer width for each decimal precision, but
DecimalByteParts decoding and `narrowed_decimal` in the compressor still
make narrower decimal arrays on `develop`.

The MSP's logical dtype now depends on the precision alone: the signed
integer at the canonical width, capped at `i64`. The canonical width is
the smallest signed width that holds `10^p - 1`, so every value of a
narrower signed integer is a valid `Decimal(p)` value, and a narrow MSP
is an integer `Widen` that needs no precision label and no scan. The
closed #10905 decoded a narrow MSP into a decimal `Widen` instead, which
needed both, and CodSpeed reported decoding 4.7x to 8.4x slower with
that design.

## Changes

The wire stores the child of the `Widen`, not a new form, so old readers
read new files and the integer `Widen` wire form can wait for #10733.

Only files from earlier releases hold an MSP that is wider than its
logical dtype. The reader gives it a checked copy on the host instead of
a cast, because a cast keeps a null value that fits the width and skips
its check when the child has exact min and max statistics. That MSP
fails to read from device memory.

`WidenArray::from_stored_integer` and `WidenArray::to_stored_integer`
live in `vortex-array` instead of private helpers, because any encoding
that fixes the dtype of an integer child needs the same two steps.

Null slots no longer choose the lower-part count or the MSP type, which
is why `p38_large_null_slots` goes from one lower part to none. The GPU
decoder still returns `i64` storage above precision 18 until #11460. For
review, read the commits one at a time, because the second one is a pure
`git mv`.

### Known costs

- `decimal_wide_p40` doubles in size, because the canonical width of
precision 40 is `i256`.
- Decoding an `i64` MSP at precision 38 gains one copy, to `i128`.
- With lower parts, compare loses its whole-answer shortcut when the
constant's MSP word is outside the range of the narrow child. A
`TODO(connor)` in `compare.rs` names the fix.
- At precision 18 or below, the Arrow `Decimal128` export of a narrow
MSP makes two copies instead of one. The follow-up is an Arrow export
hook keyed by encoding.

## API Changes

- `DecimalByteParts::try_new`, `try_new_with_lower_parts`, and
`DecimalBytePartsData::validate` require the logical MSP dtype of the
precision and at most the number of lower parts that the precision
needs.
- `split_decimal` takes the validity mask and an explicit lower-part
count.
- `narrowed_decimal` is removed.
- A file whose wider MSP holds a valid value outside the precision no
longer reads.

<details>
<summary>Validation</summary>

On the rebased stack (`develop` at `26a12a670b`):

- `cargo +nightly-2026-11-13 fmt --all --check` passes.
- `cargo clippy --all-targets --all-features -- -D warnings` passes for
`vortex-decimal-byte-parts`, `vortex-btrblocks`, `vortex-array`,
`vortex-file`, `vortex-compat`, `vortex-arrow`, and `vortex-cuda`.
- `cargo nextest run --all-features` passes for
`vortex-decimal-byte-parts`, `vortex-btrblocks`, `vortex-compat`, and
`vortex-file`, and both golden tests pass with `INSTA_UPDATE=no`.

Before the rebase (`develop` at `d81bd4ce25`), the same checks also
passed for `vortex-duckdb` and `vortex`, with `cargo bench -- --test`
for the DBP, `to_arrow`, `decimal_export`, and
`common_encoding_tree_throughput` benches. `compat.py check --mode all`
read every fixture of the 28 published versions, including the wide
legacy MSP files of 0.91.0 to 0.93.0. Of the generated fixtures, only
`decimal_byte_parts_narrow_msp.vortex` changes.

The debug assert in the v1 scheme, the `WidenArray` stored integer
functions, and the rebase onto `develop` at `c58d6237e5` came after
these runs. They only passed the format check, and no local clippy or
test run covers them yet.

Not run: the CUDA tests (no GPU), CodSpeed, and the arm64 and Windows
jobs. `cargo clippy -p vortex-btrblocks --all-targets` with default
features fails on an unused import in `vortex-btrblocks/src/tests.rs`
that is already on `develop`.

</details>

---------

Signed-off-by: Connor Tsui <connor.tsui20@gmail.com>
@connortsui20
connortsui20 deleted the ct/dbp-integer-child branch November 17, 2026 21:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

changelog/break A breaking API change

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant