LiquidCache 使用教程

1. 项目介绍

LiquidCache 是一个为 DataFusion 系统设计的 S3 缓存解决方案。它通过一个优化器规则，能够将成本和延迟降低高达 10 倍。LiquidCache 不是透明的缓存（可以考虑使用 Foyer），它利用查询语义来优化缓存。LiquidCache 将 S3 数据（如 JSON、CSV、Parquet）转码为内部格式，这种格式更加压缩，更适合 NVMe 存储，且对 DataFusion 操作更高效。

2. 项目快速启动

以下是快速启动 LiquidCache 的步骤：

首先，确保你已经安装了 Rust 编译环境和 Cargo 包管理工具。

启动 Cache Server

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let liquid_cache = LiquidCacheService::new(
        SessionContext::new(),
        Some(1024 * 1024 * 1024), // 最大内存缓存大小 1GB
        Some(tempfile::tempdir()?),
        // 磁盘缓存目录
    );
    let flight = FlightServiceServer::new(liquid_cache);
    Server::builder()
        .add_service(flight)
        .serve("0.0.0.0:50051".parse()?)
        .await?
;
    Ok(())
}

或者，你可以使用预构建的 Docker 镜像：

docker run -p 50051:50051 -v ~/liquid_cache:/cache \
ghcr.io/xiangpenghao/liquid-cache/liquid-cache-server:latest \
/app/bench_server --address 0.0.0.0:50051 --disk-cache-dir /cache

连接到缓存服务器

在你的 DataFusion 项目中添加以下依赖：

[dependencies]
liquid-cache-client = "0.1.0"

然后，创建一个新的 DataFusion 上下文，并连接到 LiquidCache：

#[tokio::main]
pub async fn main() -> Result<(), Box<dyn std::error::Error>> {
    /*==========================LiquidCache============================*/
    let ctx = LiquidCacheBuilder::new(cache_server)
        .with_object_store(ObjectStoreUrl::parse(object_store_url.as_str())?, None)
        .with_cache_mode(CacheMode::Liquid)
        .build(SessionConfig::from_env()?);
    /*=================================================================*/
    let ctx: Arc<SessionContext> = Arc::new(ctx);
    ctx.register_table(table_name, ..).await?;
    ctx.sql(&sql).await?.show().await?;
    Ok(())
}

3. 应用案例和最佳实践

社区服务器

LiquidCache 在 Xiangpeng 的 NAS 上运行了一个社区服务器，地址为 https://hex.tail0766e4.ts.net:50051（使用风险自负）。你可以通过运行以下命令来尝试它：

cargo run --bin example_client --release -- \
--cache-server https://hex.tail0766e4.ts.net:50051 \
--file "https://huggingface.co/datasets/HuggingFaceFW/fineweb/resolve/main/data/CC-MAIN-2024-51/000_00042.parquet" \
--query "SELECT COUNT(*) FROM \"000_00042\" WHERE \"token_count\" < 100"

运行 ClickBench

1. 设置仓库

   git clone https://github.com/XiangpengHao/liquid-cache.git
   cd liquid-cache
   

2. 运行 LiquidCache 服务器

   cargo run --bin bench_server --release
   

3. 在另一个终端运行 ClickBench 客户端

   cargo run --bin clickbench_client --release -- --query-path benchmark/clickbench/queries.sql --file examples/nano_hits.parquet
   

   注意：替换 nano_hits.parquet 为实际的 ClickBench 数据集以进行完整的基准测试。

4. 典型生态项目

目前，LiquidCache 主要与 DataFusion 配合使用，但也可以与其他数据分析和查询引擎集成。它的开源性质鼓励社区贡献和扩展，以支持更多的项目和用例。