Appearance

Get Started ​

Mosaic can be imported for use in JavaScript projects, leveraged within Jupyter notebooks, or deployed alongside a standalone DuckDB server.

Use in JavaScript ​

Include the desired Mosaic libraries in your project dependencies and import them as part of your application. For a working standalone example, take a look at the Cross-Filter Flights 10M notebook on Observable.

The snippet below imports vgplot, configures the coordinator to use DuckDB-WASM, and creates a plot with a single areaY mark to produce a time-series chart for the database table "stocks". To access the central coordinator, use the coordinator() method, which is exported by Mosaic core and also re-exported by Mosaic vgplot.

js
import * as vg from "@uwdata/vgplot";

// configure the coordinator to use DuckDB-WASM
// creates a new database instance running in-browser
vg.coordinator().databaseConnector(vg.wasmConnector());

// load data into the database
// executes a query generated by the loadCSV helper
vg.coordinator().exec(vg.loadCSV("stocks", "stock-data.csv"));

// create an area chart, returned as an HTML element
// you can subsequently add this to your webpage
const chart = vg.plot(
  vg.areaY(vg.from("stocks"), { x: "Date", y: "Price" })
);

Use in Python + Jupyter ​

To create scalable visualizations within Jupyter notebooks, you can use Mosaic vgplot specifications in either YAML or JSON format. See the Jupyter widget docs for more. In the future we hope to also support a Python API, not unlike Vega Altair.

Deploy in Observable Framework ​

Mosaic-powered visualizations can be in deployed dashboards or data apps published with Observable Framework. For guidance on deploying Mosaic and using DuckDB to prepare data, see the Mosaic + Framework example site.

Run and develop locally ​

To run Mosaic examples on a local DuckDB server or work on Mosaic development, make a local clone of the Mosaic GitHub repository.

Installation ​

For local installation you should have npm and node version 18 or higher.

Run Examples ​

After installation, you can run examples locally, using either DuckDB-WASM or a DuckDB server to load and process data.

  • Run npm run dev to launch a local web server and view examples. By default, the examples use DuckDB-WASM in the browser. The socket and rest connectors will only work if a local DuckDB server is running. For greater performance, launch and connect to a local DuckDB server as described below below.

To launch a local DuckDB server:

  • Install hatch, if not already present.
  • Run npm run server to launch the duckdb-server. This runs the server in development mode, so the server will restart if you change its code.