Index of every page on this site: llms.txt
All skills
clickhouse avatar

/chdb-sql

@1008fd7 official
by clickhouseclickhouse/agent-skills573 stars
37
Run it yourself

Use when the user wants to run SQL — especially analytical SQL — on local files (parquet/csv/json), URLs, S3 paths, or remote databases (Postgres, MySQL, MongoDB, ClickHouse Cloud, Iceberg, Delta Lake) without setting up a server. Provides chDB — embedded ClickHouse SQL in Python with 1000+ functions, Session for stateful multi-step pipelines, parametrized queries, and cross-source joins via `s3()`, `mysql()`, `postgresql()`, `iceberg()`, `deltaLake()`, `remoteSecure()` table functions. TRIGGER when: user wants SQL on parquet/csv/files or across remote analytical sources; uses ClickHouse SQL features (window functions, windowFunnel, geoToH3, JSON path ops, Session, parametrized queries); imports `chdb` or calls `chdb.query()`. SKIP this skill for pandas-style DataFrame method-chaining (use chdb-datastore instead) or ClickHouse server administration.

  • 8 files
  • 40 KB
  • Apache-2
  • Updated 6 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/clickhouse/agent-skills/chdb-sql

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈219 tokens for metadata: the name and description. ≈967 when used: this file. ≈8.3k more on demand in 6 files.

Description uses 10.9% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈872 characters, or 10.9%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

chdb SQL — ClickHouse in Your Python Process

Run ClickHouse SQL directly in Python — no server needed. Query local files, remote databases, and cloud storage with full ClickHouse SQL power.

pip install chdb

Decision Tree: Pick the Right API

1. One-off query on files or databases → chdb.query()
2. Multi-step analysis with tables      → Session
3. DB-API 2.0 connection                → chdb.connect()
4. Pandas-style DataFrame operations    → Use chdb-datastore skill instead

chdb.query() — One Line, Any Data

import chdb

chdb.query("SELECT * FROM file('data.parquet', Parquet) WHERE price > 100 LIMIT 10")       # local files
chdb.query("SELECT * FROM mysql('db:3306', 'shop', 'orders', 'root', 'pass')")              # databases
chdb.query("SELECT * FROM s3('s3://bucket/data.parquet', NOSIGN) LIMIT 10")                 # cloud storage
chdb.query("SELECT * FROM deltaLake('s3://bucket/delta/table', NOSIGN) LIMIT 10")           # data lakes

# Cross-source join
chdb.query("""
    SELECT u.name, o.amount FROM mysql('db:3306', 'crm', 'users', 'root', 'pass') AS u
    JOIN file('orders.parquet', Parquet) AS o ON u.id = o.user_id ORDER BY o.amount DESC
""")

data = {"name": ["Alice", "Bob"], "score": [95, 87]}
chdb.query("SELECT * FROM Python(data) ORDER BY score DESC")                                # Python data
df = chdb.query("SELECT * FROM numbers(10)", "DataFrame")                                   # output formats
chdb.query("SELECT toDate({d:String}) + number FROM numbers({n:UInt64})",
    "DataFrame", params={"d": "2025-01-01", "n": 30})                                      # parametrized

Table functions → table-functions.md | SQL functions → sql-functions.md | Full API → api-reference.md

Session — Stateful Analysis Pipelines

from chdb import session as chs
sess = chs.Session("./analytics_db")   # persistent; Session() for in-memory

sess.query("CREATE TABLE users ENGINE=MergeTree() ORDER BY id AS SELECT * FROM mysql('db:3306','crm','users','root','pass')")
sess.query("CREATE TABLE events ENGINE=MergeTree() ORDER BY (ts,user_id) AS SELECT * FROM s3('s3://logs/events/*.parquet',NOSIGN)")
sess.query("""
    SELECT u.country, count() AS cnt, uniqExact(e.user_id) AS users
    FROM events e JOIN users u ON e.user_id = u.id
    WHERE e.ts >= today() - 7 GROUP BY u.country ORDER BY cnt DESC
""", "Pretty").show()
sess.close()

Connection API (DB-API 2.0)

from chdb import dbapi
conn = dbapi.connect()
cur = conn.cursor()
cur.execute("SELECT * FROM file('data.parquet', Parquet) WHERE value > 100")
print(cur.fetchall())
cur.close()
conn.close()

Troubleshooting

Problem Fix
ImportError: No module named 'chdb' pip install chdb
DB::Exception: FILE_NOT_FOUND Check file path; use absolute path or verify cwd
DB::Exception: Unknown table function Check function name spelling (e.g., deltaLake not deltalake)
Connection refused to remote DB Check host:port format; ensure remote DB allows connections
Environment check Run python scripts/verify_install.py (from skill directory)

References

Note: This skill teaches how to use chdb SQL. For pandas-style operations, use the chdb-datastore skill. For contributing to chdb source code, see CLAUDE.md in the project root.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 1008fd7. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 22 minutes ago.

Activeupdated 6 months ago
compatibility
Requires Python 3.9+, macOS or Linux. pip install chdb.
Other metadata
metadata
{
  "author": "chdb-io",
  "version": "4.1",
  "homepage": "https://clickhouse.com/docs/chdb"
}
  • Python
  • clickhouse
  • chdb
  • sql
  • analytics
  • parquet
  • csv
  • s3
  • postgres
  • mysql
  • mongodb
  • data-lakes

README badge

README badge for clickhouse/agent-skills/chdb-sql

Runs ClickHouse SQL directly in Python against local files (parquet, CSV, JSON), remote databases (Postgres, MySQL, MongoDB, ClickHouse Cloud), and data lakes (Iceberg, Delta Lake) without a server. Use for analytical queries with window functions, cross-source joins, and parametrized statements via chdb.query() or Session for stateful pipelines.

Generated from the current SKILL.md.

Does chdb require a running ClickHouse server?
No. chdb is embedded ClickHouse SQL that runs directly in your Python process without needing a server.
What remote data sources can I query?
Postgres, MySQL, MongoDB, ClickHouse Cloud, Iceberg, Delta Lake, S3, and local files (parquet, CSV, JSON).
Can I join data across different sources in a single query?
Yes. You can use table functions like `mysql()`, `postgresql()`, `s3()`, and `deltaLake()` together in cross-source JOINs.
What Python versions does this support?
Python 3.9 and later on macOS or Linux.
Does this work for pandas-style DataFrame operations?
No. For method-chaining DataFrame workflows, use the chdb-datastore skill instead.

Generated from the current SKILL.md. These answers refresh after source changes.