摘要:在浏览器内的 Python 环境中运行 DuckDB,实现对远程文件的简单查询、交互式文档和易于使用的培训材料。

实现"Hello World"

当你第一次使用一个新的库时,最重要的是能多快实现"Hello World"。

同样,如果有人访问你写的任何文档,你希望他们能快速轻松地让你的工具运行起来。当你做演示时,你希望避免"演示地狱",并且第一次就能成功!

如果你想尝试"专家模式",试试带领整个会议室的人完成这些设置步骤!在课堂或会议研讨会环境中,安装过程必须万无一失,这一点变得更加重要。

Python 是我们使用 DuckDB 最喜欢的方式之一,但 Python 的设置出了名的困难 - 对于新手程序员来说更是如此。什么是虚拟环境?你用的是 Windows、Linux 还是 Mac?用 Pip 还是 Conda?还是新出现的 uv?

有经验的 Python 使用者也不能幸免!很多人,包括我在内,都被迫庆祝这个由  xkcd 记录的^[1]  传统 - 直接删除所有与 Python 相关的东西,然后从头开始。

我们如何让在 Python 中测试 DuckDB 变得尽可能简单和快速呢?

服务器端 Python 的困难

应对这一挑战的一种方法是为每个用户在服务器上托管一个 Python 环境。这有一些问题。

自己在服务器上托管 Python 并不是免费的。如果你有很多用户,费用可能远非小数。

如果你想使用像 Google Colab 这样的免费解决方案,每个访问者都需要一个 Google 账户,而且你需要接受 Google 访问你的数据。此外,很难将其嵌入到现有网页中以获得无缝体验。

Pyodide 登场

Pyodide^[2]  是一种直接在浏览器中运行 Python 的方法,无需安装和设置,这要归功于 WebAssembly 的强大功能。这使其成为启动和运行 Python 环境最简单和最快速的方式 - 只需加载一个网页!所有计算都在本地进行,因此可以像任何静态网站一样使用 GitHub Pages 等工具提供服务。不需要服务器端 Python!

另一个好处是 Pyodide 在浏览器环境中很好地沙盒化。每个用户都有自己的工作空间,而且由于全部是本地的,所以非常安全。

Pyodide 与其他浏览器内 Python 方法的不同之处在于,它甚至可以运行用 C、C++ 甚至 Fortran 编写的库,包括大部分 Python 数据科学栈。这意味着现在你也可以在 Pyodide 中使用 DuckDB 了!你甚至可以将其与 NumPy、SciPy 和 Pandas 结合使用(除了许多纯 Python 库之外)。PyArrow 和 Ibis 也有实验性支持。

Pyodide DuckDB 的使用场景

想要使用 Python 或 DuckDB 快速分析一些远程数据?

Pyodide 是使用 Python 最快速地获得答案的方法。

想要快速分析一些本地数据?

Pyodide 也可以 查询本地文件^[3] !

想让你的文档具有交互性?

让用户轻松测试你的 DuckDB 驱动的库。我们将在下面看到一个示例,演示  magic-duckdb^[4]  如何启用 SQL 单元格。

正在进行 DuckDB 和 Python 的培训课程?

跳过本地安装的麻烦。不需要与观众中 15% 有奇怪设置的人一对一工作!每个人都能在几秒钟内第一次成功运行,这样你就可以专注于你想教授的内容。而且它是免费的,不需要任何形式的注册!

Pyodide 示例

我们将介绍多种方法,将 Pyodide 驱动的 Python 直接嵌入到你的网站中,这样你的用户只需单击一下就可以尝试你的新 DuckDB 支持的工具!

• PyScript 编辑器

  
  

• 一个具有良好语法高亮的编辑器

• JupyterLite Notebook

  
  

• 经典的笔记本环境

• JupyterLite Lab IDE

  
  

• 完整的开发环境

PyScript 编辑器

这个 HTML 片段将在任何页面中嵌入一个可运行的 PyScript 编辑器!

<script type="module" src="https://pyscript.net/releases/2024.8.2/core.js"></script><script type="py-editor" config='{"packages":["duckdb"]}'>    import duckdb    print(duckdb.sql("SELECT '42 in an editor' AS s").fetchall())</script>

只需点击播放按钮,你就可以直接在浏览器中执行 DuckDB 查询。你可以编辑代码,添加新行等。试试看!

JupyterLite Notebook

这里是一个使用 iframe 指向部署在 GitHub Pages 上的 JupyterLite 环境的例子!

<iframe src="https://alex-monahan.github.io/jupyterlite_duckdb_demo/notebooks/index.html?path=hello_duckdb.ipynb" style="height: 600px; width: 100%;"></iframe>

这是一个完全交互式的 Python 笔记本环境,内部运行着 DuckDB。随意运行一下吧!

配置完整的 JupyterLite 环境只需几个步骤!JupyterLite 团队已经建立了一个作为模板的演示页面,并有一些 很棒的文档^[5] 。主要步骤是:

