Entradas de Dados do PyGWalker

O PyGWalker trabalha com dados tabulares. A maioria das APIs públicas aceita pandas DataFrame, polars DataFrame, pyarrow Table, conectores de banco de dados e strings SQL/fonte de dados no estilo de conector. Alguns adaptadores também aceitam um pygwalker.Walker reutilizável.

Matriz de entradas suportadas

Entrada de dados	APIs típicas	Observações
pandas DataFrame	Todas as APIs principais	A entrada local mais comum.
polars DataFrame	Todas as APIs principais	Processado pela camada de parser de DataFrame.
pyarrow Table	Todas as APIs principais	Suportado pelas assinaturas da API pública e pelos testes de parser.
`Connector` de banco de dados	`walk`, `render`, `table`, Streamlit, Gradio, webserver, helpers de nuvem	Datasets de conector usam consultas no lado do kernel.
String SQL/fonte de dados	Top-level, notebook, anywidget, marimo, webserver, componente, helpers de gráfico HTML	Use para caminhos no estilo de conector quando o adaptador oferecer suporte.
`pygwalker.Walker`	`walk`, anywidget, marimo, webserver, Streamlit, `to_html`	Reutiliza um objeto PyGWalker já construído.

Pandas

Use pandas quando seus dados já estão em memória.

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

Polars

DataFrames Polars podem ser passados diretamente.

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

PyArrow Table

PyArrow Tables são suportadas pelo tipo público de DataFrame e pelos testes de 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 de Banco de Dados

Use Connector quando os dados devem permanecer atrás de uma consulta SQL em vez de serem carregados primeiro em um DataFrame local.

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

Datasets de conector são tratados por padrão como entradas de computação em kernel porque as consultas precisam de um backend ativo.

`Walker` reutilizável

Crie um Walker quando quiser que um dataset e uma configuração passem por mais de um adaptador.

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

Adaptadores rejeitam opções de construção que entram em conflito com um Walker existente. Coloque spec_path, field_specs, appearance e computation no construtor Walker.

FieldSpec

FieldSpec permite sobrescrever metadados inferidos dos campos.

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)

Definição:

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

Use "?" para deixar o PyGWalker inferir o valor.

Armadilhas comuns

Armadilha	Correção
Passar um arquivo spec local por `spec` em código novo	Use `spec_path="./gw_config.json"` para explicitar arquivos locais.
Passar `spec_path` novamente quando um adaptador recebe um `Walker`	Coloque `spec_path` em `pyg.Walker(...)`.
Exportar HTML estático com `computation="kernel"` ou `"cloud"`	Use `computation="browser"` para exportações estáticas.
Usar `kernel_computation=True` em exemplos novos	Use `computation="kernel"`.