Set up docs MCP在本指南中，我们将快速上手 chDB 的 Python 版本。 我们将先查询 S3 上的一个 JSON 文件，然后基于该 JSON 文件在 chDB 中创建一张表，并对其中的数据执行一些查询。 我们还会了解如何让查询以不同格式返回数据，包括 Apache Arrow 和 Panda，最后学习如何查询 Pandas DataFrame。
准备
首先，创建一个虚拟环境：
python -m venv .venv
source .venv/bin/activate现在开始安装 chDB。 请确保版本为 2.0.3 或更高：
pip install "chdb>=2.0.2"现在，我们来安装 ipython：
pip install ipython我们将使用 ipython 运行本指南后续部分中的命令，你可以通过运行以下命令启动它：
ipython本指南中还会用到 Pandas 和 Apache Arrow，因此也请安装这两个库：
pip install pandas pyarrow查询 S3 中的 JSON 文件
现在我们来看一下如何查询存储在 S3 bucket 中的 JSON 文件。 YouTube dislikes 数据集包含截至 2021 年 YouTube 视频上超过 40 亿行点踩记录。 我们将使用该数据集中的一个 JSON 文件。
导入 chdb：
import chdb可以编写以下查询来描述其中一个 JSON 文件的结构：
chdb.query(
"""
DESCRIBE s3(
's3://clickhouse-public-datasets/youtube/original/files/' ||
'youtubedislikes_20211127161229_18654868.1637897329_vid.json.zst',
'JSONLines'
)
SETTINGS describe_compact_output=1
"""
)"id","Nullable(String)"
"fetch_date","Nullable(String)"
"upload_date","Nullable(String)"
"title","Nullable(String)"
"uploader_id","Nullable(String)"
"uploader","Nullable(String)"
"uploader_sub_count","Nullable(Int64)"
"is_age_limit","Nullable(Bool)"
"view_count","Nullable(Int64)"
"like_count","Nullable(Int64)"
"dislike_count","Nullable(Int64)"
"is_crawlable","Nullable(Bool)"
"is_live_content","Nullable(Bool)"
"has_subtitles","Nullable(Bool)"
"is_ads_enabled","Nullable(Bool)"
"is_comments_enabled","Nullable(Bool)"
"description","Nullable(String)"
"rich_metadata","Array(Tuple(
call Nullable(String),
content Nullable(String),
subtitle Nullable(String),
title Nullable(String),
url Nullable(String)))"
"super_titles","Array(Tuple(
text Nullable(String),
url Nullable(String)))"
"uploader_badges","Nullable(String)"
"video_badges","Nullable(String)"我们还可以统计该文件中的行数：
chdb.query(
"""
SELECT count()
FROM s3(
's3://clickhouse-public-datasets/youtube/original/files/' ||
'youtubedislikes_20211127161229_18654868.1637897329_vid.json.zst',
'JSONLines'
)"""
)336432这个文件包含 30 多万条记录。
chdb 目前还不支持传入查询参数，但我们可以把 path 提取出来，并通过 f-String 传入。
path = 's3://clickhouse-public-datasets/youtube/original/files/youtubedislikes_20211127161229_18654868.1637897329_vid.json.zst'chdb.query(
f"""
SELECT count()
FROM s3('{path}','JSONLines')
"""
)配置输出格式
默认的输出格式是 CSV，但我们可以通过 output_format 参数来更改。
chDB 支持 ClickHouse 的数据格式，也支持一些自身的格式，其中包括 DataFrame；它会返回一个 Pandas DataFrame：
result = chdb.query(
f"""
SELECT is_ads_enabled, count()
FROM s3('{path}','JSONLines')
GROUP BY ALL
""",
output_format="DataFrame"
)
print(type(result))
print(result)<class 'pandas.core.frame.DataFrame'>
is_ads_enabled count()
0 False 301125
1 True 35307或者，如果我们想返回一个 Apache Arrow 表：
result = chdb.query(
f"""
SELECT is_live_content, count()
FROM s3('{path}','JSONLines')
GROUP BY ALL
""",
output_format="ArrowTable"
)
print(type(result))
print(result)<class 'pyarrow.lib.Table'>
pyarrow.Table
is_live_content: bool
count(): uint64 not null
----
is_live_content: [[false,true]]
count(): [[315746,20686]]从 JSON 文件创建表
接下来，我们来看看如何在 chDB 中创建表。 为此需要使用不同的 API，所以先导入它：
from chdb import session as chs接下来，我们将初始化一个会话。 如果希望将该会话持久化到磁盘，就需要提供一个目录名。 如果留空，该会话将是临时的：chDB 会将其数据保存在磁盘上的临时目录中，并在会话关闭时删除，因此数据不会持久化。
sess = chs.Session("gettingStarted.chdb")接下来，我们来创建一个 database：
sess.query("CREATE DATABASE IF NOT EXISTS youtube")现在我们可以根据 JSON 文件 中的 schema，使用 CREATE...EMPTY AS 方法创建一个 dislikes 表。
我们将使用 schema_inference_make_columns_nullable 设置，这样列类型就不会全部被设为 Nullable。
sess.query(f"""
CREATE TABLE youtube.dislikes
ORDER BY fetch_date
EMPTY AS
SELECT *
FROM s3('{path}','JSONLines')
SETTINGS schema_inference_make_columns_nullable=0
"""
)然后，我们可以使用 DESCRIBE 子句来查看 schema：
sess.query(f"""
DESCRIBE youtube.dislikes
SETTINGS describe_compact_output=1
"""
)"id","String"
"fetch_date","String"
"upload_date","String"
"title","String"
"uploader_id","String"
"uploader","String"
"uploader_sub_count","Int64"
"is_age_limit","Bool"
"view_count","Int64"
"like_count","Int64"
"dislike_count","Int64"
"is_crawlable","Bool"
"is_live_content","Bool"
"has_subtitles","Bool"
"is_ads_enabled","Bool"
"is_comments_enabled","Bool"
"description","String"
"rich_metadata","Array(Tuple(
call String,
content String,
subtitle String,
title String,
url String))"
"super_titles","Array(Tuple(
text String,
url String))"
"uploader_badges","String"
"video_badges","String"接下来，向该表插入数据：
sess.query(f"""
INSERT INTO youtube.dislikes
SELECT *
FROM s3('{path}','JSONLines')
SETTINGS schema_inference_make_columns_nullable=0
"""
)我们也可以使用 CREATE...AS 方法，一步完成这两个步骤。
下面用这种方法创建一个不同的表：
sess.query(f"""
CREATE TABLE youtube.dislikes2
ORDER BY fetch_date
AS
SELECT *
FROM s3('{path}','JSONLines')
SETTINGS schema_inference_make_columns_nullable=0
"""
)查询表
最后，我们来查询一下这张表：
df = sess.query("""
SELECT uploader, sum(view_count) AS viewCount, sum(like_count) AS likeCount, sum(dislike_count) AS dislikeCount
FROM youtube.dislikes
GROUP BY ALL
ORDER BY viewCount DESC
LIMIT 10
""",
"DataFrame"
)
df uploader viewCount likeCount dislikeCount
0 Jeremih 139066569 812602 37842
1 TheKillersMusic 109313116 529361 11931
2 LetsGoMartin- Canciones Infantiles 104747788 236615 141467
3 Xiaoying Cuisine 54458335 1031525 37049
4 Adri 47404537 279033 36583
5 Diana and Roma IND 43829341 182334 148740
6 ChuChuTV Tamil 39244854 244614 213772
7 Cheez-It 35342270 108 27
8 Anime Uz 33375618 1270673 60013
9 RC Cars OFF Road 31952962 101503 49489假设我们接着在 DataFrame 中新增一列，用于计算点赞与点踩的比率。 我们可以编写如下代码：
df["likeDislikeRatio"] = df["likeCount"] / df["dislikeCount"]查询 Pandas DataFrame
然后，我们就可以通过 chDB 查询该 DataFrame：
chdb.query(
"""
SELECT uploader, likeDislikeRatio
FROM Python(df)
""",
output_format="DataFrame"
) uploader likeDislikeRatio
0 Jeremih 21.473548
1 TheKillersMusic 44.368536
2 LetsGoMartin- Canciones Infantiles 1.672581
3 Xiaoying Cuisine 27.842182
4 Adri 7.627395
5 Diana and Roma IND 1.225857
6 ChuChuTV Tamil 1.144275
7 Cheez-It 4.000000
8 Anime Uz 21.173296
9 RC Cars OFF Road 2.051021你还可以在查询 Pandas DataFrame 开发者指南中进一步了解如何查询 Pandas DataFrame。
后续步骤
希望通过本指南，你已经对 chDB 有了较为全面的了解。 如需进一步了解其使用方法，请参阅以下开发者指南：