> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# chDB 入门

> chDB 是一个由 ClickHouse 提供支持的进程内 SQL OLAP 引擎

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

<div id="setup">
  ## 准备
</div>

先创建一个虚拟环境：

```bash theme={null}
python -m venv .venv
source .venv/bin/activate
```

现在安装 chDB。
请确保使用的是 2.0.3 或更高版本：

```bash theme={null}
pip install "chdb>=2.0.2"
```

现在我们来安装 [ipython](https://ipython.org/)：

```bash theme={null}
pip install ipython
```

接下来我们将使用 `ipython` 运行本指南其余部分中的命令，你可以通过运行以下命令来启动它：

```bash theme={null}
ipython
```

本指南还会用到 Pandas 和 Apache Arrow，因此也请一并安装这些库：

```bash theme={null}
pip install pandas pyarrow
```

<div id="querying-a-json-file-in-s3">
  ## 查询 S3 中的 JSON 文件
</div>

下面我们来看看如何查询存储在 S3 bucket 中的 JSON 文件。
[YouTube dislikes 数据集](/zh/get-started/sample-datasets/youtube-dislikes)包含截至 2021 年 YouTube 视频上超过 40 亿行的点踩数据。
我们将使用该数据集中的一个 JSON 文件。

导入 chdb：

```python theme={null}
import chdb
```

我们可以使用以下查询来查看其中一个 JSON 文件的结构：

```python theme={null}
chdb.query(
  """
  DESCRIBE s3(
    's3://clickhouse-public-datasets/youtube/original/files/' ||
    'youtubedislikes_20211127161229_18654868.1637897329_vid.json.zst',
    'JSONLines'
  )
  SETTINGS describe_compact_output=1
  """
)
```

```text theme={null}
"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)"
```

我们还可以统计该文件中的行数：

```python theme={null}
chdb.query(
  """
  SELECT count()
  FROM s3(
    's3://clickhouse-public-datasets/youtube/original/files/' ||
    'youtubedislikes_20211127161229_18654868.1637897329_vid.json.zst',
    'JSONLines'
  )"""
)
```

```text theme={null}
336432
```

这个文件包含 30 多万条记录。

chdb 目前还不支持传入查询参数，但我们可以先提取出路径，再通过 f-String 传入。

```python theme={null}
path = 's3://clickhouse-public-datasets/youtube/original/files/youtubedislikes_20211127161229_18654868.1637897329_vid.json.zst'
```

```python theme={null}
chdb.query(
  f"""
  SELECT count()
  FROM s3('{path}','JSONLines')
  """
)
```

<Warning>
  对程序中定义的变量这样做没有问题，但不要对用户提供的输入这样做，否则你的查询就会存在 SQL 注入风险。
</Warning>

<div id="configuring-the-output-format">
  ## 配置输出格式
</div>

默认输出格式为 `CSV`，但我们可以通过 `output_format` 参数进行更改。
chDB 支持 ClickHouse 的数据格式，也支持[一些自身的格式](/zh/products/chdb/reference/data-formats)，其中包括 `DataFrame`，它会返回一个 Pandas DataFrame：

```python theme={null}
result = chdb.query(
  f"""
  SELECT is_ads_enabled, count()
  FROM s3('{path}','JSONLines')
  GROUP BY ALL
  """,
  output_format="DataFrame"
)

print(type(result))
print(result)
```

```text theme={null}
<class 'pandas.core.frame.DataFrame'>
   is_ads_enabled  count()
0           False   301125
1            True    35307
```

或者，如果要返回一个 Apache Arrow 表：

```python theme={null}
result = chdb.query(
  f"""
  SELECT is_live_content, count()
  FROM s3('{path}','JSONLines')
  GROUP BY ALL
  """,
  output_format="ArrowTable"
)

print(type(result))
print(result)
```

```text theme={null}
<class 'pyarrow.lib.Table'>
pyarrow.Table
is_live_content: bool
count(): uint64 not null
----
is_live_content: [[false,true]]
count(): [[315746,20686]]
```

<div id="creating-a-table-from-json-file">
  ## 从 JSON 文件创建表
</div>

接下来，我们来看看如何在 chDB 中创建表。
为此需要使用另一个 API，因此先将其导入：

```python theme={null}
from chdb import session as chs
```

接下来，我们将初始化一个会话。
如果希望将该会话持久化到磁盘，需要提供一个目录名。
如果留空，database 将保存在内存中，并会在 Python 进程终止后立即丢失。

```python theme={null}
sess = chs.Session("gettingStarted.chdb")
```

接下来，创建一个数据库：

```python theme={null}
sess.query("CREATE DATABASE IF NOT EXISTS youtube")
```

现在我们可以根据 JSON 文件 中的 schema，使用 `CREATE...EMPTY AS` 方法创建一个 `dislikes` 表。
我们将使用 [`schema_inference_make_columns_nullable`](/zh/reference/settings/formats#schema_inference_make_columns_nullable) 设置，这样列类型就不会全部变为 `Nullable`。

```python theme={null}
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：

```python theme={null}
sess.query(f"""
   DESCRIBE youtube.dislikes
   SETTINGS describe_compact_output=1
   """
)
```

```text theme={null}
"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"
```

接下来，向该表插入数据：

```python theme={null}
sess.query(f"""
  INSERT INTO youtube.dislikes
  SELECT * 
  FROM s3('{path}','JSONLines')
  SETTINGS schema_inference_make_columns_nullable=0
  """
)
```

我们也可以用 `CREATE...AS` 的方式一步完成这两个步骤。
我们来用这种方式创建另一个表：

```python theme={null}
sess.query(f"""
  CREATE TABLE youtube.dislikes2
  ORDER BY fetch_date 
  AS 
  SELECT * 
  FROM s3('{path}','JSONLines')
  SETTINGS schema_inference_make_columns_nullable=0
  """
)
```

<div id="querying-a-table">
  ## 查询表
</div>

最后，来查询一下这张表：

```sql theme={null}
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
```

```text theme={null}
                             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 中再添加一列，用来计算 likes 与 dislikes 的比值。
我们可以编写如下代码：

```python theme={null}
df["likeDislikeRatio"] = df["likeCount"] / df["dislikeCount"]
```

<div id="querying-a-pandas-dataframe">
  ## 查询 Pandas DataFrame
</div>

然后，我们可以在 chDB 中查询该 DataFrame：

```python theme={null}
chdb.query(
  """
  SELECT uploader, likeDislikeRatio
  FROM Python(df)
  """,
  output_format="DataFrame"
)
```

```text theme={null}
                             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 开发者指南](/zh/products/chdb/guides/querying-pandas)中进一步了解如何查询 Pandas DataFrame。

<div id="next-steps">
  ## 后续步骤
</div>

希望本指南能帮助你对 chDB 有一个较好的整体了解。
如需进一步了解其使用方法，请参阅以下开发者指南：

* [查询 Pandas DataFrame](/zh/products/chdb/guides/querying-pandas)
* [查询 Apache Arrow](/zh/products/chdb/guides/querying-apache-arrow)
* [在 JupySQL 中使用 chDB](/zh/products/chdb/guides/jupysql)
* [将 chDB 与现有的 clickhouse-local 数据库配合使用](/zh/products/chdb/guides/clickhouse-local)