Skip to content

fix: chunked index stream to work around arrow's 2Gb limits#664

Open
kushudai wants to merge 1 commit into
lance-format:mainfrom
kushudai:kudai/chunked-index-stream
Open

fix: chunked index stream to work around arrow's 2Gb limits#664
kushudai wants to merge 1 commit into
lance-format:mainfrom
kushudai:kudai/chunked-index-stream

Conversation

@kushudai

@kushudai kushudai commented Jun 29, 2026

Copy link
Copy Markdown

Chunk BTree index Arrow handoff to stay under Arrow's 2 GiB offset cap

What

  • The range-BTree build buffers a whole fragment group into one narrow VectorSchemaRoot. A value column exceeding 2 GiB overflows Arrow's 32-bit-offset VarChar/VarBinary buffer during accumulation.
  • Add ArrowBatchChunker: accumulates rows into multiple narrow batches, rolling before any var-width column's data buffer crosses the 2 GiB cap (plus a row-count ceiling so fixed-width/offset buffers stay under it). Fails fast on a single value over the cap.
  • Add ChunkedArrowReader: SingleBatchArrowReader generalized to emit N pre-built batches; caller owns/closes them.
  • Rewire buildForFragmentGroup to chunked accumulation. lance-core re-zones the multi-batch stream, so the built index is identical to a single-batch handoff; peak memory is unchanged.

Notes

  • Both new classes are schema/index-agnostic. Only the range-BTree path is wired as it's the only build that hands a Spark-side Arrow stream to lance-core (withPreprocessedData); FTS/zonemap/fragment-BTree read from the dataset directly and never buffer a VectorSchemaRoot.

Test plan

  • Unit (JUnit 5): ArrowBatchChunkerSuite (byte-budget split, single batch, over-budget isolation, fixed-width row cap, order/content) and ChunkedArrowReaderSuite (ordered emission, exhaustion).
  • Integration (Spark 3.5, native Lance): AddIndexTest range-mode — create, repeat/replace, rows_per_range, index-details — all pass.
  • spotless:apply + checkstyle:check clean.

@kushudai kushudai changed the title Chunked index stream to work around arrow's 2Gb limits fix: Chunked index stream to work around arrow's 2Gb limits Jun 29, 2026
@github-actions github-actions Bot added the bug Something isn't working label Jun 29, 2026
@github-actions

Copy link
Copy Markdown
Contributor

ACTION NEEDED
Lance follows the Conventional Commits specification for release automation.

The PR title and description are used as the merge commit message. Please update your PR title and description to match the specification.

For details on the error please inspect the "PR Title Check" action.

@kushudai kushudai changed the title fix: Chunked index stream to work around arrow's 2Gb limits fix: chunked index stream to work around arrow's 2Gb limits Jun 29, 2026
@kushudai kushudai marked this pull request as ready for review June 30, 2026 15:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant