marimo 是一个用于 Python 和 SQL 的开源响应式笔记本，它与 DuckDB 的 Python 客户端紧密集成，让你可以在同一个支持 git 版本控制的笔记本中混合使用 Python 和 SQL。与传统笔记本不同，当你运行某个单元格或与 UI 元素交互时，marimo 会自动（或按需）运行受影响的单元格，从而保持代码和输出的一致性。它与 DuckDB 的集成使其非常适合交互式数据处理，而其作为 Python 文件的呈现方式使得将笔记本作为脚本运行变得非常简单。

安装

要开始使用，请通过终端安装 marimo 和 DuckDB

pip install "marimo[sql]" # or uv add "marimo[sql]"

安装支持库

pip install "polars[pyarrow]" # or uv add "polars[pyarrow]"

运行教程

marimo tutorial sql

在 marimo 中使用 SQL

通过终端输入 marimo edit notebook.py 创建笔记本。你可以通过以下三种方式之一创建 SQL 单元格：

1. 右键点击 + 按钮并选择 SQL cell
2. 通过单元格菜单将任何空单元格转换为 SQL 单元格
3. 点击笔记本底部的 SQL 按钮

在 marimo 中，SQL 单元格看起来是在编写 SQL，但实际上它们被序列化为标准的 Python 代码，使用 mo.sql() 函数。这使得你的笔记本保持为纯 Python 代码，而无需特殊的语法或魔法命令。

df = mo.sql(f"SELECT 'Off and flying!' AS a_duckdb_column")

这是因为 marimo 将笔记本存储为纯 Python 文件，原因有很多，例如支持友好的 git diff 以及可以将笔记本作为 Python 脚本运行。

SQL 语句本身是一个 f-string，允许你通过 {} 将 Python 变量插入查询中（稍后展示）。特别地，这意味着你的 SQL 查询可以依赖于 UI 元素的值或其他 Python 变量，这些都是 marimo 数据流图的一部分。

警告：请注意！如果你的 SQL 查询包含用户生成的内容，请务必清理输入以防止 SQL 注入。

连接自定义 DuckDB 连接

若要连接到自定义的 DuckDB 连接而不是使用默认的全局连接，请创建一个单元格并将 DuckDB 连接定义为 Python 变量：

import duckdb

# Create a DuckDB connection
conn = duckdb.connect("path/to/my/duckdb.db")

marimo 会自动发现该连接，并允许你在 SQL 单元格的连接下拉菜单中选择它。

数据库、模式（Schema）和表自动发现

marimo 会对连接进行内省，并在“数据源”（Data Sources）面板中显示数据库、模式、表和列。该面板让你能够快速浏览模式，并将表和列拖拽到 SQL 查询中。

引用本地数据帧（Dataframe）

在 SQL 单元格中，通过使用持有数据帧的 Python 变量名来引用本地数据帧。如果你有一个与该变量同名的数据库表，则会优先使用数据库表。

import polars as pl
df = pl.DataFrame({"column": [1, 2, 3]})

SELECT * FROM df WHERE column > 2

引用 SQL 单元格的输出

在 SQL 单元格中定义一个非私有（非下划线开头）的输出变量，可以让你在其他 Python 和 SQL 单元格中引用所得的数据帧。

响应式 SQL 单元格

marimo 允许你创建响应式 SQL 单元格，当其依赖项发生变化时会自动更新。正在处理高昂的查询或大数据集吗？你可以将 marimo 的运行时配置为“惰性（lazy）”模式。这样，依赖单元格只会被标记为过期，由用户决定何时重新运行。

digits = mo.ui.slider(label="Digits", start=100, stop=10000, step=200)
digits

CREATE TABLE random_data AS
    SELECT i AS id, random() AS random_value,
    FROM range({digits.value}) AS t(i);

SELECT * FROM random_data;

与滑块等 UI 元素进行交互，可以让你的数据更加直观。

marimo 中基于 DuckDB 的 OLAP 分析

marimo 提供了多项功能，非常适合与 DuckDB 配合进行分析工作流：

• Python 和 SQL 之间的无缝集成
• 响应式执行，在查询发生变化时自动更新依赖单元格
• 可用于参数化 SQL 查询的交互式 UI 元素
• 能够将笔记本导出为独立应用程序或 Python 脚本，甚至可以通过 WebAssembly 完全在浏览器中运行。

后续步骤

• 阅读 marimo 文档。
• 尝试 SQL 教程：marimo tutorial sql。
• 本指南的代码可在 GitHub 上获得。通过 marimo edit ⟨github_url⟩ 运行它。