Skip to content

perf: run-optimize roaring bitmaps before persisting - #8688

Open
zhangyue19921010 wants to merge 1 commit into
lance-format:mainfrom
zhangyue19921010:perf-index-run-optimize-bitmap
Open

perf: run-optimize roaring bitmaps before persisting#8688
zhangyue19921010 wants to merge 1 commit into
lance-format:mainfrom
zhangyue19921010:perf-index-run-optimize-bitmap

Conversation

@zhangyue19921010

@zhangyue19921010 zhangyue19921010 commented Aug 21, 2026

Copy link
Copy Markdown
Contributor

Bitmaps holding highly contiguous id sets were serialized without run containers, storing O(elements) bytes where the information content is O(runs):

  • Index fragment bitmaps (fragment ids are allocated monotonically) — inlined in the manifest and rewritten on every commit.
  • Overlay coverage bitmaps (physical row offsets; dense overlays cover contiguous ranges) — also inlined in the manifest.
  • Compaction-captured row-addr treemaps persisted for deferred index remap — compaction reads whole fragments, so addresses are dense per-fragment ranges.

Change

Call optimize() before serializing at each of the three write points:

Write point File
From<&IndexMetadata> for pb::IndexMetadata rust/lance-table/src/format/index.rs
serialize_roaring (covers both the protobuf and serde paths) rust/lance-table/src/format/overlay.rs
Row-addr capture in rewrite_files rust/lance/src/dataset/optimize.rs

Compatibility

Run containers are part of the standard roaring serialization format, so existing readers decode the new bytes unchanged. No proto or manifest envelope changes.

Impact

A dense 1M-id bitmap shrinks from ~128 KiB to ~230 bytes (~570x); incompressible bitmaps are written as before (optimize() only converts a container when the run form is smaller).

Bitmaps holding highly contiguous id sets were serialized without run
containers, storing O(elements) bytes where the information content is
O(runs):

- index fragment bitmaps (fragment ids are allocated monotonically),
  inlined in the manifest and rewritten on every commit;
- overlay coverage bitmaps (physical row offsets; dense overlays cover
  contiguous ranges), also inlined in the manifest;
- compaction-captured row-addr treemaps persisted for deferred index
  remap (compaction reads whole fragments, so addresses are dense
  per-fragment ranges).

Call optimize() before serializing at each of the three write points.
Run containers are part of the standard roaring serialization format, so
existing readers decode the new bytes unchanged. A dense 1M-id bitmap
shrinks from ~128 KiB to ~230 bytes; incompressible bitmaps are written
as before.

Tests assert the serialized form is run-length sized (<1% of the
unoptimized bitmap; under one byte per address for the treemap) and that
it round-trips losslessly.

@lance-gatekeeper lance-gatekeeper Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gate recommendation: approve.

The change applies run optimization at the three serialization boundaries that own these persisted bitmaps, while preserving caller-visible values and the standard Roaring format. Focused round-trip and size tests cover index metadata, overlay coverage, and compaction capture.

@lance-gatekeeper lance-gatekeeper Bot added the K-approved Latest Gatekeeper recommendation permits acceptance. label Aug 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

K-approved Latest Gatekeeper recommendation permits acceptance. performance

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant