Gradio 接入数据库实战：用 SQLAlchemy + pandas 把 SQL 查询渲染成可交互图表

在构建机器学习可视化应用时，待展示的数据往往并不在内存里，而是存放在 SQLite、PostgreSQL、MySQL 等数据库中。本文基于 Gradio 官方指南《Connecting to a Database》展开，讲解如何借助 SQLAlchemy 快速把数据库查询结果提取成 pandas DataFrame，再交给 Gradio 的原生绘图组件（如 gr.LinePlot）直接渲染；读完你可以掌握静态 SQL 结果展示、基于控件联动生成交互式 SQL 查询，以及在不同数据库引擎之间自由切换的完整套路。

整体思路：数据库查询结果 = 图表组件的数据源

Gradio 的原生绘图组件（gr.LinePlot、gr.BarPlot、gr.ScatterPlot）的输入数据模型就是 pandas DataFrame。因此接入数据库的链路非常直接：

1. 用 SQLAlchemy 的 create_engine 创建数据库引擎；
2. 用 pandas 的 pd.read_sql_query(sql, engine) 执行 SQL 并把结果包装成 DataFrame；
3. 把 DataFrame 作为 value 传入 gr.LinePlot 等绘图组件，并指定横轴列 x 与纵轴列 y。

这样做的优势是：数据库层与可视化层解耦，SQL 层负责“取数”，DataFrame 负责“传输”，绘图组件只关心列名。从源码看，gradio/components/native_plot.py 中的原生绘图组件都继承自 NativePlot 基类，其中 value 参数的类型正是 pd.DataFrame | Callable | None，且支持回调函数动态返回数据（见 NativePlot.init）。

环境准备

首先安装 SQLAlchemy（pandas 通常随演示环境已具备，若缺失可一并安装）：

pip install sqlalchemy
# 若环境中还没有 pandas，请同时安装
pip install pandas

安装完成后即可开始编写接入数据库的 Blocks 应用。

场景一：SQLite 静态查询，一键渲染折线图

SQLite 是最轻量的入门选择。假设本地存在一个 your_database.db 数据库文件，其中有一张 flight_info 航班信息表，包含 time（时间）、price（价格）与 origin（出发地）等列。下面的代码把整张表的时间—价格序列直接画成折线图：

import gradio as gr
from sqlalchemy import create_engine
import pandas as pd

engine = create_engine('sqlite:///your_database.db')

with gr.Blocks() as demo:
    gr.LinePlot(pd.read_sql_query("SELECT time, price from flight_info;", engine), x="time", y="price")

if __name__ == "__main__":
    demo.launch()

要点说明：

• sqlite:///your_database.db 是 SQLite 的 SQLAlchemy 连接串，/// 后跟数据库文件的相对路径，也可换成绝对路径；
• pd.read_sql_query 执行查询并把结果封装为 DataFrame，原样传入 gr.LinePlot；
• x="time"、y="price" 指定图表横、纵轴使用的列名。根据 NativePlot 组件文档：x 列可以是数值、日期时间或字符串/类别列；y 列则必须是数值列，否则无法绘制坐标点。

gr.LinePlot 的完整实现位于 native_plot.py 中的 LinePlot 类，它只通过 get_mark() 返回 "line"，其余横轴、聚合、缩放、分组等能力全部复用 NativePlot 基类。

如果想在没有现成数据库文件的机器上快速复现效果，可以先自建一张内存表做验证：

import gradio as gr
import pandas as pd
from sqlalchemy import create_engine

engine = create_engine("sqlite://")
demo_df = pd.DataFrame({
    "time": pd.date_range("2026-01-01", periods=50, freq="h"),
    "price": range(100, 150),
    "origin": ["DFW", "DAL", "HOU"] * 17 + ["DFW"],
})
demo_df.to_sql("flight_info", engine, index=False)

with gr.Blocks() as demo:
    gr.LinePlot(
        pd.read_sql_query("SELECT time, price from flight_info;", engine),
        x="time", y="price",
    )

demo.launch()

场景二：交互式查询，让控件“改写”SQL

静态结果往往不够用。更常见的需求是：用户在下拉框里选择一个出发地，图表随之按条件重新查询。核心技巧是给绘图组件的 value 传入一个 lambda 函数，函数参数与 inputs 绑定的组件一一对应，返回新的 DataFrame 即可触发重绘：

import gradio as gr
from sqlalchemy import create_engine
import pandas as pd

engine = create_engine('sqlite:///your_database.db')

with gr.Blocks() as demo:
    origin = gr.Dropdown(["DFW", "DAL", "HOU"], value="DFW", label="Origin")

    gr.LinePlot(
        lambda origin: pd.read_sql_query(
            f"SELECT time, price from flight_info WHERE origin = {origin};",
            engine
        ),
        inputs=origin,
        x="time",
        y="price",
    )

if __name__ == "__main__":
    demo.launch()

理解这段代码需要把握三点：

1. 函数即数据源：value 从 DataFrame 换成 Callable 后，Gradio 会把 inputs（此处为 origin 下拉框）的当前值注入函数参数，再用函数返回值刷新图表，这与 gr.LinePlot 基类 value 参数声明的 Callable 类型完全吻合；
2. 下拉框联动：gr.Dropdown 的可选项为 ["DFW", "DAL", "HOU"]，默认选中 "DFW"；用户切换选项会重新执行查询并更新折线图；
3. SQL 由 UI 驱动：WHERE origin = {origin} 中的 {origin} 来自下拉框选中值，SQL 查询随交互动态生成。

若在测试中发现下拉框变化后图表没有刷新，可以检查数据库表中的 origin 取值是否与下拉框选项完全一致（大小写、空格均敏感）。

工程提示：直接使用 f-string 拼接 SQL 存在注入风险。在真实生产项目中，更推荐用 pd.read_sql_query 的参数化写法，例如： pd.read_sql_query("SELECT time, price FROM flight_info WHERE origin = :origin;", engine, params={"origin": origin})， 或先用 sqlalchemy.text() 绑定参数，再交给 pandas 执行。

这种“下拉框 + 原生图表”的交互模式还可以继续叠加 color 分组、x_bin 时间分桶、y_aggregate 聚合等参数，形成更丰富的仪表盘。仓库中的 line_plot_demo/run.py 给出了完整的进阶示例：它用 gr.Radio 控制 x_bin 与 y_aggregate、用 gr.DateTime 控件结合 x_lim 缩放时间轴，并通过事件监听批量更新多个 gr.LinePlot，可以直接作为设计“可筛选的数据库可视化面板”的参考蓝本。

场景三：PostgreSQL、MySQL、Oracle 等数据库

SQLAlchemy 的优雅之处在于：换数据库只换一行连接串，其余代码（查询、DataFrame 转换、渲染）完全不用动。

# PostgreSQL
engine = create_engine('postgresql://username:password@host:port/database_name')

# MySQL
engine = create_engine('mysql://username:password@host:port/database_name')

# Oracle
engine = create_engine('oracle://username:password@host:port/database_name')

把上面任一 engine 替换进前两个场景的代码即可。连接串的通用格式为 dialect://用户名:密码@主机:端口/数据库名，例如 PostgreSQL 默认端口为 5432、MySQL 为 3306。根据不同数据库的官方驱动要求，通常还需要额外安装对应的 DBAPI 驱动包（如 PostgreSQL 生态的 psycopg2、MySQL 生态的 pymysql 等），SQLAlchemy 才会真正建立连接；此外，为避免口令硬编码泄漏，生产环境建议把连接串中的账号密码放到环境变量或密钥管理服务中读取。

源码级补充：DataFrame 是如何变成一张图的

如果你好奇 gr.LinePlot 在拿到 DataFrame 后做了什么，可以顺着 gradio/components/native_plot.py 一探究竟：

• 原生图表组件（gr.LinePlot/gr.BarPlot/gr.ScatterPlot）都继承同一个 NativePlot 基类，仅通过 get_block_name() 与 get_mark() 区分渲染节点与标记类型（line/bar/point），见 LinePlot、BarPlot、ScatterPlot 的定义；
• 后端 postprocess 方法把收到的 DataFrame 序列化为 PlotData（包含 columns、data、datatypes 与 mark 字段）再交给前端渲染，这正是 value 支持“静态 DataFrame 或返回 DataFrame 的回调函数”两种形态的原因；
• 除 x/y 外，NativePlot.__init__ 还提供了 color（按类别列分组上色）、title、x_lim/y_lim（坐标轴范围）、x_bin/y_aggregate（时间分桶与聚合）、x_axis_format/y_axis_format 等参数，意味着接入数据库后，你仍可在不写前端代码的前提下完成分组、缩放、格式化的全套配置（参数清单见 NativePlot 构造函数）。

把「数据库查询」与上述参数结合就能得到典型的分析面板：SQL 负责按条件取数，color 按类别拆出多组序列，x_bin + y_aggregate 在时间粒度上做聚合统计。若需要的是 matplotlib 等第三方绘图对象而非原生图表，仓库还提供通用的 gradio/components/plot.py 组件承接任意绘图结果。

小结与相关指南

本指南覆盖了 Gradio 接入数据库的最小闭环：SQLAlchemy 连接引擎 → pandas 查询为 DataFrame → gr.LinePlot 渲染，并在此基础上实现了「下拉框联动改写 SQL」的交互式查询与跨数据库引擎切换。同一《数据科学与绘图》章节下还有更多可组合的进阶内容：

• 创建图表：DataFrame 绘图入门：讲解 LinePlot/BarPlot/ScatterPlot 的列映射与基础参数；
• 时间序列图：datetime 列、时间分桶与聚合的详细用法；
• 筛选器、表格与统计：原生绘图的筛选、交互与统计能力。

动手建议：先用 SQLite 跑通「场景一」，再换成带 WHERE 条件的「场景二」，最后把 engine 指向你的真实数据库即可上线；查询慢时，优先在数据库侧为 WHERE 条件涉及的列建立索引，而不是在应用层做分页或缓存。