AI Skills
chdb-sql

chdb-sql

熱門

當使用者想要在本機檔案（parquet/csv/json）、URL、S3 路徑或遠端資料庫（Postgres、MySQL、MongoDB、ClickHouse Cloud、Iceberg、Delta Lake）上執行 SQL（尤其是分析型 SQL），而無需設定伺服器時使用。提供 chDB — 內嵌於 Python 的 ClickHouse SQL，具備 1000+ 函式、支援有狀態多步驟管線的 Session、參數化查詢，以及透過 `s3()`、`mysql()`、`postgresql()`、`iceberg()`、`deltaLake()`、`remoteSecure()` 表格函式進行跨來源 JOIN。觸發時機：使用者想要對 parquet/csv/檔案或跨遠端分析來源執行 SQL；使用 ClickHouse SQL 功能（視窗函式、windowFunnel、geoToH3、JSON 路徑操作、Session、參數化查詢）；匯入 `chdb` 或呼叫 `chdb.query()`。跳過此技能：用於 pandas 風格的 DataFrame 方法鏈（請改用 chdb-datastore）或 ClickHouse 伺服器管理。

495星標
32分支
更新於 2026/7/15
獲取技能源代碼

相關技能

uncloud24萬prisma-patterns24萬vercel-composition-patterns11萬
SKILL.md
唯讀
名稱
chdb-sql
描述

當使用者想要在本機檔案（parquet/csv/json）、URL、S3 路徑或遠端資料庫（Postgres、MySQL、MongoDB、ClickHouse Cloud、Iceberg、Delta Lake）上執行 SQL（尤其是分析型 SQL），而無需設定伺服器時使用。提供 chDB — 內嵌於 Python 的 ClickHouse SQL，具備 1000+ 函式、支援有狀態多步驟管線的 Session、參數化查詢，以及透過 `s3()`、`mysql()`、`postgresql()`、`iceberg()`、`deltaLake()`、`remoteSecure()` 表格函式進行跨來源 JOIN。觸發時機：使用者想要對 parquet/csv/檔案或跨遠端分析來源執行 SQL；使用 ClickHouse SQL 功能（視窗函式、windowFunnel、geoToH3、JSON 路徑操作、Session、參數化查詢）；匯入 `chdb` 或呼叫 `chdb.query()`。跳過此技能：用於 pandas 風格的 DataFrame 方法鏈（請改用 chdb-datastore）或 ClickHouse 伺服器管理。

chdb SQL — 在你的 Python 程序中的 ClickHouse

直接在 Python 中執行 ClickHouse SQL — 無需伺服器。查詢本機檔案、遠端資料庫和雲端儲存，享有完整的 ClickHouse SQL 功能。

pip install chdb

決策樹：選擇正確的 API

1. 一次性查詢檔案或資料庫 → chdb.query()
2. 多步驟分析並建立表格 → Session
3. DB-API 2.0 連線 → chdb.connect()
4. Pandas 風格的 DataFrame 操作 → 改用 chdb-datastore 技能

chdb.query() — 一行程式碼，任意資料

import chdb

chdb.query("SELECT * FROM file('data.parquet', Parquet) WHERE price > 100 LIMIT 10")       # 本機檔案
chdb.query("SELECT * FROM mysql('db:3306', 'shop', 'orders', 'root', 'pass')")              # 資料庫
chdb.query("SELECT * FROM s3('s3://bucket/data.parquet', NOSIGN) LIMIT 10")                 # 雲端儲存
chdb.query("SELECT * FROM deltaLake('s3://bucket/delta/table', NOSIGN) LIMIT 10")           # 資料湖

# 跨來源 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 資料
df = chdb.query("SELECT * FROM numbers(10)", "DataFrame")                                   # 輸出格式
chdb.query("SELECT toDate({d:String}) + number FROM numbers({n:UInt64})",
    "DataFrame", params={"d": "2025-01-01", "n": 30})                                      # 參數化查詢

表格函式 → table-functions.md | SQL 函式 → sql-functions.md | 完整 API → api-reference.md

Session — 有狀態的分析管線

from chdb import session as chs
sess = chs.Session("./analytics_db")   # 持久化；Session() 為記憶體模式

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()

連線 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()

疑難排解

問題 解決方法
ImportError: No module named 'chdb' pip install chdb
DB::Exception: FILE_NOT_FOUND 檢查檔案路徑；使用絕對路徑或確認目前工作目錄
DB::Exception: Unknown table function 檢查函式名稱拼寫（例如 deltaLake 而非 deltalake）
無法連線到遠端資料庫 檢查 host:port 格式；確認遠端資料庫允許連線
環境檢查 執行 python scripts/verify_install.py（從技能目錄）

參考資料

注意：此技能教導如何使用 chdb SQL。
如需 pandas 風格的操作，請使用 chdb-datastore 技能。
如需貢獻 chdb 原始碼，請參閱專案根目錄的 CLAUDE.md。