1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | chdb-datastore-clickhouse-agent-skills |
| 项目自述名称 | 仓库自述名 “ClickHouse Agent Skills”（本子技能自身标题为 “chdb DataStore”） |
| 作者/维护者 | ClickHouse Inc（官方仓库，metadata.json 标注 organization: ClickHouse Inc）；子技能提交者为 chdb 项目核心维护者 auxten、ShawnChen-Sirius（GitHub API 实测） |
| 来源链接 | https://github.com/ClickHouse/agent-skills/tree/main/skills/chdb-datastore |
| 许可证 | Apache-2.0（GitHub API 实测） |
| GitHub Stars | 该子目录本身无独立 star 计数；合集仓库 agent-skills 整体 496 star（GitHub API）不可作为本子技能依据；所封装的开源引擎 chdb-io/chdb 独立仓库 2,845 star（GitHub API 实测，2 天前仍有提交） |
| Forks | agent-skills 仓库 32；chdb-io/chdb 126（GitHub API 实测） |
| 最新版本 | 4.1.0（技能自身 metadata.json 声明；底层 chdb 包 PyPI 当前为 4.2.1，略滞后但接口兼容） |
| 安装方式 | npx skills add clickhouse/agent-skills 或官方 CLI clickhousectl skills；底层需 pip install chdb |
2. 功能介绍与亮点
chdb DataStore 是 ClickHouse 官方 2026 年 3 月正式发布的 pandas 兼容 API：把 import pandas as pd 改成 import chdb.datastore as pd，其余代码不变，操作会被惰性编译为 ClickHouse SQL 并做谓词下推、列裁剪、LIMIT 传播等优化后再执行。
- 支持 209 个 DataFrame 方法，覆盖过滤、分组、排序、字符串/日期访问器等常见 pandas 用法
- 内置 16+ 数据源连接器（S3、MySQL、PostgreSQL、MongoDB、ClickHouse Cloud、Iceberg、Delta Lake 等），可直接跨源 join，无需先搭 ETL 管道
- 官方发布时以 AI 数据分析平台 Hex 作为首发合作伙伴，DataStore 已预装进 Hex notebook
- 附带
verify_install.py环境自检脚本、完整 API 参考与 10+ 可运行示例
3. 适用场景
固定分类：数据分析与可视化
适合已经熟悉 pandas、但在大文件或多数据源场景下遇到性能瓶颈的 Python 开发者与数据分析师：本地 CSV/Parquet 分析提速、无需先落库的跨库联表（如 MySQL 订单表 join S3 上的 Parquet 客户表）、notebook 场景下的探索式分析。全程本地开源即可用，不需要注册云账号。
4. 跨 Agent 兼容性
- Claude Code：✅ 原生支持——仓库自带
.claude-plugin市场清单，npx skills add可自动检测并安装 - Codex：❓ 未验证——技能遵循 agentskills.io 开放规范、SKILL.md 格式通用，但未见仓库对 Codex 的专门适配声明
- OpenClaw：❓ 未验证——抓取材料中未出现相关声明
- Hermes Agent：❓ 未验证——抓取材料中未出现相关声明
5. 推荐理由
改一行 import 就能让现有 pandas 代码接上 ClickHouse 的列式执行引擎提速，还能免搭 ETL 直接跨数据源联表；官方持续维护、零付费依赖、文档与示例齐全，对已经会写 pandas 但苦于本地/多源数据量变大的用户是低门槛的直接增益。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | 子目录自身无独立 star、commit 数少（2 次），但底层引擎 chdb-io/chdb 有 2,845 star 与多年独立讨论历史（Hacker News 多篇报道）；经 GitHub code search 验证，DataStore 已被观测平台 MapleTechLabs/maple（1,580★，2026-07-24 仍有提交）等至少 2 个独立第三方仓库直接引入（vendored）；chdb-io/chdb 仓库中另有约 20 个由独立贡献者（wudidapaopao、matrey、YarShev 等）针对 DataStore 提交的 issue/PR，反映真实使用与打磨 |
| 可用性 | 9 | pip install chdb 即可用，import chdb.datastore as pd 一行切换；SKILL.md 含决策树、连接器全表、API 参考与自检脚本；子目录最近提交 2026-05-26，距今约 2 个月，维护活跃；核心功能完全免费、无需注册任何云账号 |
| 安全性 | 8 | 见下方安全检查清单 |
| 综合 | 8.0 | 三项均值 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令执行范围 | 仅 pip install chdb；verify_install.py 为本地环境自检脚本，不执行任意 shell 命令 |
| ② 运行时联网外发数据 | 无默认外联；仅当用户显式调用 from_s3/from_mysql/from_mongodb 等连接器并提供自己的连接信息时才产生网络访问，用途透明 |
| ③ API key/凭据 | 连接远程数据源的账号密码由用户在自己代码中直接传参（如 password="pass"），技能本身不额外存储凭据 |
| ④ 可疑指令 | 审阅 SKILL.md、README、metadata.json 与 verify_install.py，未发现 prompt injection 或异常指令 |
| ⑤ 作者/组织信誉 | ClickHouse Inc 官方组织账号，提交者为 chdb 项目可验证的核心维护者 |
| ⑥ License | Apache-2.0，明确 |
| ⑦ 最近维护时间 | 子目录最近提交约 2 个月前，底层 chdb 包 2 天前仍有提交，活跃维护 |
7. 跟同类 Skills 相比的优势
同为“本地/嵌入式 OLAP 引擎”类目的技能与本技能的定位差异：
| 技能 | 出品方 | 核心接口 | 是否需付费账号 | 独有特点 |
|---|---|---|---|---|
| chdb DataStore（本次推荐） | ClickHouse Inc | pandas 风格 DataFrame API | 否 | 现有 pandas 代码近乎零改动即可提速，16+ 连接器原生跨源 join |
| chdb SQL（同仓库姊妹技能） | ClickHouse Inc | 原生 SQL（chdb.query()） |
否 | 面向已经习惯写 SQL、需要 UDF/流式查询等高级特性的用户 |
| duckdb-skills | DuckDB 官方 | 自然语言/SQL slash command | 否 | 面向 Claude Code 插件市场，六个子技能协同管理会话状态，但无 pandas 原生 API |
DataStore 的差异化在于：不要求用户改写现有 pandas 逻辑或切换到 SQL 心智模型，“一行 import 切换”是三者中对已有 pandas 代码库最友好的迁移路径。
8. 用户评价
chdb-io/chdb 仓库内可查到独立贡献者 YarShev 提交并已合并的 DataStore 性能优化 PR（#591：.columns/.dtypes/.shape/.index 免物化访问），核心维护者 wudidapaopao 评价其“看起来是很好的优化”（“looks great, really nice optimization”）并附带前后对比基准数据佐证；同仓库另有约 20 项由 matrey、chibugai 等不同独立用户针对 DataStore 提交的功能请求与问题报告。这些是可核实的具名工程协作记录，但目前尚无独立平台上的评测式用户评价。
9. 其他补充
仓库遵循 agentskills.io 开放技能规范；同仓库还含 chdb-sql、clickhouse-best-practices、clickhousectl-local-dev 等其他技能，均可按需单独安装。
10. 安装使用方式
- 推荐方式：
npx skills add clickhouse/agent-skills，CLI 会自动检测已安装的 agent 并询问装到哪个目录 - ClickHouse 官方 CLI：
clickhousectl skills - 前置依赖：
pip install chdb（Python 3.9+，macOS 或 Linux） - 安装后无需重启；在代码中写
import chdb.datastore as pd或from datastore import DataStore即可触发；可运行python scripts/verify_install.py验证环境
11. 注意事项
- DataStore 是 2026 年 3 月才发布的较新特性，部分 pandas 3.0 新增 API（如
read_iceberg、str.replace(dict)）在底层仓库中仍是待办事项，遇到生僻方法报错时可回退到原生 pandas - 本技能是合集仓库
ClickHouse/agent-skills中的一个子目录，只需 DataStore 功能时装本子目录即可，无需整仓库 - Codex / OpenClaw / Hermes Agent 的兼容性未获官方明确声明，跨 agent 使用前建议自行验证 SKILL.md 能否被目标 agent 正确加载
- 连接 MySQL/PostgreSQL/S3 等远程数据源时，凭据由用户自行在代码中提供，请遵循自己团队的密钥管理规范，不要把明文密码写入版本库