PyGWalker API 参考

使用 pygwalker.walk(df) 可以快速打开交互式探索器。需要在 notebook、Streamlit、webserver 或 HTML 导出之间复用同一个数据集、图表状态和计算模式时，请使用 pygwalker.Walker(...)。

import pygwalker as pyg
 
walker = pyg.Walker(df, spec_path="./gw_config.json", computation="browser")
walker.show()

选择入口 API

API	适合场景	说明
`pygwalker.walk(dataset, ...)`	在 notebook 或脚本中快速探索	在 Jupyter 中默认使用 anywidget，在 notebook 之外使用本地 webserver。
`pygwalker.Walker(dataset, ...)`	在多个适配器之间复用同一个 PyGWalker 对象	将 `spec_path`、`field_specs` 和 `computation` 等构造选项放在 `Walker` 上。
`pygwalker.render(dataset, spec=..., ...)`	只渲染已保存图表，不打开完整探索器	本地图表文件请使用 `spec_path`。
`pygwalker.table(dataset, ...)`	打开表格/数据概览视图	接受与 `render` 相同的数据集和计算选项。
`pygwalker.to_html(dataset_or_walker, ...)`	静态 HTML 导出	仅支持浏览器计算，会拒绝 `computation="kernel"` 和 `computation="cloud"`。
`StreamlitRenderer(dataset_or_walker, ...)`	Streamlit 应用	长时间运行的应用中用 `st.cache_resource` 缓存 renderer。
`get_html_on_gradio(dataset, ...)`	Gradio 应用	返回 iframe HTML，并挂载 `PYGWALKER_ROUTE`。
`pygwalker.component(dataset, ...)`	用代码构建图表	链式调用 mark、encode、layout 和导出方法。
`pygwalker.spec.migrate(spec)`	更新已保存的图表状态	接受已加载的 spec 对象、JSON 字符串或本地文件路径。

支持的数据集

大多数公共 API 接受 pandas DataFrame、polars DataFrame、pyarrow Table、数据库 Connector，以及适配器支持的连接器式 SQL/data-source 字符串。pygwalker.walk、notebook anywidget/marimo/webserver 适配器、StreamlitRenderer 和 to_html 也可以接受可复用的 pygwalker.Walker 对象。

详情和示例请参阅数据集输入。

常用选项

选项	类型	默认值	用途
`spec_path`	`str` or `None`	`None`	要加载和保存的本地图表状态文件。优先使用它，而不是通过 `spec` 传入本地文件路径。
`spec`	`str`	`""`	内联 JSON、配置 ID 或远程 spec URL。
`computation`	`auto`, `browser`, `kernel`, `cloud`, or `None`	`None`	选择 PyGWalker 在哪里运行数据查询。省略或使用 `"auto"` 表示自动行为。
`field_specs`	`List[FieldSpec]` or `None`	`None`	覆盖自动推断的字段语义类型和分析类型。
`theme_key`	`vega`, `g2`, or `streamlit`	`"g2"`	选择渲染器主题系列。
`appearance`	`media`, `light`, or `dark`	`"media"`	`media` 会跟随操作系统配色方案。
`default_tab`	`data` or `vis`	`"vis"`	选择探索器视图的初始标签页。

计算模式

新代码请使用 computation，不要使用旧的计算布尔参数。

值	行为	典型用途
省略或 `"auto"`	保留 PyGWalker 的自动模式选择	大多数用户的默认选择。
`"browser"`	在前端/浏览器中运行数据查询	静态 HTML 导出和较小的本地数据。
`"kernel"`	通过本地 DuckDB 支持的 Python kernel 计算运行查询	在 live notebook、Streamlit、Gradio 或 webserver 会话中处理较大的本地数据集。
`"cloud"`	通过 Kanaries 云计算运行查询	使用 Kanaries API key 的云端工作流。

kernel_computation、cloud_computation 和 use_kernel_calc 是旧兼容参数，已弃用，并计划在 PyGWalker 0.7.0 中移除。不要将启用的旧参数与非 auto 的 computation 值组合使用；PyGWalker 会抛出 ValueError。

迁移示例请参阅计算模式。

复用 `Walker`

当多个适配器需要共享同一份配置时，请创建 Walker。

import pygwalker as pyg
 
walker = pyg.Walker(
    df,
    spec_path="./gw_config.json",
    spec_io_mode="rw",
    computation="kernel",
)
 
walker.show()
renderer = walker.to_streamlit()

当适配器接收 Walker 时，构造选项必须已经设置在 Walker 上。例如，pyg.to_html(walker, spec_path="./other.json") 会被拒绝，因为它会尝试用冲突状态重建已有对象。

静态 HTML 限制

静态 HTML 导出没有 live Python 或云端后端。调用 pyg.to_html(...)、walker.to_html() 或组件 HTML 导出时，请使用 computation="browser" 或省略计算选项。需要 kernel 或 cloud 计算时，请使用 live 适配器，例如 Notebook API、Streamlit 或 Gradio。