boro

author and compose mosaic clients as anywidgets

install

uv add boro

what

mosaic is an architecture for interactive linked views over millions of rows: clients publish queries, a coordinator manages and cross-filters them against a data source (e.g., duckdb).

vgplot is how you usually author custom mosaic-based visualizations, a bundle with its own grammar and layout. boro is the same client/coordinator architecture, but each client is a standalone anywidget.

primitives

three anywidgets:

• Coordinator — owns a DataSource and the js-side mosaic engine. brokers queries over arrow ipc. headless.
• Selection — wraps a mosaic Selection. value syncs the array of clauses (sql predicates) to python.
• Client — base class. Required coord; conventional filter_by (read side) and target (publish side) selection slots, both boro.SelectionTrait. Subclasses can declare further selection slots with boro.SelectionTrait().

The base accepts a unified selection= shortcut covering all four shapes:

Histogram(c, ..., selection=sel)              # crossfilter (both slots = sel)
Histogram(c, ..., selection=(scope, detail))  # asymmetric pair
Histogram(c, ..., selection=(sel, None))      # read-only (filter only)
Histogram(c, ..., selection=(None, sel))      # publish-only

Explicit filter_by= / target= kwargs override the shortcut.

each client is its own _esm and DOM. the mosaic engine and js deps live once, in the coordinator; clients reach it via host.getWidget(...).

hello world

import boro
import duckdb

con = duckdb.connect()
con.execute("CREATE TABLE flights AS SELECT * FROM read_parquet('flights.parquet')")

c = boro.Coordinator.connect(con)
sel = boro.Selection.crossfilter(c)

Histogram(c, table="flights", column="delay", selection=sel)

Scatter(c, table="flights", x="distance", y="delay", selection=sel)

>>> sel.value
[{'value': [5, 30], 'sql': '"delay" BETWEEN 5 AND 30', 'meta': {...}, 'source': '...'}]

writing a client

import boro
import traitlets


class RowCounter(boro.Client):
    _esm = """
    export default {
      async render({ model, host, signal, el }) {
        el.style.cssText = "font: 14px ui-sans-serif; padding: 6px 8px;";
        el.textContent = "…";
        const coord = await host.getWidget(model.get("coord"));
        const { Query, msql, createClient } = coord.exports;
        const ctx = await createClient({ model, host, signal });
        ctx.liveQuery({
          filterBy: ctx.filterBy,
          query: (filter) =>
            Query.from(model.get("table"))
              .select({ n: msql.count() })
              .where(filter ?? []),
          onResult: (result) => {
            if (!result.isSuccess) {
              return;
            }
            const n = Number(result.data.toColumns().n[0]);
            el.textContent = `${n.toLocaleString()} rows`;
          },
        });
      },
    };
    """
    table = traitlets.Unicode().tag(sync=True)

    def __init__(self, coord: boro.Coordinator, table: str, **kwargs):
        super().__init__(coord=coord, table=table, **kwargs)


RowCounter(c, table="flights", selection=sel)

coord.exports provides Query / msql (mosaic-sql), mc (mosaic-core), and createClient. createClient({ model, host, signal }) returns a ctx that exposes:

• ctx.selections.<name> — resolved mosaic Selections, one per boro.SelectionTrait field on the Python class (filter_by / target come from the base; subclasses can declare more).
• ctx.state(name, opts?) — a {get, set, subscribe} handle on a sync trait. Optional {target, clause} opts auto-derive a clause from the trait and publish it to a Selection on every change.
• ctx.liveQuery({ filterBy }, queryFn, onState) — registers a filter-driven query. onState receives {status: 'idle'|'pending'|'success'|'error', data, error}.
• ctx.coordinator — the mosaic Coordinator for one-shot ad-hoc queries (await ctx.coordinator.query(sql, { type: 'arrow' })).
• ctx.client, ctx.clients, ctx.signal — the synthetic primary MosaicClient (clause source identity), the Set of all sibling clients used for cross-filter exclusion in state-derived clauses, and the abort signal scoped to this render.

example

uv run jupyterlab examples/