PyGWalker Dataset Inputs

PyGWalker works with tabular data. Most public APIs accept pandas DataFrame, polars DataFrame, pyarrow Table, database connectors, and connector-style SQL/data-source strings. Some adapters also accept a reusable pygwalker.Walker.

Supported input matrix

Dataset input	Typical APIs	Notes
pandas DataFrame	All major APIs	The most common local input.
polars DataFrame	All major APIs	Parsed through the DataFrame parser layer.
pyarrow Table	All major APIs	Supported by public API signatures and parser tests.
database `Connector`	`walk`, `render`, `table`, Streamlit, Gradio, webserver, cloud helpers	Connector datasets use kernel-side querying.
SQL/data-source string	Top-level, notebook, anywidget, marimo, webserver, component, HTML chart helpers	Use for connector-style paths where supported by the adapter.
`pygwalker.Walker`	`walk`, anywidget, marimo, webserver, Streamlit, `to_html`	Reuses an already constructed PyGWalker object.

Pandas

Use pandas when your data is already in memory.

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 DataFrames can be passed directly.

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

PyArrow Table

PyArrow Tables are supported by the public DataFrame type and parser tests.

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

Database Connector

Use Connector when data should stay behind a SQL query instead of being loaded into a local DataFrame first.

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 datasets are treated as kernel-computation inputs by default because queries need a live backend.

Reusable `Walker`

Create a Walker when you want one dataset and configuration to flow through more than one adapter.

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

Adapters reject construction options that conflict with an existing Walker. Put spec_path, field_specs, appearance, and computation on the Walker constructor.

FieldSpec

FieldSpec lets you override inferred field metadata.

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)

Definition:

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

Use "?" to let PyGWalker infer the value.

Common traps

Trap	Fix
Passing a local spec file through `spec` in new code	Use `spec_path="./gw_config.json"` so local files are explicit.
Passing `spec_path` again when an adapter receives a `Walker`	Put `spec_path` on `pyg.Walker(...)` instead.
Exporting static HTML with `computation="kernel"` or `"cloud"`	Use `computation="browser"` for static exports.
Using legacy `kernel_computation=True` in new examples	Use `computation="kernel"`.