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 单元格
2. 通过单元格菜单将任何空单元格转换为 SQL
3. 点击笔记本底部的 SQL 按钮

在 marimo 中，SQL 单元格呈现出编写 SQL 的外观，同时使用 mo.sql() 函数序列化为标准的 Python 代码，这使得您的笔记本保持纯 Python 代码，而无需特殊的语法或魔法命令。

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

这是因为 marimo 将笔记本存储为纯 Python 格式，原因有很多，例如便于 Git 友好的差异比较以及将笔记本作为 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 单元格的连接下拉菜单中选择它。

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

marimo 会自省连接并在“数据源”面板中显示数据库、模式、表和列。此面板让您可以快速浏览模式，将表和列拖入您的 SQL 查询中。

引用本地数据帧

在 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 的运行时配置为“惰性”模式。通过这样做，依赖单元格仅被标记为“过期”，用户可以选择何时重新运行它们。

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⟩ 运行它。