Struct SparsePostingBlock 

pub struct SparsePostingBlock {
    pub header: PostingBlockHeader,
    /* private fields */
}

A compressed block of posting list entries for sparse vector search.

On-disk format

┌────────────────────────────── 16-byte header ─────────────────────────────┐
│ num_entries(u16) │ bits_per_delta(u8) │ reserved(u8) │ min_offset(u32) │ │
│ max_offset(u32)  │ max_weight(f32)                                      │
└──────────────────────────────────────────────────────────────────────────┘
┌──── body ────────────────────────────────────────────────────────────────┐
│ bitpacked delta-encoded doc offsets (BitPacker4x, groups of 128)        │
│ — ceil(num_entries / 128) groups, last group padded to 128 entries      │
│ f16 little-endian weights (2 bytes × num_entries, no padding)           │
└──────────────────────────────────────────────────────────────────────────┘

Dual access modes

This type supports two access patterns used by different cursor modes in the query pipeline:

• Materialized (decode()): Decompresses the full block into owned Vecs. Used by eager cursors for small dimensions. Transitions the body from Encoded to Decoded on first call.

• Zero-copy (peek_header, decompress_offsets_into, read_value_at, raw_weight_bytes): Static methods that operate directly on a &[u8] slice (e.g. from an Arrow block cache) without constructing a SparsePostingBlock. Used by lazy/view cursors for large dimensions where we only touch a fraction of each block’s entries.

Fields

header: PostingBlockHeader

The 16-byte header fields (num_entries, bits_per_delta, min/max offset, max weight).

Implementations

impl SparsePostingBlock

pub fn from_sorted_entries( entries: &[(u32, f32)], ) -> Result<Self, SparsePostingBlockError>

Build a block from pre-sorted (offset, value) pairs.

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn decode(&mut self) -> (&[u32], &[f32])

Decode this block in place, transitioning from Encoded to Decoded.

Returns (&[u32], &[f32]) — the decompressed offsets and values. If already Decoded, returns the existing data. Returns empty slices for directory blocks (which are always Encoded and have no posting-block-shaped body).

Callers do not need to call this directly — offsets() and values() invoke it automatically.

pub fn offsets(&mut self) -> &[u32]

Decompressed doc offsets. Decodes on first call for deserialized posting blocks. Returns &[] for directory blocks.

pub fn values(&mut self) -> &[f32]

Decompressed f32 weights. Decodes on first call for deserialized posting blocks. Returns &[] for directory blocks.

pub fn serialize(&self) -> Vec<u8>

Serialize to bytes: 16-byte header + bitpacked deltas + f16 weights.

pub fn serialized_size(&self) -> usize

Byte length of the serialized representation (computable without decompression).

pub fn deserialize(bytes: &[u8]) -> Result<Self, SparsePostingBlockError>

Deserialize from bytes. Stores body bytes as Encoded; call decode() to decompress posting blocks on first access.

Returns an error if the buffer is too small for the header or the body is shorter than the header implies.

pub fn peek_header( bytes: &[u8], ) -> Result<PostingBlockHeader, SparsePostingBlockError>

Read the 16-byte header without heap allocation.

pub fn decompress_offsets_into( bytes: &[u8], hdr: &PostingBlockHeader, buf: &mut Vec<u32>, )

Decompress offsets from raw serialized bytes into a reusable buffer. Must not be called on directory blocks.

pub fn raw_weight_bytes<'a>( bytes: &'a [u8], hdr: &PostingBlockHeader, ) -> &'a [u8]

Zero-copy slice of the raw f16 weight bytes from serialized data. Each weight is 2 bytes (f16 little-endian). Must not be called on directory blocks.

pub fn read_value_at( bytes: &[u8], hdr: &PostingBlockHeader, index: usize, ) -> f32

Read a single f16 weight at index and convert to f32. O(1). Must not be called on directory blocks.

pub fn decompress_values_into( bytes: &[u8], hdr: &PostingBlockHeader, buf: &mut Vec<f32>, )

Decompress f16 weights from raw serialized bytes into a reusable f32 buffer. Must not be called on directory blocks.

pub fn is_directory(&self) -> bool

Trait Implementations

impl Clone for SparsePostingBlock

fn clone(&self) -> SparsePostingBlock

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SparsePostingBlock

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.