Documentation

SQL for Files lets you load CSV, JSON, and Parquet into a local DuckDB engine running in your browser. Use the editor like a lightweight IDE: add data, work in multiple query tabs, inspect results, build charts, and keep all your data local.

CSV, JSON, ParquetLocal-only processingCharts and column stats

On This Page

Jump to the part you need

The docs follow the app flow from importing data to exporting results. Use the links below if you want to skip straight to a specific feature.

Updated for the current editor UI

Start Here

Quickstart

  1. Open the editor and add one or more CSV, JSON, or Parquet files from the Add Data sidebar section.
  2. Review the generated table names in Database, then expand a table to inspect its schema.
  3. Write a query in the current tab, or create a fresh tab for a different idea.
  4. Press Ctrl/Cmd + Enter to run the selected SQL or the whole query.
  5. Review the Data, Visualisation, or Classification result tabs.
  6. Export the result as CSV, save the current database to your browser, or create a Parquet ZIP backup to move elsewhere.

Import

Add Data

Fast add

  • Drag and drop files or click the add area.
  • Supported formats: CSV, JSON arrays, NDJSON, and Parquet.
  • New tables are created from your files and typically saved locally for future sessions.
  • There is also a sample CSV link in the add panel if you want something quick to test with.

Advanced options

  • Preview the first 10 rows before creating a table.
  • Choose a custom table name.
  • For CSV files, adjust delimiter, header handling, skipped rows, quote, escape, null string, date format, and decimal separator.
  • Excel .xlsx files are not supported directly; convert them to CSV first.

Layout

IDE Tour

Sidebar

The sidebar groups Add Data, Database, and Query History. On mobile, the same sections open from the menu drawer.

Query tabs

Work in multiple editor tabs, rename them inline, and keep separate query drafts around while comparing results.

Results panel

The results panel shows row count and execution time, can be resized or collapsed, and switches between Data, Visualisation, and Classification views.

Learning

Learn SQL

Open the learning panel

  • Click Learn SQL in the top navigation to open the guided lesson panel from anywhere in the app.
  • On desktop, the lessons open in the right-side panel next to the editor and results.
  • On mobile, open the editor and switch to the Learn tab in the bottom tab bar.
  • Closing and reopening the panel keeps your lesson progress saved locally in your browser.

Work through a lesson

  1. Pick a lesson from the chapter list.
  2. Read the explanation and example SQL.
  3. If the lesson includes sample data, click Load Data to create the lesson tables.
  4. Click Start in Editor to prefill the active SQL tab when a challenge provides starter SQL.
  5. Run your query, then click Check Answerto validate the latest result.
  6. Use Previous and Nextto move through the track, or go back to All lessons at any time.

Progress and tips

  • Completed lessons are marked in the navigation and counted in the progress bar at the top of the panel.
  • Lesson completion is based on passing the built-in challenge check for that lesson.
  • If you want to start over, use Reset progressfrom the lesson overview.
  • The checker uses the latest query result from the active editor tab, so rerun your SQL after making changes before checking again.

Editor

Querying in Tabs

  • Monaco provides SQL syntax highlighting plus autocomplete for tables, columns, and common SQL keywords.
  • If you select part of a query and run it, only the selected text executes.
  • DDL changes such as creating or dropping tables refresh the Database sidebar after execution.
  • Query History stores recent runs locally, including status, row count, and execution time. You can reload, download, or delete entries from the sidebar.
  • Editor tab names and SQL drafts are persisted locally in your browser so you can come back to unfinished work.

Example queries

Inspect an imported table

SELECT *
FROM sales
LIMIT 25;

Join two imported files

SELECT
  o.order_id,
  c.customer_name,
  o.total_amount
FROM orders o
JOIN customers c ON o.customer_id = c.id
WHERE o.total_amount > 100
ORDER BY o.total_amount DESC;

Build a chart-friendly aggregation

SELECT
  country,
  COUNT(*) AS orders,
  AVG(total_amount) AS avg_order_value
FROM orders
GROUP BY country
ORDER BY orders DESC;

Inspect

Explore Tables and Results

  • Expand any table in Database to inspect its columns and data types.
  • Use the preview action to open a new tab with a sample query: SELECT * FROM table LIMIT 100.
  • The data grid displays up to 1,000 rows for responsiveness.
  • Column headers in the Data tab are sortable.
  • CSV export uses the full Arrow result, so exported files can include all rows even when the UI only shows the first 1,000.

Charts

Visualisation

  • Switch to the Visualisation tab after a query runs.
  • Start with auto-detected defaults, then configure bar, line, or pie charts in the side panel.
  • Choose category and value columns, add multiple series for axis-based charts, and set title or subtitle text.
  • If your category values repeat, the app warns that a GROUP BY query may produce a more meaningful chart.
  • Export charts as SVG or PNG, or copy a PNG image directly to your clipboard.

Stats

Classification

  • The Classification tab computes per-column statistics for the current result set.
  • Numeric and date columns show values such as min, max, mean, median, mode, and null count.
  • String columns show minimum and maximum length plus null count.
  • Boolean columns show true, false, and null counts.
  • Stats are computed from the full query result, not just the rows currently visible in the table.

Persistence

Save, Restore, Export, and Import

Local persistence

  • Added and imported tables are stored locally in your browser using IndexedDB.
  • On a later visit, persisted tables can be restored into the database automatically.
  • Use Save after changing tables with SQL if you want the current database state written back to local storage.
  • Query history is stored locally in IndexedDB, while layout preferences and editor tab drafts are stored locally in the browser as well.

Backups and sharing

  • Export creates a ZIP backup containing every table as Parquet plus metadata.
  • Import restores those backups and can optionally replace existing tables.
  • Use CSV export when you only need a query result.
  • Use the Parquet ZIP export when you want a fuller, lossless backup of your working database.

Speed Up

Keyboard Shortcuts

ShortcutAction
Ctrl/Cmd + EnterRun the selected SQL or the full editor contents.
Ctrl + /Toggle SQL comments in the Monaco editor.
Ctrl + SpaceOpen autocomplete suggestions for tables, columns, and SQL keywords.
Ctrl/Cmd + FSearch within the current editor tab.
Ctrl/Cmd + BCollapse or expand the sidebar.
Ctrl/Cmd + JCollapse or expand the results panel.

On Mac, use Cmd anywhere the interface shows Ctrl.

Scale

Limits and Performance

  • SQL for Files runs fully in-browser, so memory is the main practical limit.
  • Browsers usually top out around 4GB, with a more realistic working range of roughly 2 to 3GB for analytical workloads.
  • Start with LIMIT, filter early with WHERE, and prefer GROUP BY when you do not need every row.
  • Parquet is usually more memory-efficient than CSV or JSON, especially for larger datasets.
  • If results are very large, the UI warns about truncation and keeps the display lightweight while preserving the full data for CSV export.

Common Questions

FAQ

Is my data really private?

Yes. File processing, SQL execution, visualisation, and classification happen in your browser. Your files, queries, and query results are not uploaded by the app.

What happens if I refresh the page?

Persisted tables can be restored from IndexedDB, query history is kept locally, and editor tabs keep their saved SQL drafts. You can also export a Parquet ZIP backup and import it later.

Does this work offline?

After the app has loaded, many features can keep working if the necessary assets are still cached by your browser. The first load still needs an internet connection.

Can I use Excel (.xlsx) files directly?

No. This app currently supports CSV, JSON, and Parquet. Convert Excel files to CSV before adding them.

How large can my files be?

Browser memory is the main constraint. A practical working range is usually around 2 to 3GB of data in memory, and files around 200MB are typically the easiest place to start.

Fixes

Troubleshooting

Adding a file fails

  • Check that the file is CSV, JSON, or Parquet.
  • For JSON, use either an array of objects or newline- delimited records.
  • For CSV, try the Advanced options modal to confirm header handling and delimiter settings.
  • If the error persists, inspect the browser console for the exact parsing or DuckDB error.

Queries are slow or memory-heavy

  • Start with a smaller sample using LIMIT.
  • Filter early and aggregate before exporting very large result sets.
  • Close other browser tabs to free memory.
  • If possible, work from Parquet instead of raw CSV for the largest inputs.

Tables or autocomplete look out of date

  • Check the Database section to confirm the table was created successfully.
  • Run the query again after table-creating SQL so the schema refresh completes.
  • Try typing part of a table or column name and then press Ctrl + Space to reopen suggestions.

Import or export problems

  • Database import expects a ZIP backup created by SQL for Files.
  • Use Replace existing tables during import if you want imported tables to overwrite current ones.
  • Use CSV export for query output and ZIP export for a full database backup.

Still stuck?

Open your browser developer tools and check the Console tab. Parsing errors, DuckDB SQL errors, and import issues usually show the most helpful details there.

You can also write to info@sqlforfiles.app.