On this page
RawQL documentation
Query local files with DuckDB, develop dbt models, and turn results into notebooks, charts and dashboards. This guide covers the editor, from your first import to saving and versioning your work.
RawQL is in invite-only beta. These guides and sample files are public and readable on mobile. You need beta access to run the examples in the editor. A desktop browser is recommended for the best editing experience, but you can continue on mobile.
Choose a guide
Capy Agent
Create SQL files, charts, dashboards and notebooks with workspace data.
Link local workspaces
Link .rawql files or folders and switch projects without importing inactive archives.
Query CSV with SQL
Filter orders, aggregate revenue and join customers.
Explore Parquet files
Inspect column types, select fields and group results.
Work with Excel
Query a worksheet and clean numeric values.
Classify text with Jev
Classify descriptions, detect interaction and score text.
prompt_jev to classify text, estimate a yes/no probability or score rows. Review the texts and questions before enabling Jev for the editor session: these inputs are sent for remote AI processing. Read about costs, saving results and SQL limits.1 Open your workspace
Request beta access or sign in with your account email and code. Access follows your account; the files and queries in a browser workspace do not sync to another device.
The navigation rail opens Workspaces for documents, Databases for data and schemas, Marketplace for public datasets, Version control for local document history, and Capy Agent for AI assistance. Query history and palette controls are also on the rail.
2 Import a local file
Open Databases → Add local sources, then choose Add files or Add folder. Chrome and Edge link CSV, JSON, Parquet, XLSX and XLS sources on disk, preserving folders and subfolders. Other browsers import copies, up to 10 copied files and 100 MiB per file. Device memory affects what you can query comfortably. The URL section imports public CSV or JSON files.
RawQL creates a view over each imported file. Punctuation in the filename becomes underscores: orders.csv appears as orders_csv. Look in the catalog for the actual name and column types. Imported file contents stay on your device.
Excel sheets and linked sources
For Excel, preview and select one or more sheets, choose a header row or no header, optionally set a cell range, and confirm each SQL name with Import selected sheets. Each selected sheet counts as one copied file. Formula values come from the saved workbook; RawQL does not recalculate Excel formulas. See the Excel guide for a worked example.
Use a linked source’s menu to Refresh source after changing files on disk, or Reconnect source when permission needs renewing. Removing a connection leaves the original files on disk.
Local DuckDB databases
Add database attaches a .duckdb file in read-only mode, or in read-and-write mode when your browser supports file permissions. Read-and-write access can change the original database. Browsers that import copies support read-only databases. The catalog also lets you create databases and schemas, open table previews, and insert quoted object names into SQL.
Explore the Marketplace
Open Marketplace to search public datasets and filter by source, format or category. Use Query the catalog to explore the catalog itself with SQL.
Only the catalog loads automatically. Importing a dataset downloads it on request; advanced sources open a SQL starter for you to review and run. Remote requests depend on the source’s availability and browser access rules. Once imported, ordinary SQL processing happens locally.
3 Run your first query
Download the sample orders CSV, import it, then open a SQL file under Workspaces. Run this query:
SELECT * FROM orders_csv
ORDER BY order_id
LIMIT 10;The sample contains six fictional orders. Use Run query for the selected SQL or the statement at your cursor. Use Run all when a script contains several statements that must run in sequence.
Select the intended database and schema before running SQL. The editor completes SQL keywords, catalog objects and columns, and provides Format SQL and Copy SQL. You can cancel a running query from the results panel.
Organize documents and panes
Files and folders
Use the create menu in Workspaces or the plus button beside the tabs to add SQL, YAML and Markdown files, notebooks, dashboards or dbt projects. Group documents in folders. File menus offer rename, duplicate, copy, move, download and delete; closing a tab keeps its document.
Panes, focus and themes
Tab menus offer Split right and Split down for supported documents. Resize the sidebar, split panes and SQL/results divider, or use Focus mode for more editing space. Palettes provides built-in and custom editor palettes; the theme control switches between light and dark.
Combine SQL and notes in notebooks
Cells and notes
Create a Notebook to keep SQL cells and Markdown explanations together. Name cells, drag them into order, collapse them, or add and delete cells. Each SQL cell selects its own database and schema and has its own result view.
Run cells in order
Run a cell, all cells, all cells above, or the selected cell and those below it. SQL cells execute in order and execution stops at the first error. Previous outputs for the targeted cells are cleared when a run begins. The inspector provides an outline and searchable column profiles for the selected result.
Export and Python limits
Notebook options include favorites, duplication, expanding or collapsing all cells, and clearing results. Download a notebook as .ipynb from its file menu to preserve cell text and metadata. Python cells support editing only: execute exported Python code in a suitable external environment. A .rawql snapshot also preserves the editable notebook; live cell results are not restored.
4 Inspect and export results
Explore rows and profiles
Use the result grid to sort retained rows, search values, choose visible columns and inspect a selected cell. JSON values open an interactive viewer with tree, text and graph views, search, and SVG/PNG graph export. Query details describes the returned data; Query Profile shows the recorded execution plan and measurements when available. Select an operator or a SQL fragment to explore their relationship. Expand results to fullscreen when you need more space.
A Column profile in the database explorer helps check types, missing values, distinct values and distributions. Grid search, sorting and statistics cover retained rows; use SQL filters, ORDER BY and aggregates for an answer over the whole source.
Export CSV, TSV and JSON
Open Download results for CSV, TSV or JSON. In ordinary SQL worksheets, CSV and TSV rerun the original SQL against current sources and export its full result without grid filters. JSON downloads filtered retained rows and visible columns. A changed source or volatile query can therefore produce a different CSV or TSV from the displayed grid.
Query history
Query history keeps the last 50 queries in this session, including failures, context and execution measurements. Selecting an entry restores its SQL and opens its saved profile without rerunning it. This execution history is separate from document commits in Version control.
Charts and dashboards
After running a worksheet or notebook cell, open Chart to create a visualization from its executed SQL. Choose Result to plot the source rows, or Summarize to group and aggregate the full SQL result in DuckDB. A LIMIT already in your source SQL still limits that source. Adding a chart to a dashboard preserves its analysis instead of aggregating its displayed points again.
Charts, pivots and preparation
Charts include bars (vertical or horizontal), line, area, pie, donut, scatter, combo, funnel, heatmap, sankey, box, histogram, waterfall, gantt, forecast line and maps. A Pivot and a custom visualization view are also available; dashboard KPI and table widgets use the same analytical results. Pie and donut require nonnegative values and a positive total. Large integers and decimals remain exact in tooltips and the equivalent data table; plotted coordinates can be rounded and long axis labels use scientific notation.
Configure dimensions, measures, filters, sorting and Top N in the analysis builder. Time grains and date settings control temporal grouping. Pivot provides row and column dimensions, measures and totals. Named SQL source parameters and their defaults belong to the saved analytical source; check parameter values and the time zone before refreshing an analysis.
For raw observations, use the preparation controls to calculate box-plot statistics, histogram bins, waterfall steps or pivot aggregates locally. Forecast charts display supplied prediction and bound columns; choosing that chart does not train a forecasting model.
Sources and SQL parameters
A dashboard can use several saved SQL sources. Each source captures its SQL, parameters, database context and time zone. Editing the original worksheet does not change the dashboard source automatically. Use Manage sources to validate or update it deliberately. Analytical refreshes permit local data only and do not call Jev or fetch remote files.
A named source parameter uses a placeholder such as :status in WHERE status = :status. Declare its type and default in the source editor, then supply values when running or bind a dashboard filter to it. Parameter values are separate from filters applied to the source’s returned columns.
Pages and widget layout
Use View to read, Edit to arrange widgets, and Presentation for fullscreen. Edit mode provides keyboard controls for moving, resizing and changing reading order. Small historical tiles keep their saved dimensions; scroll inside them to see the whole chart, controls and data table.
Organize a dashboard into pages using the page tabs. In Edit mode, page actions let you rename, clone, reorder, delete or auto-arrange a page. The Data tab opens the dashboard’s sources.
Combine charts, KPI counters, tables, pivots and rich-text notes. Configure supported charts to cross-filter other widgets through selections. Use the equivalent data table to inspect plotted values, and SVG or PNG export to save a visualization. If creating dashboards is marked Paused in your deployment, existing dashboards remain available.
Filters, refresh and limits
Link a filter to compatible source fields or parameters. Selection is a draft until Apply filters; saving defaults is separate. While a refresh runs, the previous result retains its computed filter labels. A failed tile shows its error without replacing another tile's result. Theme changes, layout edits and SVG/PNG exports do not run SQL.
Current limits include 30 widgets per dashboard, 20,000 analytical output rows and an estimated 8 MiB retained frame. A chart supports up to 50 series, 10,000 marks or 500 pie slices. Use an explicit Top N reduction when needed; intentional reduction and safety truncation are labeled separately. Results use bounded caches and may be evicted. Refresh an evicted preview to calculate it again. These limits do not guarantee a dataset size or response time on your computer.
Develop dbt projects
Projects, templates and sources
Choose dbt project from the create menu, name the project, and start with Palmer penguins, Seattle weather or Jaffle Shop. A top-level folder can also be converted with Convert to dbt project. Open Project settings and sources from the project folder menu to select source relations and configure the DuckDB output profile, target, schema and threads.
dbt runs in your browser with a local DuckDB engine; no local software installation or remote warehouse account is required. SQL worksheets and dbt share the editor’s data catalog. Source relations keep their database and schema; the output profile controls models created in warehouse. Source data is shared, while materialized outputs are restored for each project and branch.
Edit, preview and build
Edit SQL/Jinja, YAML and Markdown in the project tree. Completion and navigation help resolve model references. Use Preview for the current model, selected SQL or a CTE, Compile to inspect generated SQL, and Build, Run or Test for a model and its selected ancestors or descendants.
The command line accepts commands such as dbt build --select my_model. The Project commands menu also exposes run, test, compile, seed, snapshot, ls, debug, freshness, docs generate and clean. Command options include exclusion, full refresh, saved execution state and defer. Defer needs an execution whose saved database is still available.
The project folder menu can show generated target/ files for read-only inspection. These artifacts are excluded from Git. dbt clean removes configured artifacts without deleting warehouse relations; a later build recreates them. The bundled dbt_utils package is available, while installing additional packages with dbt deps is not supported.
Results and performance
The output tabs include Commands, Results, Problems, Code quality, Compiled code, Lineage and Performance. Inspect saved execution logs, SQL, status and measurements, compare executions, select a result model, adjust displayed rows, or export CSV/TSV. Use result in RawQL makes an available current result reusable in the workbench; changed code or sources require a rebuild.
Lineage and documentation
Lineage shows model dependencies and column provenance from compiled SQL. Focus resources, expand the graph and inspect columns. Resource and column documentation edits, including supported unique and not-null tests, save to project YAML; rebuild to refresh generated documentation and tests.
Project settings support rename, duplication, archiving and restoring archived projects. Cached databases and execution results use local browser storage and can be evicted; rebuild when a result is unavailable. Package installation, Python lineage and remote warehouse services are not supported by this workflow.
Version workspace documents locally
Review and commit changes
Open Version control to review a file’s diff, stage selected changes, enter a message and commit. Versioned documents include SQL worksheets, notebooks, YAML/Markdown files, dashboard and visualization definitions, folders and dbt project files. Imported data, database contents, computed results and local dbt profiles are outside those commits.
Branches, merges and stashes
Version control actions → Branch tools lets you create or switch branches, merge, and stash changes. Resolve conflicting files before committing a merge. Use Compare commits to inspect two saved versions, or restore a file to its last committed content.
Compare and restore versions
Restoring a workspace commit requires a clean working tree and restores documents as uncommitted changes; data tables stay unchanged. Commit, stash or discard existing edits first. This Git history stays local and does not push to GitHub or synchronize devices. Export a workspace snapshot to carry the workspace and its local history with you.
Use Capy Agent and Jev
Capy Agent overview
Capy Agent helps create and edit workspace SQL, charts, dashboards and notebooks. Choose its context and sharing settings, reference files or folders with @, review its changes, and stop a run when needed. The Capy Agent guide explains context, models, Marketplace actions and recovery.
Jev in SQL
Jev adds AI functions such as prompt_jev to SQL for text classification, probability estimates and scoring. It requires session consent and uses credits. Follow the Jev guide for arguments, batching, costs and saving generated values.
Ordinary SQL and file processing stay on your device. These optional AI features send authorized context or selected text and questions for remote processing. Review sharing before using them with sensitive data; see Privacy & local data.
5 Save your workspace
Link and switch workspaces
Work across several local projects? Link .rawql files or folders and switch workspaces using the switch icon in the Workspaces drawer. Inactive archives stay on disk.
Browser storage and autosave
SQL worksheets, notebooks and dashboard definitions are kept in browser localStorage. Imported files and supported DuckDB tables are automatically saved unencrypted in IndexedDB and restored when you reopen this browser workspace. SQL result pages may use temporary IndexedDB storage; dbt databases and run results have a separate local cache. Dashboard results and filter-option lists stay in memory. Clearing workspace data or signing out removes the local workspace and remembered connections, while linked files and downloaded snapshots remain on disk. Signing in on another browser or device restores access, not your data.
Portable workspace snapshots
Before leaving, export results or use Save workspace as in Workspaces to download a .rawql snapshot. Inspect its inventory before restoring it. A snapshot contains data, saved SQL, notebooks, dashboard definitions, dbt projects and local version history, including saved parameter and filter defaults. It excludes live dashboard previews, analytical caches and Jev consent. After import or reload, use Refresh deliberately to recalculate dashboards. SQL that cannot use the restored local data remains inactive until you repair its source.
Current imports accept snapshot format v3. Archives in v1 or v2 must first be opened and exported as v3 with a compatible older RawQL release. Restoring an archive does not execute its saved SQL or notebook cells.
Keyboard shortcuts
Use Ctrl on Windows/Linux or Cmd on macOS. Open Keyboard shortcuts in the editor’s status bar for the available combinations.
- Ctrl / Cmd + Enter
Shift + Enter - Run selected SQL or the statement at the cursor. In a notebook, run selected SQL or the current cell.
- Ctrl / Cmd + Shift + Enter
- Run all SQL in a worksheet. In a notebook, run the current SQL cell.
- Ctrl / Cmd + Shift + F
- Format SQL in the worksheet or current SQL cell.
- Ctrl / Cmd + B
- Toggle the editor sidebar.
- Ctrl / Cmd + Alt + K
- Open the keyboard shortcuts dialog.
When a query fails
- Table not found
- Confirm the file is loaded in this session and use its catalog name.
- Column not found
- Check spelling and quote names with spaces, such as
"Order total". - Unexpected types
- Inspect columns before aggregating. Use
TRY_CASTto find values that cannot be converted. - Large result
- Select only useful columns and add a
LIMITwhile exploring. - Linked source unavailable
- Reconnect the source and grant file access again, then refresh it from Databases.
- dbt results unavailable or stale
- Check Problems and the selected execution. Rebuild after changing code or sources, or when cached results have been evicted.
- Save failed or Memory only
- Use the status bar’s Save a copy action to download a snapshot before closing the tab. Check browser storage availability before relying on automatic saving.
For the SQL dialect, see the DuckDB SQL documentation. See the privacy policy for the distinction between local data and account information.
RawQL