README-zh.md

📢 chDB joins the ClickHouse family 🐍+🚀

chDB

English

chDB 是一个由 ClickHouse 驱动的嵌入式 SQL OLAP 引擎。更多细节：chDB: ClickHouse as a Function

特点

• 嵌入在 Python 中的 SQL OLAP 引擎，由 ClickHouse 驱动
• 不需要安装 ClickHouse
• 支持 Parquet、CSV、JSON、Arrow、ORC 和其他 60 多种格式的输入输出，示例。
• 支持 Python DB API 2.0 标准, example

架构

安装方式

目前，chDB 只支持在 macOS（x86_64 和 ARM64）和 Linux 上的 Python 3.8+。

pip install chdb

用法

在命令行中运行

python3 -m chdb SQL [OutputFormat]

python3 -m chdb "SELECT 1,'abc'" Pretty

有三种使用 chdb 的方法：“原始文件查询（性能）”、“高级查询（推荐）”和“DB-API”：

🗂️ 原始文件查询

（Parquet、CSV、JSON、Arrow、ORC 等 60 多种格式）

您可以执行 SQL 并返回所需格式的数据。

import chdb
res = chdb.query('select version()', 'Pretty'); print(res)

使用 Parquet 或 CSV

# 查看更多数据类型格式，请参见 tests/format_output.py
res = chdb.query('select * from file("data.parquet", Parquet)', 'JSON'); print(res)
res = chdb.query('select * from file("data.csv", CSV)', 'CSV');  print(res)
print(f"SQL read {res.rows_read()} rows, {res.bytes_read()} bytes, elapsed {res.elapsed()} seconds")

Pandas DataFrame 输出

# 更多内容请参见 https://clickhouse.com/docs/en/interfaces/formats
chdb.query('select * from file("data.parquet", Parquet)', 'Dataframe')

🗂️ 高级查询

（Pandas DataFrame、Parquet 文件/字节、Arrow 文件/字节）

查询 Pandas DataFrame

import chdb.dataframe as cdf
import pandas as pd
# Join 2 DataFrames
df1 = pd.DataFrame({'a': [1, 2, 3], 'b': ["one", "two", "three"]})
df2 = pd.DataFrame({'c': [1, 2, 3], 'd': ["①", "②", "③"]})
ret_tbl = cdf.query(sql="select * from __tbl1__ t1 join __tbl2__ t2 on t1.a = t2.c",
                  tbl1=df1, tbl2=df2)
print(ret_tbl)
# Query on the DataFrame Table
print(ret_tbl.query('select b, sum(a) from __table__ group by b'))

🗂️ 基于有状态会话 Session 查询

from chdb import session as chs

## 在临时会话中创建DB, Table, View，当会话被删除时自动清除。
sess = chs.Session()
sess.query("CREATE DATABASE IF NOT EXISTS db_xxx ENGINE = Atomic")
sess.query("CREATE TABLE IF NOT EXISTS db_xxx.log_table_xxx (x String, y Int) ENGINE = Log;")
sess.query("INSERT INTO db_xxx.log_table_xxx VALUES ('a', 1), ('b', 3), ('c', 2), ('d', 5);")
sess.query(
    "CREATE VIEW db_xxx.view_xxx AS SELECT * FROM db_xxx.log_table_xxx LIMIT 4;"
)
print("Select from view:\n")
print(sess.query("SELECT * FROM db_xxx.view_xxx", "Pretty"))

参见: test_stateful.py

🗂️ Python DB-API 2.0

import chdb.dbapi as dbapi
print("chdb driver version: {0}".format(dbapi.get_client_info()))

conn1 = dbapi.connect()
cur1 = conn1.cursor()
cur1.execute('select version()')
print("description: ", cur1.description)
print("data: ", cur1.fetchone())
cur1.close()
conn1.close()

🗂️ Query with UDF(User Defined Functions)

from chdb.udf import chdb_udf
from chdb import query

@chdb_udf()
def sum_udf(lhs, rhs):
    return int(lhs) + int(rhs)

print(query("select sum_udf(12,22)"))

参见: test_udf.py.

更多示例，请参见 examples 和 tests。

演示和示例

• Colab Notebook 和更多 示例

基准测试

• ClickBench of embedded engines

• chDB vs Pandas

• Benchmark on DataFrame: chDB Pandas DuckDB Polars

文档

• 关于 SQL 语法，请参考 ClickHouse SQL 参考

贡献

贡献是使开源社区成为一个学习、激励和创造的绝佳场所的原因。您做出的任何贡献都将受到高度赞赏。 以下是您可以提供帮助的事项：

• 「Star」和「分享」
• 帮助测试和报告错误
• 帮助改进文档
• 帮助提高代码质量和性能

事件

• Demo chDB at ClickHouse v23.7 livehouse! and Slides

相关论文

• ClickHouse - Lightning Fast Analytics for Everyone

版权信息

Apache 2.0，请查看 LICENSE 获取更多信息。

鸣谢

chDB 主要基于 ClickHouse。由于商标和其他原因，我将其命名为 chDB。

联系方式

• 知乎: @auxten
• Discord：https://discord.gg/D2Daa2fM5K
• 电子邮件：[email protected]
• Twitter：@chdb