Skip to content

Decode selected PCO pages for primitive-index takes - #10828

Closed
danking wants to merge 25 commits into
dk/pco-logical-page-indexfrom
dk/pco-selective-take
Closed

danking wants to merge 25 commits into
dk/pco-logical-page-indexfrom
dk/pco-selective-take

Conversation

@danking

@danking danking commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Use the logical-row page index to decompress only pages containing requested non-null values for primitive-index take. Group requests by page, reuse chunk decoder setup, and gather values in the requested order while preserving duplicates and logical nulls. Files without an index retain the existing fallback; compact range take and slice handling are introduced separately.

@codspeed

codspeed Bot commented Oct 26, 2026 •

Copy link
Copy Markdown

Merging this PR will regress 3 benchmarks

4 warnings, 1 note

⚠️ Walltime results may be unreliable

Some benchmarks used the Walltime instrument outside CodSpeed Macro Runners, which can make the results inconsistent.

Learn more about Macro Runners

See affected benchmarks

⚠️ Unable to measure the execution of 1 benchmark

This benchmark measured no execution time, so its result is not comparable and counts as unchanged. This usually happens when the compiler removes the code under test.

Prevent compiler optimizations

See affected benchmarks

⚠️ 15 benchmarks are dominated by system calls

System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.

Learn more about system calls

See affected benchmarks

⚠️ Base and head ran on different runner types

Some benchmarks with significant performance changes were compared across different runner types, so the changes might not come from the code. Run base and head on the same runner type, or use CodSpeed Macro Runners for more stable results.

Learn more about Macro Runners

Open the report in CodSpeed to investigate

ℹ️ 40 benchmarks have no flamegraph

The flamegraph wasn't generated: the symbols of the profiling trace could not be resolved, because no information about the language frames was collected.

See affected benchmarks

⚡ 5 improved benchmarks
❌ 3 regressed benchmarks
✅ 2457 untouched benchmarks
⏩ 12 skipped benchmarks1

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

Mode Benchmark BASE HEAD Efficiency
❌ CPU Simulation chunked_dict_primitive_canonical_into[f64, (1000, 1000, 10)] 146.5 µs 200.7 µs -27.02%
❌ CPU Simulation metadata_open_batch[true] 506.8 ms 646.6 ms -21.62%
❌ CPU Simulation test_scan_filter[int] 3 ms 3.4 ms -11.22%
⚡ CPU Simulation selection[("ranges", true)] 540.1 ms 2.1 ms ×260
⚡ CPU Simulation selection[("ranges", false)] 344.7 ms 1.7 ms ×200
⚡ CPU Simulation selection[("sparse", true)] 539.7 ms 10.9 ms ×50
⚡ CPU Simulation selection[("sparse", false)] 344.4 ms 12.2 ms ×28
⚡ CPU Simulation selection[("contiguous", true)] 638.3 ms 516.8 ms +23.51%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.


Comparing dk/pco-selective-take (eea0ae2) with dk/pco-logical-page-index (0d82a2d)

Open in CodSpeed

Footnotes

  1. 12 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

@danking danking added the changelog/performance A performance improvement label Oct 26, 2026
@danking
danking force-pushed the dk/pco-selective-take branch from aa62381 to c1c91ba Compare October 26, 2026 18:01
@danking
danking force-pushed the dk/pco-selective-take branch from c1c91ba to 0affd29 Compare October 26, 2026 18:04
@danking
danking force-pushed the dk/pco-selective-take branch 2 times, most recently from 3367172 to f783c34 Compare October 26, 2026 18:16
@danking
danking force-pushed the dk/pco-selective-take branch 2 times, most recently from 661d07c to 4c93a25 Compare October 26, 2026 18:33
@danking

danking commented Oct 26, 2026

Copy link
Copy Markdown
Contributor Author

@claude review

@github-actions

github-actions Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @danking's task in 2m 28s —— View job


PR #10828 review: selective PCO take

  • Gather context (diff vs dk/pco-logical-page-index)
  • Review take.rs, access.rs, decoder.rs
  • Review tests and registration call sites
  • Post findings

