Skip to content

PyGWalker データセット入力

PyGWalker は表形式データを扱います。ほとんどの公開 API は pandas DataFrame、polars DataFrame、pyarrow Table、データベース Connector、Connector 形式の SQL / データソース文字列を受け取れます。一部のアダプターは再利用可能な pygwalker.Walker も受け取れます。

対応入力マトリクス

データセット入力一般的な APIメモ
pandas DataFrame主要 API 全般最も一般的なローカル入力です。
polars DataFrame主要 API 全般DataFrame parser レイヤーで処理されます。
pyarrow Table主要 API 全般公開 API シグネチャと parser テストでサポートされています。
データベース Connectorwalk、render、table、Streamlit、Gradio、webserver、cloud helperConnector データセットは kernel 側のクエリを使います。
SQL / データソース文字列トップレベル、notebook、anywidget、marimo、webserver、component、HTML chart helperアダプターが対応する Connector 形式の経路で使います。
pygwalker.Walkerwalk、anywidget、marimo、webserver、Streamlit、to_html構築済みの PyGWalker オブジェクトを再利用します。

Pandas

データがすでにメモリ上にある場合は pandas を使います。

import pandas as pd
import pygwalker as pyg
 
df = pd.read_csv("data.csv")
walker = pyg.walk(df, spec_path="./gw_config.json")

Polars

Polars DataFrame はそのまま渡せます。

import polars as pl
import pygwalker as pyg
 
df = pl.read_csv("data.csv")
walker = pyg.walk(df, computation="browser")

PyArrow Table

PyArrow Table は公開 DataFrame 型と parser テストでサポートされています。

import pyarrow as pa
import pygwalker as pyg
 
table = pa.table({
    "city": ["London", "Paris", "Tokyo"],
    "sales": [120, 95, 140],
})
 
walker = pyg.walk(table, computation="browser")

データベース Connector

データをローカル DataFrame に先に読み込まず、SQL クエリの背後に置きたい場合は Connector を使います。

from pygwalker.data_parsers.database_parser import Connector
import pygwalker as pyg
 
conn = Connector(
    "postgresql+psycopg2://username:password@host:5432/database",
    "SELECT * FROM table_name",
)
 
walker = pyg.walk(conn, spec_path="./gw_config.json", computation="kernel")

クエリにはライブバックエンドが必要なため、Connector データセットはデフォルトで kernel-computation 入力として扱われます。

再利用可能な Walker

1 つのデータセットと設定を複数のアダプターに流したい場合は Walker を作成します。

import pygwalker as pyg
 
walker = pyg.Walker(
    df,
    spec_path="./gw_config.json",
    computation="browser",
)
 
walker.show()
html = pyg.to_html(walker, width="100%", height="720px")

アダプターは、既存の Walker と競合する構築オプションを拒否します。spec_path、field_specs、appearance、computation は pyg.Walker(...) のコンストラクターに渡してください。

FieldSpec

FieldSpec を使うと、推論されたフィールドメタデータを上書きできます。

from pygwalker import FieldSpec
import pygwalker as pyg
 
field_specs = [
    FieldSpec(
        fname="order_date",
        semantic_type="temporal",
        analytic_type="dimension",
        display_as="Order Date",
    ),
    FieldSpec(
        fname="revenue",
        semantic_type="quantitative",
        analytic_type="measure",
        display_as="Revenue",
    ),
]
 
pyg.walk(df, field_specs=field_specs)

定義:

FieldSpec(
    fname: str,
    semantic_type: "?" | "nominal" | "ordinal" | "temporal" | "quantitative" = "?",
    analytic_type: "?" | "dimension" | "measure" = "?",
    display_as: str = None,
)

PyGWalker に値を推論させるには "?" を使います。

よくある落とし穴

落とし穴修正方法
新しいコードでローカル spec ファイルを spec に渡すローカルファイルであることが明確になるように spec_path="./gw_config.json" を使います。
アダプターが Walker を受け取ったあとで、もう一度 spec_path を渡す代わりに pyg.Walker(...) 側へ spec_path を渡します。
静的 HTML を computation="kernel" または "cloud" でエクスポートする静的エクスポートには computation="browser" を使います。
新しい例でレガシーな kernel_computation=True を使うcomputation="kernel" を使います。

関連ガイド