Skip to content

PyGWalker Streamlit API

Streamlit 앱에 PyGWalker를 임베드하려면 StreamlitRenderer를 사용하세요. 데이터셋과 차트 상태를 rerun 사이에서 재사용한다면 렌더러를 캐시하세요.

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()

생성자

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_pathNone로컬 차트 상태 파일입니다. 로컬 파일에는 이 옵션을 권장합니다.
spec_io_mode"r"Streamlit UI에서 차트 편집 내용을 spec 파일에 저장해야 하면 "rw"를 사용하세요.
computationNone모드를 강제하려면 "browser", "kernel", "cloud"를 사용하세요. Streamlit 자동 동작은 기본적으로 kernel 쪽 계산을 사용합니다.
show_cloud_toolNone사용 가능한 경우 cloud UI 표시 여부를 제어합니다.
default_tab"vis"초기 탐색기 탭입니다.

kernel_computation과 use_kernel_calc는 레거시 호환성 옵션입니다. computation을 권장하며, 레거시 플래그는 PyGWalker 0.7.0에서 제거될 예정입니다.

주요 메서드

메서드용도
renderer.explorer(key="explorer", default_tab="vis")전체 drag-and-drop 탐색기입니다.
renderer.viewer(key="viewer")보기 전용/filter-renderer UI입니다.
renderer.chart(index, key="chart", size=None, pre_filters=None)0부터 시작하는 인덱스로 저장된 차트를 렌더링합니다.
renderer.table(key="table")테이블 뷰를 렌더링합니다.
renderer.set_global_pre_filters(pre_filters)차트 호출이 덮어쓰지 않는 한 여러 차트에 필터를 적용합니다.

저장된 차트 렌더링

차트를 spec_path에 저장한 뒤 인덱스로 하나의 차트를 렌더링하세요.

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"인 경우 값은 밀리초 타임스탬프 또는 파싱 가능한 날짜 문자열일 수 있습니다.

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 컴포넌트가 사용하는 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"을 사용하세요.

관련 가이드