Files

The files driver is the easiest way to start with PlotPress. Point it at a directory of data files and every file becomes a queryable view. No database to install, no DSN to configure.

Internally it uses DuckDB to read the files; for a full SQL surface (joins, custom views over multiple files), use the DuckDB connection instead.

DSN

ledger:
  driver: files
  path: ./data           # directory containing data files
  format: auto           # auto-detect by extension (default)
  allowed_users: [analysts]

Field	Meaning
path	Directory PlotPress watches for data files. Relative paths resolve from the dashboard folder.
format	auto (default — detect by extension), or pin to one: csv, tsv, json, ndjson, parquet, arrow.
recursive	true to walk subdirectories. Default false.
pattern	Optional glob to restrict which files become views (e.g. "*.parquet").

Supported formats

Extension	Format	Notes
.csv, .csv.gz	CSV	Headers auto-detected; types inferred from the first ~1000 rows.
.tsv, .tsv.gz	TSV	Tab-separated.
.json	JSON	Single root array of objects.
.ndjson, .jsonl, .jsonl.gz	JSON Lines	One object per line — preferred for large datasets.
.parquet	Parquet	Column projection / predicate pushdown supported.
.arrow, .feather	Apache Arrow	IPC stream / Feather v2.
.xlsx	Excel	First sheet only by default; pin a sheet with ?sheet=Name in the view name.

Compressed (.gz, .zst) variants of CSV/TSV/NDJSON are recognised by extension.

Views

Each file in the configured directory becomes a view named by its basename (without extension):

data/
├── orders.csv          → view=orders
├── customers.parquet   → view=customers
└── 2026/
    └── pageviews.ndjson  → view=2026__pageviews    (recursive=true)

Reference from a Plot block:

```plot view=orders
Plot.barY(data, { x: "status", y: { reduce: "count" } })
```

Parameters work via DuckDB-style placeholders the same way as the DuckDB connection.

Caveats

• Schema is inferred per file. If two files in the same directory share a basename (orders.csv and orders.parquet), the explicit-format file wins; otherwise it’s an error.
• Live updates. PlotPress watches the directory and re-discovers files on change. Schema changes (added/removed/renamed columns) take effect on the next request.
• Large CSVs. CSV requires reading the whole file for filtering. Convert to Parquet for tables larger than a few hundred MB — same connection, ten-times faster reads, automatic predicate pushdown.
• Headers. PlotPress assumes a header row for CSV/TSV. Disable with ?header=false in the view name (the view becomes column_0, column_1, …).
• Excel. Tracked but not free — .xlsx parsing is slow. Convert to CSV/Parquet at ingest time when you can.

When to graduate to DuckDB

files is great for a single directory of files exposed as flat views. Reach for DuckDB when you want:

• A SQL view that joins two files.
• A persistent .duckdb database file holding intermediate tables.
• DuckDB extensions (httpfs for S3, sqlite scanner, postgres scanner).