DuckDB Terminal User Guide
A browser-based SQL terminal powered by DuckDB WASM and Gespenst. Run SQL queries directly in your browser with interactive charts, multiple themes, and data export.
Getting Started
DuckDB Terminal is a browser-based SQL interface that lets you run queries directly in your web browser. It uses DuckDB WASM for query execution and Gespenst for terminal emulation, powered by Ghostty VT.
Key Features
- Full SQL Support - Execute any DuckDB-compatible SQL query
- Command History - Navigate previous commands with arrow keys (persisted across sessions)
- Auto-Complete - Tab completion for SQL keywords, table names, and functions
- Multiple Output Formats - Table, CSV, TSV, or JSON output
- Interactive Charts - Visualize query results with auto-detected chart types
- Query Sharing - Share SQL queries via URL for collaboration
- Local AI Assistant - Ask questions about your data with a language model that runs in your browser
- File Loading - Load CSV, Parquet, and JSON files via drag-and-drop
- Syntax Highlighting - Color-coded SQL for better readability
Your First Query
When you open the terminal, you'll see the duck prompt (🦆). Simply type a SQL query and press Enter to execute:
SELECT 'Hello, DuckDB!' AS greeting;
The result will be displayed in a formatted table below your query.
Tip: Use Tab for auto-completion. Start typing a SQL keyword or table name and press Tab to see suggestions.
Multi-line Input
For complex queries, you can write SQL across multiple lines. The terminal detects incomplete statements and shows a continuation prompt ( >) until you complete the query with a semicolon:
SELECT
id,
name,
email
FROM users
WHERE active = true
ORDER BY name;
Multithreading
DuckDB Terminal starts with the smaller single-threaded DuckDB-Wasm bundle by default. This avoids downloading the larger experimental threaded build when it is not needed.
Thread support is selected when the database starts, so SET threads = 4 cannot enable it in a single-threaded build. An embedding application must opt in with a COI bundle and a maximumThreads value, and serve the page and bundle assets with cross-origin isolation enabled.
Hosted demo: This site intentionally uses one DuckDB thread so Parquet and other dynamically loaded extensions remain available. The page is cross-origin isolated only so the AI assistant can use several CPU threads. Multithreading remains an explicit library option while threaded extension loading is incompatible upstream.
Terminal Commands
Terminal commands start with a dot (.) and provide various utilities. Type .help to see all available commands.
Information Commands
| Command | Description |
|---|---|
.help | Show all available commands |
.tables | List all tables in the database |
.schema <table> | Show the schema of a specific table |
.examples | Show example SQL queries |
Display Commands
| Command | Description |
|---|---|
.clear | Clear the terminal screen |
.mode table|csv|tsv|json | Set the output format |
.pagesize <n> | Set pagination size (0 to disable) |
.timer on|off | Toggle query execution timing |
.highlight on|off | Toggle syntax highlighting |
.links on|off | Toggle clickable URL detection |
.theme dark|light|... | Switch color theme |
.prompt [primary] [cont] | Customize the command prompt |
Data Commands
| Command | Description |
|---|---|
.copy | Copy last query results to clipboard |
.download [filename] | Download results as a file |
.files [list|add|remove] | Manage loaded files |
.open | Open file picker to load data files |
System Commands
| Command | Description |
|---|---|
.clearhistory | Clear command history |
.clearmodels | Remove the downloaded AI models from the browser |
.reset | Reset database and all settings |
Visualization Commands
| Command | Description |
|---|---|
.chart [options] | Show interactive chart of last query result |
AI Commands
| Command | Description |
|---|---|
.model [1-4] | Choose, download, and select a local AI model |
.ai <prompt> | Ask the selected local AI model about your data |
Keyboard Shortcuts
Navigation & Editing
| Key | Action |
|---|---|
| Enter | Execute command/SQL |
| Tab | Auto-complete |
| ↑ / ↓ | Navigate command history |
| ← / → | Move cursor |
| Home | Move to start of line |
| End | Move to end of line |
| Backspace | Delete character before cursor |
| Delete | Delete character at cursor |
| Ctrl+A | Move to start of line |
| Ctrl+E | Move to end of line |
| Ctrl+K | Clear from cursor to end of line |
| Ctrl+U | Clear entire line |
| Ctrl+V | Paste from clipboard |
| Ctrl+C | Cancel current input or running query |
Pagination Mode
When viewing paginated results, these shortcuts are available:
| Key | Action |
|---|---|
| n / ↓ / Enter | Next page |
| p / ↑ | Previous page |
| q / Escape / Ctrl+C | Quit pagination |
Chart Mode
| Key | Action |
|---|---|
| Escape | Close the chart |
| Ctrl+S / Cmd+S | Export chart as PNG |
Output Modes
Use .mode to switch between output formats. The format affects both display and clipboard/download content.
Table Format (Default)
Human-readable ASCII table with borders:
+----+-------+-------------------+
| id | name | email |
+----+-------+-------------------+
| 1 | Alice | [email protected] |
| 2 | Bob | [email protected] |
+----+-------+-------------------+
CSV Format
Comma-separated values, ideal for spreadsheets:
id,name,email
1,Alice,[email protected]
2,Bob,[email protected]
TSV Format
Tab-separated values for data import:
id name email
1 Alice [email protected]
2 Bob [email protected]
JSON Format
Array of objects for APIs and JSON files:
[
{"id": 1, "name": "Alice", "email": "[email protected]"},
{"id": 2, "name": "Bob", "email": "[email protected]"}
]
Copying & Downloading
After running a query:
.copy- Copy results to clipboard in current format.download- Download as file (extension matches format).download mydata- Download with custom filename
Pagination
For large result sets, enable pagination:
.pagesize 50 -- Show 50 rows per page
.pagesize 0 -- Disable pagination
Note: Queries with explicit LIMIT or OFFSET bypass pagination.
Working with Files
DuckDB Terminal supports loading data files directly in your browser.
Supported Formats
- CSV - Comma-separated values
- Parquet - Columnar storage format
- JSON - JSON files and JSON Lines
Loading Files
There are two ways to load files:
Drag and Drop
Simply drag a file from your computer and drop it onto the terminal. The file will be registered and you can query it immediately.
File Picker
Use the .open command to open a file picker dialog.
Querying Loaded Files
Once loaded, files are accessible by their filename:
SELECT * FROM 'sales.csv' LIMIT 10;
SELECT category, SUM(amount)
FROM 'transactions.parquet'
GROUP BY category;
Managing Files
.files list -- Show all loaded files
.files add -- Open file picker
.files remove -- Remove a loaded file
Charts & Visualization
Visualize query results with interactive charts powered by uPlot.
Basic Usage
Run a query, then use .chart to visualize:
SELECT date, revenue, cost FROM sales;
.chart
Auto-Detected Chart Types
| Data Pattern | Chart Type | Example |
|---|---|---|
| Temporal + Numeric | Line | Date + revenue = time series |
| Categorical + Numeric | Bar | Category + total = bar chart |
| Two Numeric columns | Scatter | x_value + y_value = scatter plot |
| Single Numeric column | Histogram | value = distribution |
| Multiple Numeric columns | Line | col1, col2, col3 = multi-series |
Chart Options
.chart type=bar -- Force bar chart
.chart x=date -- Specify X-axis column
.chart y=revenue,cost -- Specify Y-axis columns
.chart export -- Export as PNG
Example: Time Series
SELECT
DATE '2024-01-01' + INTERVAL (i) DAY AS date,
100 + random() * 50 AS revenue,
80 + random() * 30 AS cost
FROM generate_series(0, 30) AS t(i);
.chart
Example: Bar Chart
SELECT category, SUM(amount) as total
FROM (VALUES
('Electronics', 1500),
('Clothing', 800),
('Food', 1200),
('Books', 400)
) AS t(category, amount)
GROUP BY category;
.chart
Example: Histogram
SELECT (random() * 100)::INTEGER AS value
FROM generate_series(1, 200);
.chart
Local AI Assistant
Ask questions about your data in plain language. A small language model runs entirely in your browser with wllama (llama.cpp compiled to WebAssembly, accelerated with WebGPU): there is no server and no API key, and your data never leaves the page. The setup follows the duckdb-wasm-shell-wllama demo.
Choosing a Model
Run .model to list the models, pick one, and confirm the download:
.model
Local AI models (run in your browser with wllama)
1. Qwen3.5 0.8B (Q4_0) 537 MiB
2. MiniCPM5 1B (Q4_K_M) 656 MiB
3. Qwen3.5 2B (Q4_K_XL) 1278 MiB
4. Qwen3.5 4B (Q4_K_XL) 2777 MiB
Select a model (1-4): 1
Do you want to install the selected model (size 537 MiB) in your browser (yes/no) yes
Installed Qwen3.5 0.8B (Q4_0). Ask it with .ai <prompt>
Each model is downloaded once from the Hugging Face Hub and cached in your browser. Picking a model that is already installed switches to it without asking. .model 2 skips the menu, and Ctrl+C cancels a download. .clearmodels lists the downloaded models, including interrupted downloads, and removes them after you confirm.
| # | Model | Hugging Face repository | Size |
|---|---|---|---|
| 1 | Qwen3.5 0.8B (Q4_0) | ggml-org/Qwen3.5-0.8B-GGUF | 537 MiB |
| 2 | MiniCPM5 1B (Q4_K_M) | openbmb/MiniCPM5-1B-GGUF | 656 MiB |
| 3 | Qwen3.5 2B (Q4_K_XL) | unsloth/Qwen3.5-2B-GGUF | 1278 MiB |
| 4 | Qwen3.5 4B (Q4_K_XL) | unsloth/Qwen3.5-4B-GGUF | 2777 MiB |
All four models are Apache-2.0 licensed. Larger models give better answers but need more GPU memory, so start with the smallest.
Asking Questions
CREATE TABLE orders AS SELECT * FROM 'orders.csv';
.ai Which customer spent the most in total?
The terminal streams the model's reasoning (dimmed, under "Thinking") and then its answer. To answer, the model can run SQL: each statement and its result appear in the terminal like a query you typed, the statement is added to your history, and the result can be copied, downloaded, or charted. It can also search the DuckDB documentation that ships with the terminal; the sections it reads are listed with their duckdb.org links.
- The model's statements run without asking, including ones that change data or schema. Keep a copy of data you cannot recreate, especially in a persistent (OPFS) database.
- The current schema is sent with every prompt, and the model sees at most 50 rows of each result.
- Questions can name files on the web (Parquet, CSV, or JSON URLs); the terminal describes their columns to the model like loaded tables. For a DuckDB database URL (
.duckdb,.ddb,.db), the model runsATTACH ... (READ_ONLY)itself and then queries its tables. The server must allow CORS (and range requests, for Parquet and database files). - Follow-up prompts continue the conversation. Switching models or running
.resetstarts a new one. - Ctrl+C stops the model.
AI Commands
| Command | Description |
|---|---|
.model [1-4] | Choose, download, and select a local AI model |
.clearmodels | Remove the downloaded models from the browser |
.ai <prompt> | Ask the selected model about your data |
Requirements:
- WebGPU for usable speed: current Chrome, Edge, and Safari. Without it the model runs on the CPU, which is much slower. Firefox runs the model on the CPU, because its WebGPU waits about 100 ms for each GPU synchronization (Mozilla bug 1870699). The first answer takes a few minutes there, mostly reading the prompt; Chrome, Edge, or Safari answer in seconds.
- Not on iPhone and iPad: every browser there uses WebKit, which gives a tab too little memory. Loading even the smallest model briefly takes about 3 GB, and the tab crashes, so
.modeland.aiexplain this instead of loading a model. - Browser storage (Origin Private File System) for the model cache, which some private browsing modes do not provide.
- Disk space and GPU memory for the selected model.
Themes
DuckDB Terminal includes five color themes. Switch using the settings dropdown in the sidebar or the .theme command.
Available Themes
Switching Themes
.theme dark
.theme light
.theme tokyo-night
.theme dracula
.theme solarized-dark
Note: Theme changes apply immediately without reloading. Your terminal output, pending input, command history, and database are preserved.
SQL Basics
Here are some common SQL operations to get you started.
Creating Tables
CREATE TABLE users (
id INTEGER PRIMARY KEY,
name VARCHAR,
email VARCHAR,
created_at TIMESTAMP DEFAULT current_timestamp
);
Inserting Data
INSERT INTO users (id, name, email) VALUES
(1, 'Alice', '[email protected]'),
(2, 'Bob', '[email protected]'),
(3, 'Charlie', '[email protected]');
Querying Data
-- Select all
SELECT * FROM users;
-- With conditions
SELECT name, email
FROM users
WHERE name LIKE 'A%'
ORDER BY name;
-- With limit
SELECT * FROM users LIMIT 10;
Joins
SELECT
u.name,
o.order_date,
o.total
FROM users u
JOIN orders o ON u.id = o.user_id
WHERE o.total > 100;
DuckDB Features
DuckDB includes many powerful features beyond standard SQL.
Generate Series
-- Generate numbers 1-10
SELECT * FROM generate_series(1, 10);
-- Generate dates
SELECT generate_series(
DATE '2024-01-01',
DATE '2024-12-31',
INTERVAL '1 month'
);
Range Function
SELECT range(10); -- Returns [0,1,2,3,4,5,6,7,8,9]
SELECT range(5, 10); -- Returns [5,6,7,8,9]
Date/Time Functions
SELECT
current_date,
current_timestamp,
date_part('year', current_date) AS year,
date_trunc('month', current_date) AS month_start;
JSON Functions
SELECT
json_extract('{"name": "Alice", "age": 30}', '$.name') AS name,
json_extract_string('{"city": "NYC"}', '$.city') AS city;
String Functions
SELECT
upper('hello') AS upper,
lower('HELLO') AS lower,
concat('Hello', ' ', 'World') AS concat,
substring('Hello World', 1, 5) AS substr;
Window Functions
SELECT
name,
department,
salary,
ROW_NUMBER() OVER (PARTITION BY department ORDER BY salary DESC) AS rank,
AVG(salary) OVER (PARTITION BY department) AS dept_avg
FROM employees;
Data Analysis Patterns
Aggregation
SELECT
category,
COUNT(*) AS count,
SUM(amount) AS total,
AVG(amount) AS average,
MIN(amount) AS min,
MAX(amount) AS max
FROM transactions
GROUP BY category
ORDER BY total DESC;
Pivot Tables
SELECT
region,
SUM(CASE WHEN product = 'A' THEN sales ELSE 0 END) AS product_a,
SUM(CASE WHEN product = 'B' THEN sales ELSE 0 END) AS product_b,
SUM(CASE WHEN product = 'C' THEN sales ELSE 0 END) AS product_c
FROM sales
GROUP BY region;
Common Table Expressions (CTEs)
WITH monthly_sales AS (
SELECT
date_trunc('month', order_date) AS month,
SUM(total) AS revenue
FROM orders
GROUP BY 1
)
SELECT
month,
revenue,
LAG(revenue) OVER (ORDER BY month) AS prev_month,
revenue - LAG(revenue) OVER (ORDER BY month) AS growth
FROM monthly_sales;
Subqueries
SELECT *
FROM products
WHERE price > (
SELECT AVG(price) FROM products
);
External Data
DuckDB can query files directly without importing them first.
CSV Files
-- Query local file (after drag-drop or .open)
SELECT * FROM 'sales_data.csv';
-- With options
SELECT * FROM read_csv('data.csv', header=true, delim=',');
Parquet Files
-- Query parquet directly
SELECT * FROM 'analytics.parquet';
-- With column selection (efficient - only reads needed columns)
SELECT date, revenue
FROM 'large_dataset.parquet'
WHERE date >= '2024-01-01';
JSON Files
-- Query JSON array
SELECT * FROM 'users.json';
-- JSON Lines format
SELECT * FROM read_json('logs.jsonl', format='newline_delimited');
HTTP/HTTPS Files
-- Query remote CSV
SELECT * FROM 'https://example.com/data.csv';
-- Query remote Parquet
SELECT * FROM 'https://example.com/dataset.parquet';
Note: Remote file access requires CORS headers from the server. Some public datasets may not be accessible due to CORS restrictions.
Extensions
DuckDB-Wasm can load compatible extensions at runtime. In the browser, INSTALL does not persist an extension across sessions; LOAD fetches and loads the matching Wasm extension for the current DuckDB build.
INSTALL iceberg;
LOAD iceberg;
Inspect the extension catalog and the state of each extension with:
SELECT extension_name, installed, loaded
FROM duckdb_extensions()
ORDER BY extension_name;
Compatibility: Catalog entries can vary by DuckDB version, and not every native DuckDB extension has a compatible Wasm build. A load can also fail when an extension does not match the current Wasm ABI.
Apache Iceberg
After loading the Iceberg extension, you can query a table directly and inspect its snapshots:
SELECT *
FROM iceberg_scan('s3://my-bucket/warehouse/db/table');
SELECT *
FROM iceberg_snapshots('s3://my-bucket/warehouse/db/table');
Cloud Storage (S3 / R2)
DuckDB-Wasm can query objects in Amazon S3 and S3-compatible storage such as Cloudflare R2 directly from the browser. Private objects require a temporary DuckDB secret.
Amazon S3
CREATE SECRET (
TYPE s3,
PROVIDER config,
KEY_ID 'AKIA...',
SECRET '...',
REGION 'eu-central-1'
);
SELECT *
FROM read_parquet('s3://my-bucket/data/*.parquet');
Cloudflare R2
CREATE SECRET (
TYPE r2,
PROVIDER config,
KEY_ID '...',
SECRET '...',
ACCOUNT_ID '...'
);
SELECT *
FROM read_parquet('r2://my-bucket/data.parquet');
Browser access: Configure the bucket's CORS policy to allow requests from this site's origin, including the headers and HTTP Range requests required by the object store. Use short-lived, least-privilege credentials.
CREATE SECRET creates a temporary, in-memory secret by default. In the hosted terminal it lasts only for the current DuckDB instance and is discarded when the page is reloaded.
Memory Limit
DuckDB-Wasm has a finite WebAssembly memory budget. The exact default depends on the browser and build, so query the current value before changing it:
-- Check the current limit
SELECT current_setting('memory_limit');
-- Lower it for this DuckDB instance
SET memory_limit = '1GB';
Lowering the limit provides a guardrail for memory-intensive queries. Queries that exceed it fail with an Out of Memory Error instead of continuing to grow DuckDB's managed memory.
Storage: The hosted terminal opens an in-memory database. Applications embedding the library can instead opt into persistent OPFS storage with the storage and databasePath options.