smallpond

一个基于 DuckDB 和 3FS 构建的轻量级数据处理框架。

特性

• 🚀 由 DuckDB 提供支持的高性能数据处理
• 🌍 可扩展以处理 PB 级数据集
• 🛠️ 操作简便，无需长时间运行的服务

安装

支持 Python 3.8 至 3.12。

pip install smallpond

快速入门

# 下载示例数据
wget https://duckdb.org/data/prices.parquet

import smallpond

# 初始化会话
sp = smallpond.init()

# 加载数据
df = sp.read_parquet("prices.parquet")

# 处理数据
df = df.repartition(3, hash_by="ticker")
df = sp.partial_sql("SELECT ticker, min(price), max(price) FROM {0} GROUP BY ticker", df)

# 保存结果
df.write_parquet("output/")
# 显示结果
print(df.to_pandas())

文档

有关详细指南和 API 参考：

• 入门指南
• API 参考

性能

我们使用 GraySort 基准测试（脚本）在由 50 个计算节点和 25 个存储节点组成的集群上评估了 smallpond，该集群运行 3FS。基准测试在 30 分钟 14 秒内对 110.5TiB 的数据进行了排序，平均吞吐量达到 3.66TiB/min。

详情请参阅 3FS - Gray Sort。

开发

pip install .[dev]

# 运行单元测试
pytest -v tests/test*.py

# 构建文档
pip install .[docs]
cd docs
make html
python -m http.server --directory build/html

许可证

本项目采用 MIT 许可证授权。

smallpond 快速上手指南

环境准备

• 操作系统：支持 Linux、macOS 和 Windows
• Python 版本：3.8 至 3.12
• 前置依赖：无需额外安装复杂依赖，框架内置基于 DuckDB 和 3FS 的核心引擎

💡 提示：国内用户建议使用清华或阿里镜像源加速 pip 安装。

安装步骤

使用 pip 直接安装最新稳定版：

pip install smallpond -i https://pypi.tuna.tsinghua.edu.cn/simple

如需安装开发版本或包含文档/测试依赖的版本：

pip install .[dev]
# 或
pip install .[docs]

基本使用

以下是最简单的数据处理流程示例：

1. 下载示例数据

wget https://duckdb.org/data/prices.parquet

2. 编写 Python 脚本进行处理

import smallpond

# 初始化会话
sp = smallpond.init()

# 加载 Parquet 数据
df = sp.read_parquet("prices.parquet")

# 数据重分区（按 ticker 哈希分为 3 份）
df = df.repartition(3, hash_by="ticker")

# 执行 SQL 聚合查询
df = sp.partial_sql("SELECT ticker, min(price), max(price) FROM {0} GROUP BY ticker", df)

# 保存结果为 Parquet 文件
df.write_parquet("output/")

# 打印结果预览
print(df.to_pandas())

该示例展示了从数据加载、重分区、SQL 聚合到结果输出的完整流程，适用于本地快速验证或小规模数据处理任务。