The sparse/grouped design holds up. Requests are sorted, repeated rows are resolved once, each page is decoded once, and results are scattered into an initialized output. Bounds checks run before any allocation, and legacy metadata uses a single ranked validity mask instead of a per-index scan. The kernel registration matches how ALP, BitPacked and the others do it. I found one test-module compile error that will break CI, and one large block of code that can never run.

🔴 Blocking

1. selective_take_tests.rs doesn't compile: PiecewiseSequenceArray is not imported.
contiguous_take_preserves_nullable_index_dtype (L257) calls PiecewiseSequenceArray::try_new(...), but the import list (L4–23) has no use vortex_array::arrays::PiecewiseSequenceArray;. selection_contract_tests.rs does import it, but that import doesn't reach this module. Because the module won't build, every vortex-pco test fails, not just this one. I didn't compile this locally; CI "Linters and Tests" was still queued when I checked.
Fix this →

🟠 Should address

2. gather_typed, the Output<T, NULLABLE> helper and the stride-0/strided handling can never run (about 200 lines in take.rs L433–605).
Here is how TakeExecute::take routes requests:

  • grouped = (!summary.contiguous).then_some(..), and contiguous can only be true when the mask is AllTrue and every index is the previous one plus 1 (L155–163).
  • So whenever grouped is None, primitive_runs returns exactly one Run { start: Some(_), stride: 1 }. gather pattern-matches that case and goes straight to stream_range (L325–334).
  • Therefore gather_typed::<_, true/false> is never reached. The same goes for the run.stride == 0 branch, the strided for offset loop, and the zero-page branch in gather (L335–348), which zero_page_take already handles at L91.

Run.stride is always 1 in this PR. My guess is this code is staged for the PiecewiseSequence follow-up. If so, I'd move it to that PR, where it will actually be called and tested. Otherwise it ships untested, and the compiler won't flag it because it is technically reachable. At minimum, add a comment saying it's reserved for range descriptors.

3. The CodSpeed regression in test_repeated_scan_scalar_at[int] (−14%) needs a route check before it's dismissed.
Base and head ran on different runner types, so this may be noise. Still, every single-index take with a valid index now goes through the following steps:

  • execute::<PrimitiveArray>
  • min_max
  • execute_mask
  • stream_range, which builds a fresh PageDecoder, computes the whole-page validity mask, and decodes the full page into scratch

If scalar-at scans end up in this kernel, that fixed overhead per call is a plausible cause. A cheap early exit for indices.len() == 1 (resolve plus a single page read) might be worth it, or confirm that this path isn't hit.

4. The module docs still show the old registration.
lib.rs L12–20 tells users to call session.arrays().register(vortex_pco::Pco). That still works, but it silently skips the take kernel, as your own registry_only_session_retains_legacy_take_fallback test shows. Point the example at vortex_pco::initialize(&session). Related: vortex-btrblocks/tests/golden.rs:456 and the existing pco test sessions (tests.rs, page_index_tests.rs, selection_contract_tests.rs) register only Pco, so they never exercise the new kernel. That's probably intentional for some of them, but worth a look.

🟡 Minor / style

  1. Imports inside initialize (lib.rs L88–92) are on the CLAUDE.md "Common Mistakes" list. Move them to module level, or follow ALP's split and put initialize in rules.rs / kernel.rs. Likewise, access.rs L393/L395 spells out crate::decoder::PageDecoder when take.rs already imports it.
  2. Validation differs between legacy paths. In access.rs, span checks that mask.true_count() equals the total stored values (L278–282). resolve_impl (legacy branch, L231–236) doesn't. If the validity marks fewer valid rows than there are stored values, the grouped path quietly returns misaligned values while the streaming path errors. I'd run the same vortex_ensure_eq! when self.legacy is first populated.
  3. AccessState::values indexes array.chunk_metas[page.chunk] directly (L397). Corrupt metadata would panic there, while stream_range uses .get(..).ok_or_else(..). Using .get here too would keep it consistent.
  4. gather_grouped keeps every decoded page alive until the end because it uses AccessState::<true>. Pages are visited in sorted order and never revisited, so retaining them only adds peak memory, roughly the size of all touched pages. prefer_canonical_primitive caps that below the canonical size, but dropping decoded after each page group (or using a non-retaining decode for the values phase) would bring it down to one page.
  5. PageDecoder::read zero-fills the whole buffer and then decodes over it (decoder.rs L46). That's harmless but wastes one pass per decoded page in the grouped path. Use with_capacity plus decoding into spare capacity if pco allows it, or just note why the zero-fill is needed.
  6. Legacy heuristic in prefer_canonical_primitive. requests >= index.pages.len() means a legacy array with only a few pages always takes the canonical path. That's reasonable, but a short comment explaining why the page count stands in for the byte estimate would help reviewers.
  7. validate_runs repeats the bounds check. validate_extrema already proved every defined index is within bounds. I'd keep it only if it exists for the upcoming range descriptors (see item 2).

