Chart CSV, Excel, JSON, and TSV Files with Vizly

Not every dataset lives in a database. You get CSVs from clients, Excel exports from finance, JSON payloads from APIs, and TSV dumps from legacy systems. Vizly has a loader for each of these in the base package, with no extra installs.

CSV files

vz.from_csv() reads a path or path-like string. It returns a tabular view ready for any chart factory.

import vizly as vz

sales = vz.from_csv("sales.csv")
chart = vz.bar(sales, x="region", y="sales", title="Sales by region")
chart.render("sales.html")

Custom delimiters work for pipe or semicolon separated files:

data = vz.from_csv("data.psv", delimiter="|")
chart = vz.line(data, x="date", y="revenue", title="Revenue")

TSV files

Tab-separated exports use from_tsv():

data = vz.from_tsv("metrics.tsv")
chart = vz.area(data, x="time", y="value", title="Throughput")

JSON files

from_json() handles three common shapes: a list of record dicts, a columnar object, and nested data payloads. Set orient= to match your file.

# List of records: [{"date": "...", "revenue": 42}, ...]
data = vz.from_json("records.json", orient="records")

# Columnar object: {"date": [...], "revenue": [...]}
data = vz.from_json("columnar.json", orient="columnar")

chart = vz.line(data, x="date", y="revenue", title="Revenue")

Excel workbooks

from_excel() reads a sheet from an .xlsx workbook using openpyxl, which ships with the base package. Select a sheet by name or index (defaults to the first sheet).

# First sheet
budget = vz.from_excel("budget.xlsx")

# Specific sheet by name or index
budget = vz.from_excel("budget.xlsx", sheet_name="Q3")
budget = vz.from_excel("budget.xlsx", sheet_name=2)

chart = vz.waterfall(budget, x="category", y="amount", title="Budget breakdown")

From records and columnar dicts

Data you already hold in Python can go straight into a chart without a file at all. This is the fastest path when data comes from an API call or is built in code.

# List of dicts (records)
payload = [
    {"date": "2026-01-01", "revenue": 42},
    {"date": "2026-01-02", "revenue": 48},
]
chart = vz.line(vz.from_records(payload), x="date", y="revenue")

# Columnar dict
payload = {"date": ["2026-01-01", "2026-01-02"], "revenue": [42, 48]}
chart = vz.line(vz.from_columnar(payload), x="date", y="revenue")

Note that chart factories also accept records and columnar dicts directly, so the explicit loader calls are optional:

chart = vz.line(payload, x="date", y="revenue")

Building a dashboard from mixed files

A common pattern: revenue from CSV, budget from Excel, and API metrics from JSON, all composed into one dashboard.

import vizly as vz

vz.set_theme("corporate")

sales = vz.from_csv("sales.csv")
budget = vz.from_excel("budget.xlsx", sheet_name="Annual")
metrics = vz.from_json("api_metrics.json", orient="records")

chart = vz.page(
    charts=[
        vz.bar(sales, x="region", y="sales", title="Sales by region"),
        vz.waterfall(budget, x="category", y="amount", title="Budget"),
        vz.line(metrics, x="date", y="value", title="API metrics"),
    ],
    title="Mixed source dashboard",
)
chart.render("dashboard.html")

Tips

Tip	Detail
Watch delimiters	CSV defaults to comma. Pass `delimiter="
Name your sheets	Excel workbooks with many sheets are easier to keep straight with sheet_name="Q3" than index numbers.
JSON shapes differ	Match orient= to your file. records and columnar cover most API and export formats.
Skip the loader	Chart factories accept records and columnar dicts directly, so you can chart API payloads in one call.
Prefer SQL for big data	For large or frequently queried datasets, from_sql beats file loading. See the SQL dashboards recipe.