如果需要，DuckDB 的 Python 客户端无需额外配置即可直接在 Jupyter Notebook 中使用。不过，可以使用额外的库来简化 SQL 查询的开发。本指南将介绍如何利用这些额外的库。有关如何将 DuckDB 与 Python 结合使用的更多信息，请参阅 Python 部分的其他指南。

在此示例中，我们使用 JupySQL 包。此示例工作流程也可以通过 Google Colab notebook 获取。

库安装

四个额外的库可以改善 Jupyter Notebook 中的 DuckDB 使用体验。

1. jupysql：将 Jupyter 代码单元格转换为 SQL 单元格
2. Pandas：整洁的表格可视化效果以及与其他分析工具的兼容性
3. matplotlib：使用 Python 进行绘图
4. duckdb-engine (DuckDB SQLAlchemy 驱动)：供 SQLAlchemy 用于连接 DuckDB（可选）

如果尚未安装 Jupyter Notebook，请从命令行运行这些 pip install 命令。否则，请参阅上方提供的 Google Colab 链接以获取 Notebook 内的示例。

pip install duckdb

安装 Jupyter Notebook

pip install notebook

或 JupyterLab

pip install jupyterlab

安装支持库

pip install jupysql pandas matplotlib duckdb-engine

库导入与配置

打开 Jupyter Notebook 并导入相关库。

设置 jupysql 的配置，以便直接将数据输出到 Pandas，并简化打印到 Notebook 的输出内容。

%config SqlMagic.autopandas = True
%config SqlMagic.feedback = False
%config SqlMagic.displaycon = False

原生连接 DuckDB

要连接到 DuckDB，请运行

import duckdb
import pandas as pd

%load_ext sql
conn = duckdb.connect()
%sql conn --alias duckdb

警告：在原生 DuckDB 连接中无法识别 变量。

通过 SQLAlchemy 连接 DuckDB

或者，您可以使用 duckdb_engine 通过 SQLAlchemy 连接到 DuckDB。请参阅 性能和功能差异。

import duckdb
import pandas as pd
# No need to import duckdb_engine
#  jupysql will auto-detect the driver needed based on the connection string!

# Import jupysql Jupyter extension to create SQL cells
%load_ext sql

连接到一个新的 内存中 DuckDB、默认连接 或文件备份数据库

%sql duckdb:///:memory:

%sql duckdb:///:default:

%sql duckdb:///path/to/file.db

如果您提供 duckdb:///:default: 作为 SQLAlchemy 连接字符串，则 %sql 命令和 duckdb.sql 将共享同一个 默认连接。

查询 DuckDB

可以使用行首的 %sql 运行单行 SQL 查询。查询结果将显示为 Pandas DataFrame。

%sql SELECT 'Off and flying!' AS a_duckdb_column;

通过在单元格开头放置 %%sql，可以将整个 Jupyter 单元格用作 SQL 单元格。查询结果将显示为 Pandas DataFrame。

%%sql
SELECT
    schema_name,
    function_name
FROM duckdb_functions()
ORDER BY ALL DESC
LIMIT 5;

要将查询结果存储在 Python 变量中，请使用 << 作为赋值运算符。这可以同时用于 %sql 和 %%sql Jupyter 魔术命令。

%sql res << SELECT 'Off and flying!' AS a_duckdb_column;

如果设置了 %config SqlMagic.autopandas = True 选项，则变量为 Pandas DataFrame；否则，它是一个可以使用 DataFrame() 函数转换为 Pandas 的 ResultSet。

查询 Pandas DataFrames

DuckDB 能够查找并查询 Jupyter Notebook 中存储为变量的任何 DataFrame。

input_df = pd.DataFrame.from_dict({"i": [1, 2, 3],
                                   "j": ["one", "two", "three"]})

被查询的 DataFrame 可以像 FROM 子句中的任何其他表一样进行指定。

%sql output_df << SELECT sum(i) AS total_i FROM input_df;

警告：当使用 SQLAlchemy 连接且 DuckDB 版本 >= 1.1.0 时，请确保运行 %sql SET python_scan_all_frames=true，以使 Pandas DataFrames 可被查询。

可视化 DuckDB 数据

在 Python 中绘制数据集的最常见方法是使用 Pandas 加载它们，然后使用 matplotlib 或 seaborn 进行绘图。这种方法需要将所有数据加载到内存中，效率极低。JupySQL 中的绘图模块在 SQL 引擎中运行计算。这会将内存管理委托给引擎，并确保中间计算不会持续占用内存，从而高效地绘制海量数据集。

箱线图与直方图

要创建箱线图，请调用 %sqlplot boxplot，并传入表名和要绘制的列。在本例中，表名是本地存储的 Parquet 文件的路径。

from urllib.request import urlretrieve

_ = urlretrieve(
    "https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2021-01.parquet",
    "yellow_tripdata_2021-01.parquet",
)

%sqlplot boxplot --table yellow_tripdata_2021-01.parquet --column trip_distance

安装并加载 DuckDB httpfs 扩展

DuckDB 的 httpfs 扩展 允许通过 http 远程查询 Parquet 和 CSV 文件。这些示例查询了一个包含纽约市历史出租车数据的 Parquet 文件。使用 Parquet 格式使 DuckDB 仅能将所需的行和列拉取到内存中，而不是下载整个文件。DuckDB 也可用于处理本地 Parquet 文件，如果需要查询整个 Parquet 文件或运行需要文件大子集的多个查询，这可能非常有用。

%%sql
INSTALL httpfs;
LOAD httpfs;

现在，创建一个按第 90 百分位数进行过滤的查询。请注意 --save 和 --no-execute 函数的使用。这告诉 JupySQL 存储该查询，但跳过执行。它将在下一个绘图调用中被引用。

%%sql --save short_trips --no-execute
SELECT *
FROM 'https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2021-01.parquet'
WHERE trip_distance < 6.3

要创建直方图，请调用 %sqlplot histogram 并传入表名、要绘制的列以及分桶 (bins) 数量。这使用了 --with short-trips，因此 JupySQL 会使用之前定义的查询，从而仅绘制数据的一个子集。

%sqlplot histogram --table short_trips --column trip_distance --bins 10 --with short_trips

总结

现在，您能够以简单且高性能的方式在 SQL 和 Pandas 之间切换！您可以直接通过引擎绘制海量数据集（避免了下载整个文件并将其全部加载到 Pandas 内存中）。DataFrames 可以作为表在 SQL 中读取，SQL 查询结果也可以输出到 DataFrames 中。分析愉快！

jupysql 的一个替代方案是 magic_duckdb。