✅ Looks good

  • Adding Page::chunk to the page index, together with a per-operation BTreeMap<usize, ChunkDecompressor>, cleanly fixes multi-chunk addressing (commit 4c93a25).
  • read_into checks both n_processed and finished, so a truncated page can never write a partially filled output.
  • Null indices with out-of-range physical values (i64::MIN / i64::MAX) are never inspected, and there's a test for it.
  • stream_range copies the sliced source validity directly instead of rebuilding it.
  • Test coverage is good: sliced-of-sliced sources, legacy and unknown metadata versions, repeated and scattered requests, empty and mostly-null requests, and dtype nullability.

Checks

I did not run any builds or tests; this was a read-only review. Item 1 comes from reading the import list, not from a compile. CI "Linters and Tests" was still queued when I checked.

@danking
danking force-pushed the dk/pco-selective-take branch from 4c93a25 to ce5758f Compare October 26, 2026 18:42
@danking
danking force-pushed the dk/pco-selective-take branch 4 times, most recently from d4b2869 to 73dbbe4 Compare October 26, 2026 20:09
@danking
danking force-pushed the dk/pco-selective-take branch 4 times, most recently from e348dea to fbe9df9 Compare October 26, 2026 20:23
Signed-off-by: Daniel King <dan@spiraldb.com>
Signed-off-by: Daniel King <dan@spiraldb.com>
Signed-off-by: Daniel King <dan@spiraldb.com>
Signed-off-by: Daniel King <dan@spiraldb.com>
Signed-off-by: Daniel King <dan@spiraldb.com>
Signed-off-by: Daniel King <dan@spiraldb.com>
Signed-off-by: Daniel King <dan@spiraldb.com>
Signed-off-by: Daniel King <dan@spiraldb.com>
Signed-off-by: Daniel King <dan@spiraldb.com>
…stry guards

Signed-off-by: Daniel King <dan@spiraldb.com>
Signed-off-by: Daniel King <dan@spiraldb.com>
@danking
danking force-pushed the dk/pco-selective-take branch from e2ba944 to 76e27b4 Compare October 30, 2026 15:08

danking commented Oct 30, 2026

Copy link
Copy Markdown
Contributor Author

Addressed the remaining applicable take feedback in 76e27b4: scatter directly from each decoded primitive page using checked reads, eliminating the per-page temporary index array, second take dispatch, and selected-value array. The public example now calls initialize, basic and new test sessions exercise that registration, and vortex-file initializes PCO outside its retained array-registry guard.

The older Run/Output/contiguous planner, BTreeSet page estimate, legacy selective path, and codec zero-fill changes are absent from the current diff, as requested by Daniel. Global semantic prefix validation and corrupt-index conformance tests remain intentionally excluded under his explicit scope/validation policy; this does not promise every malformed index returns Err rather than panicking. The checked page-value reads preserve the previous gather's local bounds failure. Local independent source review passed; no builds/tests or timing reruns were performed, and no CodSpeed regression was acknowledged.

@github-actions

Copy link
Copy Markdown
Contributor

This PR has been marked as stale because it has been open for 14 days with no activity. Please comment or remove the stale label if you wish to keep it active, otherwise it will be closed in 7 days

@github-actions github-actions Bot added the stale This PR is stale and will be auto-closed soon label Nov 15, 2026
@danking danking closed this Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

changelog/performance A performance improvement stale This PR is stale and will be auto-closed soon

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant