Engine guides
DuckDB and data files.
Query CSV, TSV, Parquet, JSON, NDJSON and Excel files, or a .duckdb database, with SQL. Join them with a live PostgreSQL database if you like.
Opening files#
Use Open data file… on the Connections home, in the File menu, or in the palette, or drop files on the window. The Connections home says: “Drop a CSV, Excel, Parquet or JSON file here, or open one. DuckDB makes each file (and each Excel sheet) a table you can query with SQL.” Opening files starts a new DuckDB session and disconnects the current connection; when you drop files onto a window that is connected elsewhere, Plasma asks Open these files in DuckDB? first.
| Kind | Extensions |
|---|---|
| CSV | .csv (also .csv.gz); .txt is not accepted here |
| TSV | .tsv, .tab (also gzipped) |
| Parquet | .parquet |
| JSON | .json (also gzipped) |
| NDJSON | .ndjson, .jsonl (also gzipped) |
| Excel | .xlsx. Old .xls workbooks are not supported; save as .xlsx first. |
| DuckDB database | .duckdb, .ddb. Opened read-only. |
- Each file becomes a view named after the file (spaces and symbols become underscores; clashes get
_2,_3). An Excel workbook gives one view per visible sheet, namedfile_sheet. - File names containing
*,?,[or]are refused, because DuckDB would treat them as patterns. - Plasma only reads files you chose with the picker or dropped on the window; the renderer cannot name a path on its own.
Querying#
The workbench is the SQL editor with DuckDB as the engine. The sidebar lists the views; the grid is read-only. In the Structure tab each view shows a column profile (type, null percentage, an approximate distinct count, minimum and maximum) produced by DuckDB’s SUMMARIZE. Cancel interrupts the running statement. DuckDB has no plan view or ER diagram in Plasma.
Attach a PostgreSQL connection#
Attach a Postgres connection to this DuckDB session… (palette, while a file session is open) lists your saved PostgreSQL connections. The chosen one is attached read-only under the alias pg_<name>, so you can join your files with live tables. The session reopens with the same files. Queries run in DuckDB; nothing is written to PostgreSQL.
A .duckdb file as a connection#
You can also save a connection of engine DuckDB with DuckDB file pointing at a .duckdb file. It opens read-only. For CSV, Excel, Parquet or JSON, use Open data file… instead; the form says so. A read-only transaction is used for AI queries, which also refuses nextval().