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

CommandDescription
.helpShow all available commands
.tablesList all tables in the database
.schema <table>Show the schema of a specific table
.examplesShow example SQL queries

Display Commands

CommandDescription
.clearClear the terminal screen
.mode table|csv|tsv|jsonSet the output format
.pagesize <n>Set pagination size (0 to disable)
.timer on|offToggle query execution timing
.highlight on|offToggle syntax highlighting
.links on|offToggle clickable URL detection
.theme dark|light|...Switch color theme
.prompt [primary] [cont]Customize the command prompt

Data Commands

CommandDescription
.copyCopy last query results to clipboard
.download [filename]Download results as a file
.files [list|add|remove]Manage loaded files
.openOpen file picker to load data files

System Commands

CommandDescription
.clearhistoryClear command history
.clearmodelsRemove the downloaded AI models from the browser
.resetReset database and all settings

Visualization Commands

CommandDescription
.chart [options]Show interactive chart of last query result

AI Commands

CommandDescription
.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

KeyAction
EnterExecute command/SQL
TabAuto-complete
↑ / ↓Navigate command history
← / →Move cursor
HomeMove to start of line
EndMove to end of line
BackspaceDelete character before cursor
DeleteDelete character at cursor
Ctrl+AMove to start of line
Ctrl+EMove to end of line
Ctrl+KClear from cursor to end of line
Ctrl+UClear entire line
Ctrl+VPaste from clipboard
Ctrl+CCancel current input or running query

Pagination Mode

When viewing paginated results, these shortcuts are available:

KeyAction
n / ↓ / EnterNext page
p / ↑Previous page
q / Escape / Ctrl+CQuit pagination

Chart Mode

KeyAction
EscapeClose the chart
Ctrl+S / Cmd+SExport 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 PatternChart TypeExample
Temporal + NumericLineDate + revenue = time series
Categorical + NumericBarCategory + total = bar chart
Two Numeric columnsScatterx_value + y_value = scatter plot
Single Numeric columnHistogramvalue = distribution
Multiple Numeric columnsLinecol1, 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

Query Sharing

Share SQL queries via URL to collaborate with others. When someone opens a shared link, the queries execute automatically in the terminal.

Opening the Share Modal

There are two ways to open the sharing modal:

  • Press Ctrl+Shift+S (or Cmd+Shift+S on Mac)
  • Click the share button in the sidebar (desktop) or mobile action bar

Selecting Queries

The modal displays your recent SQL queries from history. Dot commands (like .help) are excluded since they are terminal-specific.

  1. Navigate the list using arrow keys or mouse
  2. Press Space or click to select/deselect queries
  3. Watch the character counter to stay within the 2000 character URL limit
  4. Selected queries will execute in order (oldest first) when the link is opened

Note: The URL length is limited to 2000 characters for maximum browser compatibility. Complex queries may need to be simplified or split.

Copying the Link

Once you've selected queries:

  • Press Enter to copy the shareable link to clipboard
  • Or click the "Copy shareable link" button

The modal closes automatically after copying.

Receiving Shared Links

When someone opens a shared URL:

  1. The terminal loads normally with the welcome message
  2. After initialization, the shared queries execute automatically
  3. Each query is displayed with its output
  4. The URL is cleared to prevent re-execution on page refresh

Keyboard Shortcuts

KeyAction
↑ / ↓Navigate query list
SpaceSelect/deselect query
EnterCopy shareable link and close
EscapeClose modal without copying

URL Format

Shared URLs use a hash-based format with Base64-encoded queries:

https://duckdb-terminal.com/#$queries=v1,ENCODED_QUERY_1,ENCODED_QUERY_2
  • The v1 prefix indicates the URL format version
  • Each query is URL-safe Base64 encoded (no special characters)
  • Queries are separated by commas

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.

#ModelHugging Face repositorySize
1Qwen3.5 0.8B (Q4_0)ggml-org/Qwen3.5-0.8B-GGUF537 MiB
2MiniCPM5 1B (Q4_K_M)openbmb/MiniCPM5-1B-GGUF656 MiB
3Qwen3.5 2B (Q4_K_XL)unsloth/Qwen3.5-2B-GGUF1278 MiB
4Qwen3.5 4B (Q4_K_XL)unsloth/Qwen3.5-4B-GGUF2777 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 runs ATTACH ... (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 .reset starts a new one.
  • Ctrl+C stops the model.

AI Commands

CommandDescription
.model [1-4]Choose, download, and select a local AI model
.clearmodelsRemove 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 .model and .ai explain 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

Dark (default) - VS Code dark theme
Light - Clean light theme
Tokyo Night - Popular dark theme with purple accents
Dracula - Dark theme with vibrant colors
Solarized Dark - Low-contrast dark theme

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.