Documentation

Getting Started

Follow these simple steps to start querying your files:

1. Upload your CSV, JSON, or Parquet files using the file uploader
2. Your files will automatically be converted to database tables
3. Expand the table list card to view the schema (column names and types) for each table
4. Write SQL queries in the editor
5. Click "Run Query" or press Ctrl+Enter to execute
6. View your results in the table below

Supported File Formats

CSV Files

Comma-separated values files are automatically parsed. The first row is used as column names.

JSON Files

Both line-delimited JSON (NDJSON) and standard JSON arrays are supported.

Parquet Files

Apache Parquet files are natively supported for efficient columnar data processing.

Query History

SQL for Files automatically saves your query history to help you track and reuse your work:

• Auto-save: Every query you execute is automatically saved to your browser's local storage
• Quick access: Click the "History" button next to the Run Query button to view all saved queries
• Load queries: Click any query in the history to load it back into the editor
• Status tracking: See success/error status and row counts for each executed query
• Download queries: Save any query as a .sql file for sharing or backup
• Clear history: Remove individual queries or clear all history at once

Database Export & Import

Save your work and restore it later using the database export/import feature:

Export Database

• Click the "Export" button in the Tables section to download all your tables
• Creates a ZIP file containing all table data in csv format
• Includes metadata with table schemas, column types, and row counts
• Perfect for backing up your work or sharing datasets with others

Import Database

• Click the "Import" button to restore a previously exported database
• Select the ZIP file you exported earlier
• All tables and data will be automatically recreated
• Original files are stored in browser storage for persistence

Table Preview

Quickly preview table contents without writing a query:

• Click the eye icon next to any table name in the Tables list
• Automatically runs SELECT * FROM table LIMIT 10
• Great for quickly inspecting table structure and sample data

Keyboard Shortcuts

• Ctrl+Enter (or Cmd+Enter on Mac) - Execute query or selected text
• Ctrl+/ - Toggle comment (in editor)
• Escape - Close query history dropdown

Tips & Best Practices

• Table names are automatically derived from your file names. If a file name starts with a number, the prefix 'table_' is automatically added (e.g., '2023_sales.csv' becomes 'table_2023_sales')
• Query results are limited to displaying 1000 rows in the UI for performance, but CSV exports include all rows from your query
• All processing happens in your browser - your data stays private
• Use LIMIT to preview large datasets before running complex queries
• DuckDB supports advanced SQL features like window functions and CTEs

Memory & Performance Limits

SQL for Files runs entirely in your browser for privacy and convenience, but this comes with memory constraints:

How We Handle Large Results

• Display Optimization: Only the first 1,000 rows are converted to JavaScript objects and displayed in the table. This keeps the UI responsive even with large query results.
• Full Data Export: When you export to CSV, all rows from your query are included, not just the displayed 1,000.
• Automatic Warnings: The console will warn you when results exceed 100,000 rows and alert you about potential memory issues when results exceed 1,000,000 rows.

Best Practices for Large Files

• Start Small: Test your queries with LIMIT 100 first to verify correctness before running on the full dataset
• Use Aggregations: Instead of retrieving all rows, use GROUP BY, COUNT, and other aggregations to summarize data
• Filter Early: Use WHERE clauses to reduce the result set before processing
• Parquet Format: For files over 100MB, use Parquet format which is more memory-efficient than CSV or JSON
• Watch File Sizes: Files over 200MB may cause performance issues. Consider splitting them or using aggregations

SQL Examples

Basic Query

SELECT * FROM your_table LIMIT 10;

Filtering Data

SELECT name, age, city
FROM users
WHERE age > 25
ORDER BY name;

Aggregations

SELECT
  country,
  COUNT(*) as total_users,
  AVG(age) as avg_age
FROM users
GROUP BY country
ORDER BY total_users DESC;

Joining Tables

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;

Frequently Asked Questions (FAQ)

Troubleshooting