1. 基本信息
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 名称 | chdb-sql | GitHub API / SKILL.md |
| 项目自述名称 | “chdb SQL — ClickHouse in Your Python Process”（SKILL.md 内标题） | SKILL.md |
| 作者/维护者 | ClickHouse 官方（clickhouse/agent-skills 仓库；chdb 引擎归属 chdb-io，隶属 ClickHouse 生态） |
GitHub API |
| 来源链接 | https://github.com/clickhouse/agent-skills/tree/main/skills/chdb-sql | — |
| 许可证 | Apache License 2.0 | GitHub API |
| GitHub Stars / Forks | 所属合集仓库 clickhouse/agent-skills 492★/32 forks（该数字属整个合集，不代表本技能个体热度）；本技能封装的底层引擎独立仓库 chdb-io/chdb 2,838★/126 forks |
GitHub API |
| 最新版本 | SKILL.md 标注 version 4.1；仓库最近一次相关提交 2026-05-26 | 仓库文件树 / SKILL.md |
| 安装方式 | npx skills add clickhouse/agent-skills（交互式安装到已检测到的 agent），或 ClickHouse 官方 CLI clickhousectl skills；运行依赖 pip install chdb |
仓库 README |
2. 功能介绍与亮点
chdb-sql 让 Claude Code 等 agent 直接在 Python 进程内执行 ClickHouse SQL，不需要单独部署或连接一台 ClickHouse 服务器。
核心能力：
- 查询本地文件（Parquet/CSV/JSON）、URL、S3 路径，或跨源联表——通过
s3()、mysql()、postgresql()、iceberg()、deltaLake()、remoteSecure()等 table function 直接 JOIN 不同数据源 - 内置 Session 机制，支持有状态的多步骤查询管道与参数化查询
- 集成 ClickHouse 全部 1000+ 内置 SQL 函数（窗口函数、地理函数、JSON 路径操作等）
- 配套 9 个可运行示例、API 参考文档（
references/api-reference.md、table-functions.md）与环境验证脚本，agent 可按需渐进式加载 - 与同仓库姊妹技能 chdb-datastore（pandas 风格 DataFrame API）明确分工：pandas 链式操作用 chdb-datastore，原生 SQL 诉求用 chdb-sql，SKILL.md 中有清晰的技能路由说明
亮点：官方 ClickHouse 团队出品并持续维护，2026-04-14 合并 PR #14 正式引入该技能，2026-05-26 有元数据同步更新；底层 chDB 引擎是 ClickHouse 官方孵化的独立开源项目，在 Hacker News 上有过多轮技术讨论。
3. 适用场景
固定分类：数据分析与可视化
- 数据分析师或开发者需要对本地 CSV/Parquet 文件或远程数据库做即席 SQL 查询，又不想安装配置一整套数据库服务时
- 需要跨 S3、MySQL、Postgres、Iceberg、Delta Lake 等异构数据源做联表分析，但不想为每次分析单独写 ETL 脚本的场景
- 已经在用 Pandas 做数据分析、但某些操作用 SQL 表达更直观（窗口函数、复杂 JOIN）的场景
4. 跨 Agent 兼容性
- Claude Code：原生支持——仓库 README/AGENTS.md 明确将 Claude Code 列为目标 agent，
npx skills add可一键安装 - Codex：未验证——官方材料未逐一列出 Codex 支持情况；技能遵循开放的 agentskills.io / SKILL.md 规范，安装器声称“自动检测已安装 agent”，理论上具备通用性，但未见官方或可靠第三方专门验证
- OpenClaw：未验证——官方材料未提及
- Hermes Agent：未验证——官方材料未提及
（仅基于已抓取材料判断，未为兼容性单独发起搜索）
5. 推荐理由
chdb-sql 是 ClickHouse 官方团队出品的技能，把“我只是想快速对一个文件跑 SQL”这类高频却总要为它搭建数据库服务的麻烦事，简化成一条 pip install chdb 加自然语言描述即可完成的操作；文档、可运行示例与验证脚本齐全，对初中级用户上手成本很低。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | 技能所属合集仓库规模不大（492★），不能代表本技能热度；但其封装的底层引擎 chdb-io/chdb 是独立仓库，2,838★/126 forks，属 1k–5k 星区间，且在 Hacker News 上有多轮独立技术讨论（见第 8 章），官方 ClickHouse 背书；技能本身作为合集内单条目，尚未见到专门针对它自身的独立社区讨论，故不评更高 |
| 可用性 | 9 | npx skills add 或 clickhousectl skills 一条命令安装；SKILL.md + API 参考 + 9 个可运行示例 + 安装验证脚本，文档完整；2026-05-26 有最近提交，维护活跃；仅需 pip install chdb，无付费依赖 |
| 安全性 | 8 | 见下方检查清单 |
安全检查清单：
① 执行 shell 命令——通过 Python 调用 chdb 库在本地进程内执行查询，不新开外部 shell，执行范围明确
② 联网外发数据——默认查询本地文件不联网；仅当用户显式调用 s3()/mysql()/postgresql()/remoteSecure() 等 table function 时才会连接用户指定的外部数据源，行为透明可审计
③ API key/凭据——技能本身不代管、不硬编码任何密钥；若查询远程数据源，连接凭据由用户在查询语句中自行提供
④ 未发现可疑指令——抓取仓库页面与 SKILL.md 原文，未见要求执行技能描述之外操作的可疑指令
⑤ 作者信誉——ClickHouse 官方仓库出品，仓库另附 AI_POLICY.md 说明 AI 生成代码的审查规范，工程严谨度高
⑥ License——Apache-2.0，明确开源
⑦ 维护时间——2026-04-14 引入、2026-05-26 有更新，近 3 个月内活跃
综合评分：8.0（三项均值）
7. 跟同类 Skills 相比的优势
| 项目 | 定位 | 与 chdb-sql 的差异 |
|---|---|---|
| chdb-datastore（同仓库姊妹技能） | 面向 pandas 风格 DataFrame 链式操作的 chdb API | chdb-sql 走原生 SQL 语法，适合已经会写 SQL、想直接表达复杂查询逻辑的用户；两者是同一引擎的两种交互方式 |
| mongodb-natural-language-querying（MongoDB 官方） | 用自然语言直接生成 MongoDB 查询/聚合管道，无需写查询语法，依赖 MongoDB MCP server | 只覆盖 MongoDB 一种文档型数据库；chdb-sql 面向文件与多种关系型/云存储数据源，两者数据模型与目标用户群不同 |
| mongodb-query-optimizer（MongoDB 官方） | 针对已有 MongoDB 查询给优化与索引建议 | 解决的是“优化已有查询”而非“从零执行分析查询”；chdb-sql 是查询执行引擎本身 |
| business-analytics（wshobson/agents 插件） | KPI 仪表盘设计与数据叙事方法论指导 | 偏 business intelligence 的规划性建议，不提供具体的查询执行能力；chdb-sql 是可直接跑起来的 SQL 引擎 |
| data-engineering（wshobson/agents 插件） | ETL 管道搭建、数据仓库设计模式指导 | 同样是方法论/最佳实践类指导内容，不内置查询执行引擎；chdb-sql 可直接对文件/远程源跑分析查询 |
chdb-sql 的差异化在于“零服务器即席分析”：不需要先决定数据仓库架构，也不需要先写 ETL 把数据搬进某个数据库，直接对现有文件或多个异构数据源用标准 SQL 分析，是同类技能中门槛最低的一个。
8. 用户评价
chdb-sql 这一具体技能包发布时间较新，第三方平台尚无针对该技能包本身的具名评价。其封装的底层 chDB 引擎在 Hacker News 上有过独立技术讨论：用户 qxip（chDB 维护团队背景）介绍该引擎继承了 ClickHouse 的稳定性、支持 70+ 数据格式且无需部署服务端/客户端，适合“进程内与无服务器场景下的快速 OLAP 执行”；用户 nasretdinov 评价 chDB 是切入 ClickHouse 生态的低门槛入口，后续若数据规模增长，可以直接把表挂载到正式 ClickHouse 实例上继续使用，不需要经历繁琐的数据迁移。
9. 其他补充
chDB 引擎支持 70+ 种数据格式读写；SKILL.md 明确标注与姊妹技能 chdb-datastore 的路由边界，避免 agent 在两者之间选错。
10. 安装使用方式
- Agent Skills CLI：
npx skills add clickhouse/agent-skills（安装整个官方合集，含 chdb-sql） - ClickHouse 官方 CLI：
clickhousectl skills - 手动安装：将仓库
skills/chdb-sql目录复制到对应 agent 的技能目录 - 运行依赖：
pip install chdb（建议 Python 3.9+）
安装后注意事项：安装后无需重启，agent 会在对话涉及“对 Parquet/CSV 文件跑 SQL”“调用 chdb.query()”“跨源 JOIN”等场景时自动触发该技能；若只需要 pandas 风格 API，应改用同仓库的 chdb-datastore 技能而非本技能。
11. 注意事项
- 仅支持 Python 环境，不提供 Node.js 等其他语言的原生绑定
- 跨源联表功能（
mysql()/postgresql()/remoteSecure()等 table function）依赖网络连接与目标数据源自身的权限配置，用户需自行确保连接凭据安全，技能本身不做凭据托管 - Codex、OpenClaw、Hermes Agent 平台下的官方支持程度均未经证实，建议使用前自行验证基本安装与触发流程
- 与同仓库 chdb-datastore 技能功能边界明确但存在相邻关系，选错技能可能导致 agent 用不擅长的接口方式完成任务，建议提前阅读两者 SKILL.md 的路由说明