Crate buff_rs 

buff-rs

A Rust implementation of BUFF: Decomposed Bounded Floats for Fast Compression and Queries.

Based on the VLDB 2021 paper: “BUFF: Accelerating Queries in Memory through Decomposed Bounded Floats”.

Overview

BUFF provides efficient compression and query execution for bounded floating-point data (data with a known precision/scale). It achieves this through:

1. Precision Bounding: Determining the minimum bits needed to represent values within a given precision tolerance
2. Byte Slicing: Column-oriented storage where each bit position across all values is stored contiguously
3. Direct Query Execution: Aggregate and filter operations can execute directly on compressed data

Key Differences from decimal-bytes

Feature	decimal-bytes	buff-rs
Data Type	Single decimal values	Arrays of floats
Precision	Arbitrary (unlimited)	Bounded (fixed scale)
Storage	Row-oriented	Column-oriented (byte-sliced)
Primary Use	Document storage	Columnar/time-series data
Queries	Compare after decode	Query compressed data

Quick Start

use buff_rs::BuffCodec;

// Create a codec with 3 decimal places of precision (scale=1000)
let codec = BuffCodec::new(1000);

// Encode an array of f64 values
let data = vec![1.234, 5.678, 9.012, -3.456];
let encoded = codec.encode(&data).unwrap();

// Decode back to f64
let decoded = codec.decode(&encoded).unwrap();

// Query directly on compressed data
let sum = codec.sum(&encoded).unwrap();
let max = codec.max(&encoded).unwrap();

Choosing a Scale

The scale determines the precision of encoded values:

Scale	Decimal Places	Example
10	1	3.1
100	2	3.14
1000	3	3.142
10000	4	3.1416
100000	5	3.14159

Choose a scale that matches your data’s required precision. Higher scales provide more precision but may reduce compression ratio.

Compression Performance

Compression ratio depends on data characteristics:

• Narrow range: Better compression (fewer bits needed)
• Wide range: More bits needed, lower compression
• Repetitive values: Good compression

Typical compression ratios range from 0.3x to 0.8x of the original size.

Modules

precision

Precision bound computation for bounded floating-point values.

Structs

BuffCodec

BUFF compressor/decompressor for bounded floating-point arrays.

BuffMetadata

Metadata about BUFF-encoded data.

SpecialValue

Represents a special floating-point value with its position.

Enums

BuffError

Errors that can occur during BUFF operations.

SpecialValueKind

Types of special floating-point values.

Type Aliases

Result

Convenience type alias for Results with BuffError.