Docs

Opening a file

There is no import step and no project to create. Open a file and it is queryable. Three ways in:

• Double-click it in Finder, once Datapuddle is the app for that type.
• File ▸ Open… (⌘O).
• File ▸ Open URL… (⌘⇧O) for an https:// or s3:// address.

A large file is not copied, converted or loaded into memory. Datapuddle reads it where it sits, which is why a multi-gigabyte Parquet opens in about the time it takes to read its footer.

What it opens

• Parquet — single files and globs.
• CSV and TSV — types and the header row are sniffed for you.
• JSON and NDJSON.
• .duckdb databases — the catalog appears in the sidebar, with every table and view in it.

Running a query

The editor sits above the results. It has SQL completion drawn from the catalog you actually have open — table names, column names and DuckDB's own functions.

• ⌘↩ — Run. With a selection, runs the selection; otherwise the statement under the cursor.
• ⌘⇧↩ — Run with Plan. Runs it and profiles it, filling the Plan tab with where the time actually went.
• ⌘E — Explain. The plan the engine intends, without running anything.
• Esc — cancels a query that is still running. It stops the engine, not just the spinner.

The file you opened is addressable by name, so a query can be as short as SELECT * FROM 'trips.parquet' WHERE fare > 100 — or you can query the opened table directly.

Reading the results

The grid scrolls the whole result, not its first page. Forty million rows scroll end to end; jumping to the last row is immediate. Only the rows near the viewport are held in memory.

Column profiles

Every column header draws its own distribution — the one deliberately loud element in the app. Null share, distinct count, and the shape of the values. They arrive in stages: the rows paint first, an approximate profile follows, then an exact one. The grid never waits on a profile.

Copying out

• ⌘C — copy the selection.
• ⌘⇧C — copy with column names, for pasting into a sheet.
• File ▸ Export Result… — the whole result to CSV or Parquet.

Query plans

After ⌘⇧↩, the Plan tab shows the profiled run two ways: a waterfall, where each operator's width is its share of the time, and a tree. Operators whose estimated row count diverged from the actual are called out — that divergence is usually the reason a query is slow. The raw JSON profile is one toggle away.

Connections

Beyond local files, Datapuddle attaches to PostgreSQL, SQLite, MotherDuck, S3 and a self-hosted server over DuckDB's Quack protocol. Add one with the + button on the Connections section of the sidebar.

Passwords, tokens and access keys go to the macOS Keychain, keyed per connection — never to a settings file, a log, or exported history. Removing a connection removes its Keychain item with it.

MySQL is not supported: its DuckDB extension cannot be statically linked, and this app links everything it ships.

Large files and memory

The engine runs under a 2 GB memory budget and spills to a temporary directory past it, so a file far larger than memory is a slower query rather than a crash. The clips on the home page are a 41,169,720-row Parquet scanning 630 MB, on a laptop.

If a query does spill heavily, the constraint is free disk space in your temporary directory, not RAM.

Keyboard shortcuts

What leaves your machine

Nothing, unless a query you wrote sends it somewhere you configured. No account, no telemetry, no update check, no licence call home. The DuckDB extensions are compiled into the binary, so none is ever downloaded at runtime. The full detail is on the privacy page.

Anything else

Support covers installation, the trial and purchases. For anything not answered there — including team licences or a build that uses your own DuckDB — support@datapuddle.app.

← Back to Datapuddle