PyGWalker Streamlit API

PyGWalker を Streamlit アプリに埋め込むには StreamlitRenderer を使います。データセットとチャート状態を rerun 間で再利用する場合は renderer をキャッシュします。

import pandas as pd
import streamlit as st
from pygwalker.api.streamlit import StreamlitRenderer
 
st.set_page_config(page_title="PyGWalker", layout="wide")
 
@st.cache_resource
def get_renderer():
    df = pd.read_csv("data.csv")
    return StreamlitRenderer(
        df,
        spec_path="./gw_config.json",
        spec_io_mode="rw",
        computation="kernel",
    )
 
renderer = get_renderer()
renderer.explorer()

Constructor

StreamlitRenderer(
    dataset,
    gid=None,
    *,
    field_specs=None,
    theme_key="g2",
    appearance="media",
    spec="",
    spec_path=None,
    spec_io_mode="r",
    computation=None,
    kernel_computation=None,
    use_kernel_calc=None,
    show_cloud_tool=None,
    kanaries_api_key="",
    default_tab="vis",
    **kwargs,
)

dataset には pandas DataFrame、polars DataFrame、pyarrow Table、データベース Connector、または再利用可能な pygwalker.Walker を渡せます。

主要オプション

オプション	デフォルト	メモ
`spec_path`	`None`	ローカルチャート状態ファイル。ローカルファイルにはこれを推奨します。
`spec_io_mode`	`"r"`	Streamlit UI がチャート編集を spec ファイルへ保存する必要がある場合は `"rw"` を使います。
`computation`	`None`	モードを強制するには `"browser"`、`"kernel"`、`"cloud"` を使います。Streamlit の自動挙動は kernel 側計算がデフォルトです。
`show_cloud_tool`	`None`	利用可能な場合に cloud UI の表示を制御します。
`default_tab`	`"vis"`	explorer の初期タブです。

kernel_computation と use_kernel_calc はレガシー互換オプションです。computation を優先してください。レガシーフラグは PyGWalker 0.7.0 で削除予定です。

主なメソッド

メソッド	用途
`renderer.explorer(key="explorer", default_tab="vis")`	フルのドラッグアンドドロップ explorer。
`renderer.viewer(key="viewer")`	表示専用 / filter-renderer UI。
`renderer.chart(index, key="chart", size=None, pre_filters=None)`	保存済みチャートを 0 始まりの index でレンダリングします。
`renderer.table(key="table")`	テーブルビューをレンダリングします。
`renderer.set_global_pre_filters(pre_filters)`	chart 呼び出しで上書きされない限り、チャート全体にフィルターを適用します。

保存済みチャートをレンダリングする

チャートを spec_path に保存したあと、index で 1 つのチャートをレンダリングします。

renderer.chart(0, size=(720, 420))

チャートレベルのフィルターには PreFilter を使います。

from pygwalker.api.streamlit import PreFilter
 
renderer.chart(
    0,
    pre_filters=[
        PreFilter(field="category", op="one of", value=["A", "B"]),
        PreFilter(field="revenue", op="range", value=[0, 100000]),
    ],
)

PreFilter は次を受け取ります。

PreFilter(
    field: str,
    op: "range" | "temporal range" | "one of",
    value: list[int | float | str],
)

op="temporal range" では、value にミリ秒タイムスタンプまたは parse 可能な日付文字列を指定できます。

`Walker` を再利用する

同じデータセットとオプションを他のアダプターと共有したい場合は、先に Walker を構築します。

import pygwalker as pyg
from pygwalker.api.streamlit import StreamlitRenderer
 
walker = pyg.Walker(
    df,
    spec_path="./gw_config.json",
    spec_io_mode="rw",
    computation="kernel",
)
 
renderer = StreamlitRenderer(walker)
renderer.explorer()

Walker を渡す場合、構築オプションは pyg.Walker(...) 側に置きます。StreamlitRenderer(walker, spec_path="./other.json") は既存オブジェクトと競合するため拒否されます。

`get_streamlit_html`

get_streamlit_html は Streamlit component が使う HTML 文字列を返します。

from pygwalker.api.streamlit import get_streamlit_html
 
html = get_streamlit_html(
    df,
    spec_path="./gw_config.json",
    spec_io_mode="rw",
    mode="explore",
    computation="kernel",
)

対応モードは "explore"、"filter_renderer"、"table" です。

よくある落とし穴

落とし穴	修正方法
rerun ごとに `StreamlitRenderer` を作り直す	構築処理を `@st.cache_resource` で包みます。
ローカルファイルに `spec="./gw_config.json"` を使う	`spec_path="./gw_config.json"` を使います。
`Walker` を渡したあとに構築オプションを渡す	それらのオプションを `pyg.Walker(...)` に移します。
新しいコードを `kernel_computation=True` で始める	`computation="kernel"` を使います。