DuckDB Virtual Server

Perspective provides a built-in virtual server for DuckDB, allowing <perspective-viewer> clients to query a server-side DuckDB database over WebSocket.

For browser-only usage via DuckDB-WASM, see the JavaScript DuckDB guide.

Installation

pip install perspective-python duckdb

Usage

Create a server that exposes a DuckDB database to browser clients:

import duckdb
import tornado.web
import tornado.ioloop
from perspective import DuckDBVirtualServer
from perspective.handlers.tornado import PerspectiveTornadoHandler

# Create DuckDB connection and load data
conn = duckdb.connect()
conn.execute("CREATE TABLE my_table AS SELECT * FROM 'data.parquet'")

# Create virtual server backed by DuckDB
server = DuckDBVirtualServer(conn)

# Serve over WebSocket
app = tornado.web.Application([
    (r"/websocket", PerspectiveTornadoHandler, {"perspective_server": server}),
])

app.listen(8080)
tornado.ioloop.IOLoop.current().start()

Connect from the browser:

const websocket = await perspective.websocket("ws://localhost:8080/websocket");
const table = await websocket.open_table("my_table");
document.getElementById("viewer").load(table);

Supported features

The DuckDB virtual server supports:

• group_by — aggregation via DuckDB’s GROUP BY
• split_by — column pivoting
• sort — ordering results
• filter — all standard filter operators
• expressions — computed columns via DuckDB SQL expressions
• Full set of DuckDB aggregate functions (sum, avg, count, min, max, product, string_agg, etc.)

Examples

• Python DuckDB example