1. 使用 JupyterLite Demo 模板创建你自己的仓库

2. 为该仓库启用 GitHub Pages

3. 在 content 文件夹中添加并提交一个 .ipynb 文件

4. 访问 https://⟨YOUR_GITHUB_USERNAME⟩.github.io/⟨YOUR_REPOSITORY_NAME⟩/notebooks/index.html?path=⟨YOUR_NOTEBOOK.ipynb⟩

注意,GitHub Pages 部署可能需要几分钟时间。你可以在 GitHub 的 Actions 标签页上监控进度。

JupyterLite Lab IDE

按照 JupterLite Notebook 设置中的步骤操作后,如果你将 URL 从 /notebooks/ 改为 /lab/,你就可以获得完整的 IDE 体验!这种形式更难嵌入到另一个页面中,但非常适合交互式使用。

这个例子使用了  magic-duckdb^[3] ,它允许我们使用 %%dql 创建 SQL 单元格。

点击此链接查看 Lab IDE 界面^[6] ,或在下面尝试 Notebook 风格的版本。

<iframe src="https://alex-monahan.github.io/jupyterlite_duckdb_demo/notebooks/index.html?path=magic_duckdb.ipynb" style="height: 600px; width: 100%;"></iframe>

Pyodide 中 DuckDB 的架构

那么 DuckDB 在 Pyodide 中究竟是如何工作的呢?DuckDB Python 客户端被完整地编译成 WebAssembly (Wasm)。这与现有的  DuckDB Wasm^[7]  方法不同,因为后者只编译库的 C++ 部分,并用 JavaScript API 包装它。两种方法都使用 Emscripten 工具链来进行 Wasm 编译。正是 DuckDB 避免依赖的设计决策和之前在 DuckDB-Wasm 上的投资,使得在如此短的时间内构建这个成为可能!

Pyodide 团队已经将 DuckDB 添加到他们托管的库存储库中,甚至将 DuckDB 设置为他们 CI/CD 工作流的一部分。这就是为什么 JupyterLite 可以简单地运行 %pip install duckdb,而 PyScript 可以在 py-editor config 参数或 <py-config> 标签中指定 DuckDB 作为包。然后 Pyodide 从 Pyodide 的存储库下载 Wasm 编译版本的 DuckDB 库。我们要向 Pyodide 团队,包括  Hood Chatham^[8]  和  Gyeongjae Choi^[9] ,以及 Voltron Data 团队,包括领导这项工作的  Phillip Cloud^[10]  表示衷心的感谢。

限制

在浏览器中运行是一个更受限制的环境(出于安全目的),所以在 Pyodide 中使用 DuckDB 时有一些限制。没有免费的午餐!

• 单线程

  
  

• Pyodide 目前将执行限制在单个线程

• 查询远程文件需要额外的几个步骤

  
  

• DuckDB 不能直接访问远程文件

• 相反,先用 Pyodide 将文件拉到本地

• DuckDB-Wasm 有自定义增强功能使这成为可能,但这些功能在 DuckDB 的 Python 客户端中不存在

• 没有运行时加载的扩展

  
  

• 几个扩展会自动包含: parquet、json、icu、tpcds 和 tpch。

• 发布节奏与 Pyodide 保持一致

  
  

• 在撰写本文时,duckdb-pyodide 的版本是 1.0.0 而不是 1.1.1

结论

Pyodide 现在是同时使用 Python 和 DuckDB 的最快方式!它也是一种可以扩展到任意数量用户的方法,因为 Pyodide 的计算完全在本地进行。

我们已经看到了如何以多种方式将 Pyodide 嵌入到静态网站中,以及如何读取远程文件。

如果你对 Pyodide 中的 DuckDB 感到兴奋,欢迎加入我们的 Discord。我们有一个 #show-and-tell 频道,你可以在那里与社区分享你的作品。你也可以探索  duckdb-pyodide 仓库^[11]  并报告你发现的任何问题。我们也非常希望得到一些帮助来启用运行时加载的扩展 - 如果你能帮忙,请联系我们!

参考链接

1. xkcd 记录的: https://xkcd.com/1987/

2. Pyodide: https://pyodide.org/

3. 查询本地文件: https://pyodide.org/en/stable/usage/accessing-files.html

4. magic-duckdb: https://github.com/iqmo-org/magic_duckdb

5. 很棒的文档: https://jupyterlite.readthedocs.io/en/latest/quickstart/deploy.html

6. 点击此链接查看 Lab IDE 界面: https://alex-monahan.github.io/jupyterlite_duckdb_demo/lab/index.html?path=magic_duckdb.ipynb

7. DuckDB Wasm: https://github.com/duckdb/duckdb-wasm

8. Hood Chatham: https://github.com/hoodmane

9. Gyeongjae Choi: https://github.com/ryanking13

10. Phillip Cloud: https://github.com/cpcloud

11. duckdb-pyodide 仓库: https://github.com/duckdb/duckdb-pyodide