perf(scan): merge narrow splits at boundaries only some fields of a struct have - #11128

Summary

• Tracking Issue: Wide nested scans hold GiBs of native memory: tiny misaligned splits each decode whole column chunks #11123

Problem: A scan splits a file wherever any column's chunk ends, and a split decodes the whole chunk of every column it overlaps. When a struct's fields chunk at unrelated rows, as list elements and dictionary-encoded columns of a wide nested file do, the union of their boundaries leaves spans of a few dozen rows. Successive splits then each decode the same chunks of the other fields. On a 180 MB list-layout file, a full scan held 3.6 GiB of native memory.

Fix: The struct reader marks boundaries that only some of its fields have as soft. SplitBy::LayoutSubSplitting merges spans that end at a soft boundary until they reach 8,192 rows. Boundaries that every field has are never merged, and neither are boundaries from layouts above the struct, so files whose columns chunk alike split as before.

Result: full scan of one file, with Arrow conversion as JNI does it. Live native bytes come from a counting allocator:

Changes

• RowSplits gains soft marks. Each struct field registers into its own RowSplits, and the struct takes their union. Any boundary that not every field has is marked soft.
  • The shared-boundary intersection is computed once. On the existing 256-column split-collection benchmark, the warm median falls from about 338 ms to 3 ms.
  • The struct's validity child is classified like any field, so a nullable struct merges the same way at any depth.
  • Soft marks inherited from nested structs are kept.
  • A single-field struct without validity registers exactly as before.
  • SplitBy::Layout collects positions only (BoundaryMode::PositionsOnly), so it skips the classification.
• SplitBy::LayoutSubSplitting merges spans ending at a soft boundary until they reach DEFAULT_MIN_SPLIT_ROWS (8,192, the writer's row block), or max_rows if that is smaller. It never merges a span past max_rows. The merge runs before the existing sub-division of wide spans.

Tests

• Struct reader, over real layouts written with RepartitionStrategy:
  • fields chunked every 1,000 and 3,000 rows mark only the unshared boundaries soft;
  • the same struct under a top-level chunked layout keeps the chunk end hard;
  • LayoutSubSplitting merges soft boundaries and keeps shared boundaries, for nullable and non-nullable structs.
• merge_small_spans: unit cases plus 1,000 generated cases. They check endpoints, hard boundaries, exact coverage, minimum span length at kept soft boundaries, and the sub-division that follows.
• The wider split-collection benchmark case, and *_sub_splitting variants that measure the default SplitBy.

On the fork (quantcast#67, same change), these passed: 836 vortex-layout library tests; Clippy for vortex-layout and vortex-file (all targets, all features, -D warnings); pinned rustfmt; the JNI and Spark builds; git diff --check.

This branch cherry-picks that change onto develop without conflicts. On the port, with the follow-up commits: 750 vortex-layout tests; Clippy for vortex-layout and vortex-file (all targets, all features, -D warnings); pinned rustfmt; git diff --check.

Update on 2026-11-09

Merged upstream develop (1c60cac79) cleanly in b7ebcd336, including the existing ty version pin and renamed-rule fix that address the Python lint failure.

Compared missing_stats[16] on the updated PR against the same upstream commit, using the repository's bench profile and locked dependencies on this macOS ARM64 host. Both builds passed. Six runs per version were interleaved in base/PR/PR/base order, each with 10,000 samples of 100 calls. Median of the per-run medians:

The local difference is 1.35%, with overlapping per-run median ranges (upstream 765.5–791.7 ns; PR 772.6–792.2 ns). This does not reproduce the earlier 17.96% CodSpeed simulation regression. The pruning implementation, benchmark fixture and lockfile are identical to the current upstream baseline; the PR changes split collection. Native walltime is supporting evidence and does not replace the CI CPU simulation.

Reproduction after building each checkout with cargo bench -p vortex-layout --bench zone_map_prune --no-run --locked:

<benchmark-binary> --bench 'missing_stats::16$' --color never --sample-count 10000 --sample-size 100

Fresh CI and CodSpeed workflows are awaiting maintainer approval. No additional tests, lint or formatting checks were run for this merge.

Not done here

• The minimum is a row count. Rows with many list elements are larger than rows with few, so a minimum in bytes would be more precise.
• The minimum isn't tuned beyond 8,192 rows. An earlier variant used less memory at 16,384.

AI assistance

Disclosed per the AI policy: AI tools helped write and review this change. Claude Code prepared this upstream port, issue and PR description at my request. I am the responsible contributor.

🤖 Generated with Claude Code