Implementation:Lance format Lance LegacyBitmapEncoding

Knowledge Sources	Lance
Domains	Encoding, Legacy_Format
Last Updated	2026-02-08 19:33 GMT

Overview

The legacy bitmap encoding is a physical encoding for densely packed boolean buffers stored as 1 bit per value in the Lance v2.0 format.

Description

⚠️ DEPRECATED: This is legacy code from the Lance v1/v2.0 format, retained only for backward compatibility. See Lance_format_Lance_Warning_Deprecated_Legacy_Encodings.

This module implements the dense bitmap page encoding for the legacy (v2.0) Lance file format. DenseBitmapScheduler reads boolean data stored in Arrow's bit-endian format at 1 bit per value. It calculates precise byte ranges from the buffer_offset and bit-level row ranges, handling bit-alignment by tracking the bit_offset within each byte. The BitmapDecoder reassembles the boolean buffer from potentially multiple non-contiguous byte chunks using Arrow's BooleanBufferBuilder::append_packed_range. The output is a FixedWidthDataBlock with bits_per_value set to 1. This encoding is primarily used for validity bitmaps in nullable columns and for boolean data type columns.

Usage

Use this encoding for boolean arrays and validity bitmaps. The physical dispatch creates DenseBitmapScheduler when encountering a Flat encoding with bits_per_value of 1. The BasicPageScheduler uses this for its validity buffer in the some-nulls mode.

Code Reference

Source Location

rust/lance-encoding/src/previous/encodings/physical/bitmap.rs

Signature

#[derive(Debug, Clone, Copy)]
pub struct DenseBitmapScheduler {
    buffer_offset: u64,
}

impl DenseBitmapScheduler {
    pub fn new(buffer_offset: u64) -> Self;
}

impl PageScheduler for DenseBitmapScheduler { /* ... */ }

Import

use lance_encoding::previous::encodings::physical::bitmap::DenseBitmapScheduler;

I/O Contract

Input	Type	Description
buffer_offset	u64	Starting byte offset of the bitmap buffer in the file
ranges	&[Range<u64>]	Row ranges (bit-level) to decode

Output	Type	Description
decoded	DataBlock::FixedWidth	Fixed-width block with bits_per_value=1 containing the boolean buffer

Usage Examples

use lance_encoding::previous::encodings::physical::bitmap::DenseBitmapScheduler;
use lance_encoding::decoder::PageScheduler;
use std::sync::Arc;

// Create a bitmap scheduler at a given file offset
let scheduler = DenseBitmapScheduler::new(1024);

// Schedule bit ranges for reading
let ranges = vec![0..100, 200..300];
let io: Arc<dyn EncodingsIo> = /* from context */;
let decoder_fut = scheduler.schedule_ranges(&ranges, &io, 0);

Related Pages

• Lance_format_Lance_LegacyPhysicalDispatch - Creates DenseBitmapScheduler for 1-bit Flat encodings
• Lance_format_Lance_LegacyBasicEncoding - Uses bitmap for validity buffers
• Lance_format_Lance_LegacyValueEncoding - Alternative encoding for multi-bit fixed-width values
• Heuristic:Lance_format_Lance_Warning_Deprecated_Legacy_Encodings