Rust列式存储库columnar_derive使用指南

概述

columnar_derive 是一个Rust派生宏工具，用于实现高效的数据序列化与压缩，特别适合列式存储场景。它通过自动生成序列化和反序列化代码，简化了列式数据结构的处理。

主要特性

• 自动派生列式存储的序列化/反序列化逻辑
• 支持高效的数据压缩
• 类型安全的操作
• 减少样板代码

使用方法

1. 添加依赖

首先在Cargo.toml中添加依赖：

[dependencies]
columnar_derive = "0.1"
columnar = "0.1"

2. 基本使用

use columnar_derive::{Columnar, ColumnarDecoder, ColumnarEncoder};

#[derive(Columnar, Debug, PartialEq)]
struct Person {
    id: u32,
    name: String,
    age: u8,
    is_active: bool,
}

3. 序列化和反序列化

fn main() {
    // 创建示例数据
    let people = vec![
        Person {
            id: 1,
            name: "Alice".to_string(),
            age: 30,
            is_active: true,
        },
        Person {
            id: 2,
            name: "Bob".to_string(),
            age: 25,
            is_active: false,
        },
    ];

    // 序列化
    let mut encoder = ColumnarEncoder::new();
    for person in &people {
        encoder.encode(person).unwrap();
    }
    let encoded_data = encoder.finish().unwrap();

    // 反序列化
    let mut decoder = ColumnarDecoder::new(&encoded_data);
    let decoded_people: Vec<Person> = decoder.decode_all().unwrap();

    assert_eq!(people, decoded_people);
}

4. 自定义压缩选项

#[derive(Columnar, Debug)]
#[columnar(compress = "zstd")]
struct SensorData {
    timestamp: u64,
    temperature: f32,
    humidity: f32,
    #[columnar(compress = "none")]  // 这个字段不压缩
    sensor_id: String,
}

高级用法

1. 处理嵌套结构

#[derive(Columnar, Debug)]
struct Order {
    id: u64,
    customer: Customer,  // 嵌套结构
    items: Vec<OrderItem>,  // 嵌套集合
}

#[derive(Columnar, Debug)]
struct Customer {
    id: u32,
    name: String,
}

#[derive(Columnar, Debug)]
struct OrderItem {
    product_id: u32,
    quantity: u16,
    price: f64,
}

2. 使用字典编码优化字符串

#[derive(Columnar, Debug)]
#[columnar(dict_encode = true)]
struct LogEntry {
    level: String,  // 会被字典编码
    message: String,
    #[columnar(dict_encode = false)]
    trace_id: String,  // 不应用字典编码
}

完整示例demo

// 完整示例：使用columnar_derive处理电商订单数据
use columnar_derive::{Columnar, ColumnarDecoder, ColumnarEncoder};

// 定义嵌套数据结构
#[derive(Columnar, Debug, PartialEq)]
struct Order {
    order_id: u64,
    customer: Customer,
    items: Vec<OrderItem>,
    total: f64,
    #[columnar(compress = "none")] // 订单ID不压缩
    order_code: String,
}

#[derive(Columnar, Debug, PartialEq)]
struct Customer {
    id: u32,
    #[columnar(dict_encode = true)] // 客户名称使用字典编码
    name: String,
    email: String,
}

#[derive(Columnar, Debug, PartialEq)]
struct OrderItem {
    product_id: u32,
    #[columnar(compress = "zstd")] // 产品名称使用zstd压缩
    product_name: String,
    quantity: u16,
    price: f64,
}

fn main() {
    // 创建示例订单数据
    let orders = vec![
        Order {
            order_id: 1001,
            customer: Customer {
                id: 1,
                name: "张三".to_string(),
                email: "zhangsan@example.com".to_string(),
            },
            items: vec![
                OrderItem {
                    product_id: 101,
                    product_name: "Rust编程指南".to_string(),
                    quantity: 1,
                    price: 99.99,
                },
                OrderItem {
                    product_id: 205,
                    product_name: "高性能笔记本".to_string(),
                    quantity: 2,
                    price: 5999.99,
                },
            ],
            total: 6099.98,
            order_code: "ORD-2023-1001".to_string(),
        },
        Order {
            order_id: 1002,
            customer: Customer {
                id: 2,
                name: "李四".to_string(),
                email: "lisi@example.com".to_string(),
            },
            items: vec![
                OrderItem {
                    product_id: 305,
                    product_name: "无线耳机".to_string(),
                    quantity: 1,
                    price: 299.99,
                },
            ],
            total: 299.99,
            order_code: "ORD-2023-1002".to_string(),
        },
    ];

    // 序列化
    let mut encoder = ColumnarEncoder::new();
    for order in &orders {
        encoder.encode(order).unwrap();
    }
    let encoded_data = encoder.finish().unwrap();
    
    println!("序列化后数据大小: {} 字节", encoded_data.len());

    // 反序列化
    let mut decoder = ColumnarDecoder::new(&encoded_data);
    let decoded_orders: Vec<Order> = decoder.decode_all().unwrap();

    // 验证数据一致性
    assert_eq!(orders, decoded_orders);
    println!("数据反序列化验证成功!");
}

性能建议

1. 对于高基数字段(如ID)，禁用压缩可能更高效
2. 对小数据集，字典编码可能增加开销
3. 批量处理数据比单条处理更高效

注意事项

• 确保所有字段类型都实现了必要的trait
• 大型结构可能需要调整默认的压缩设置
• 版本兼容性：序列化格式可能随库版本变化

columnar_derive 通过简化列式存储的实现，使得在Rust中处理大数据集变得更加高效和方便。