Core Concepts

This page explains the building blocks of DuckViz. Understanding these concepts will help you get the most out of the platform.

DuckDB-WASM

DuckViz uses DuckDB-WASM as its data engine. DuckDB is a high-performance analytical database that runs entirely in your browser via WebAssembly. This means:

• No server needed — SQL queries execute locally on your machine
• No data upload — your files are parsed and queried without leaving the browser
• Full SQL support — DuckDB supports complex SQL including window functions, CTEs, JSON, regex, and more
• Fast — columnar storage engine optimized for analytical queries

When you upload a CSV, Excel, or JSON file, DuckViz parses it off the main thread and creates a DuckDB table. All subsequent queries (for charts, widgets, reports) run against these local tables.

Sessions and persistence

A session represents the state of your current workspace — all ingested files, tables, dashboards, and widgets. DuckViz persists sessions in your browser's IndexedDB:

• Tables are exported as Parquet files and stored in IndexedDB
• Dashboard layouts and widget configurations are stored as JSON
• File metadata (names, sizes, types) is stored alongside the data

This means you can close the tab and come back later — your data and dashboards will be restored exactly as you left them.

To clear a session, use Upload → Start fresh or unmount individual tables from the memory badge in the header.

Tables

Every file you upload becomes a DuckDB table. The table is named after the file. You can:

• View table data in the data grid
• Write SQL queries against any table
• See column types, null counts, and distributions
• Join across multiple tables using standard SQL

For folder uploads, each file becomes its own table — you can query across them using SQL JOIN or UNION ALL BY NAME.

Widgets

A widget is a visualization (chart, insight, or text block) generated from a SQL query. DuckViz has two ways to create widgets:

AI-generated widgets

When you explore a table, the AI widget pipeline:

1. Classifies the data domain (e.g. "Financial Data", "Server Logs", "IoT Metrics")
2. Suggests chart types from a registry of 80+ types (bar, line, scatter, heatmap, network graph, treemap, chord diagram, etc.)
3. Generates a DuckDB SQL query for each chart, with standardized column aliases that match the chart it picked

The AI only sees column names and data types — never your actual data values.

Manual widgets

You can also type a prompt in the chat panel to request specific charts (e.g. "show me a monthly revenue trend") or write raw SQL and pick a chart type yourself.

Dashboards

A dashboard is a named collection of widgets displayed in a 12-column draggable grid. Key features:

• Drag and resize — arrange widgets freely, resize from the bottom-right corner
• Multiple dashboards — create as many as you need, each bound to its data source
• Auto-save — layouts persist automatically
• Insights — AI-written text analysis blocks live in the same grid alongside charts

Every account starts with a default dashboard. Create new ones from the sidebar when you work with different data sources.

Reports

A report is an executive-style document generated from a dashboard. It uses a Notion-style block editor with:

• Live charts — rendered inline as interactive blocks
• AI-written sections — executive summary, analysis, recommendations — streamed in parallel
• Template variables — {{total_revenue}}, {{top_category}} — filled in with live values from your data
• Rich editing — headings, bullet lists, callouts, dividers, drag-and-drop reordering
• Export — PDF, DOCX, and PPTX, all rendered in-browser

Credits

AI features (widget generation, report writing, log format detection) consume credits. Non-AI actions like file uploads, manual SQL queries, and exports are always free.

• New accounts get free credits on sign-up
• Additional credits are available as one-time credit packs — no subscription, no auto-renew
• Credits never expire
• Failed AI requests are refunded automatically

See Credits for details on pricing and per-action costs.