stream-viz

A real-time streaming SQL visualization tool. Write SQL queries against a Timeplus Proton streaming database and instantly see results rendered as live-updating data grids and charts powered by Perspective.

The app provides a split-pane interface: a SQL editor on top (with table/column autocomplete) and a Perspective data viewer on the bottom. Run a streaming query and watch the results flow in and update in real time -- including support for tumbling window aggregations and filtered streams.

Architecture

• Backend (Python/FastAPI): WebSocket server that executes streaming SQL queries against Timeplus/Proton, manages query lifecycle (start/stop/restart), and feeds results into Perspective tables over a second WebSocket channel.
• Frontend (React/TypeScript/Vite): CodeMirror-based SQL editor with schema-aware autocomplete, connected to Perspective viewers for live data grids and D3 charts. State managed with Zustand.

Prerequisites

• Python 3.9+
• uv (Python package manager)
• Node.js 18+
• A running Timeplus Proton instance

Getting Started

Timeplus Proton

Start a Proton instance with Docker:

docker run -d --name proton -p 8463:8463 -p 3218:3218 d.timeplus.com/timeplus-io/proton:latest

Backend

# Install dependencies
uv sync

# Run the server
uv run python -m stream_viz.main

The backend runs on http://localhost:8585 by default.

Frontend

cd frontend
npm install
npm run dev

Configuration

Create a .env file in the project root:

TIMEPLUS_HOST=localhost
TIMEPLUS_PORT=8463
DEBUG=true

See src/stream_viz/config.py for all available settings.

Development

# Install dev dependencies and pre-commit hooks
make install

# Run linting and type checks
make check

# Run tests
make test

License

MIT