Virtual Servers

A Virtual Server allows Perspective to query external data sources (such as DuckDB or ClickHouse) without loading the entire dataset into Perspective’s built-in data engine. Instead, Perspective translates its query operations (group by, sort, filter, etc.) into queries the external data source can execute natively, and only transfers the data needed for the current view.

The Virtual Server API works on any platform that has a Perspective Client — including JavaScript (both Node.js and the browser via WebAssembly), Python, and Rust. In the browser, this means a virtual server can front a WASM-based engine like @duckdb/duckdb-wasm, giving <perspective-viewer> the ability to query a database running entirely client-side without loading data into Perspective’s own engine.

This is useful when:

• The dataset is too large to fit in browser memory or a single process.
• Data already lives in a database and you want to avoid duplicating it.
• You want to leverage a database’s native query optimizations.
• A WASM build of the data source is available in the browser (e.g. @duckdb/duckdb-wasm) and you want to query it directly.

How it works

A virtual server implements a handler interface that Perspective calls to satisfy Table and View operations. The handler translates Perspective’s view configuration into the external system’s query language (typically SQL), executes the query, and returns the results as columnar data. Because the handler speaks the standard Perspective Client protocol, it can run anywhere a Client can — in-process, in a WebWorker, or on a remote server.

┌──────────────────────────────────────────────────┐
│  <perspective-viewer>                            │
└──┬───────────────────────────────────────────────┘
   │   ┌──────────────────────────────────────────────────┐
   └──►│  Perspective Virtual Server Handler              │
       └──┬───────────────────────────────────────────────┘
          │   ┌──────────────────────────────────────────────────┐
          └──►│  External DB (DuckDB, ClickHouse, …).            │
              └──────────────────────────────────────────────────┘

The viewer communicates with the virtual server handler the same way it would with a regular Perspective server. The handler advertises its capabilities (which operations it supports) via a features object, and the viewer UI adapts accordingly — disabling controls for unsupported operations.

Built-in implementations

Perspective ships with virtual server implementations for:

• DuckDB — query DuckDB databases in-browser via WASM (JavaScript) or server-side (Python).
• ClickHouse — query a ClickHouse server from the browser (JavaScript) or from Python (Python).

Custom implementations

You can implement your own virtual server to connect Perspective to any data source. See the language-specific guides:

• JavaScript: Implementing a custom Virtual Server
• Python: Implementing a custom Virtual Server

Features declaration

The get_features() / getFeatures() method returns an object that tells Perspective which query operations the virtual server supports. The viewer will only show controls for supported operations: