跳转到主要内容
在本指南中,我们将快速上手 chDB 的 Python 版本。 我们将先查询 S3 上的一个 JSON 文件,然后基于该 JSON 文件在 chDB 中创建一个表,并对其中的数据执行一些查询。 我们还会了解如何让查询以不同格式返回数据,包括 Apache Arrow 和 Pandas,最后学习如何查询 Pandas DataFrame。

准备

先创建一个虚拟环境:
现在安装 chDB。 请确保使用的是 2.0.3 或更高版本:
现在我们来安装 ipython
接下来我们将使用 ipython 运行本指南其余部分中的命令,你可以通过运行以下命令来启动它:
本指南还会用到 Pandas 和 Apache Arrow,因此也请一并安装这些库:

查询 S3 中的 JSON 文件

下面我们来看看如何查询存储在 S3 bucket 中的 JSON 文件。 YouTube dislikes 数据集包含截至 2021 年 YouTube 视频上超过 40 亿行的点踩数据。 我们将使用该数据集中的一个 JSON 文件。 导入 chdb:
我们可以使用以下查询来查看其中一个 JSON 文件的结构:
我们还可以统计该文件中的行数:
这个文件包含 30 多万条记录。 chdb 目前还不支持传入查询参数,但我们可以先提取出路径,再通过 f-String 传入。
对程序中定义的变量这样做没有问题,但不要对用户提供的输入这样做,否则你的查询就会存在 SQL 注入风险。

配置输出格式

默认输出格式为 CSV,但我们可以通过 output_format 参数进行更改。 chDB 支持 ClickHouse 的数据格式,也支持一些自身的格式,其中包括 DataFrame,它会返回一个 Pandas DataFrame:
或者,如果要返回一个 Apache Arrow 表:

从 JSON 文件创建表

接下来,我们来看看如何在 chDB 中创建表。 为此需要使用另一个 API,因此先将其导入:
接下来,我们将初始化一个会话。 如果希望将该会话持久化到磁盘,需要提供一个目录名。 如果留空,database 将保存在内存中,并会在 Python 进程终止后立即丢失。
接下来,创建一个数据库:
现在我们可以根据 JSON 文件 中的 schema,使用 CREATE...EMPTY AS 方法创建一个 dislikes 表。 我们将使用 schema_inference_make_columns_nullable 设置,这样列类型就不会全部变为 Nullable
然后,我们可以使用 DESCRIBE 子句来查看 schema:
接下来,向该表插入数据:
我们也可以用 CREATE...AS 的方式一步完成这两个步骤。 我们来用这种方式创建另一个表:

查询表

最后,来查询一下这张表:
假设接下来我们在 DataFrame 中再添加一列,用来计算 likes 与 dislikes 的比值。 我们可以编写如下代码:

查询 Pandas DataFrame

然后,我们可以在 chDB 中查询该 DataFrame:
你也可以在查询 Pandas DataFrame 开发者指南中进一步了解如何查询 Pandas DataFrame。

后续步骤

希望本指南能帮助你对 chDB 有一个较好的整体了解。 如需进一步了解其使用方法,请参阅以下开发者指南:
最后修改于 2026年7月3日