PlotQL

A SQL-like query language for creating plots. No Python boilerplate, no remembering matplotlib syntax — just describe what you want to plot.

Quick Start

The easiest way to use PlotQL is through the interactive TUI, which allows you to plot data without leaving your terminal:

# Setup (requires uv)
git clone https://github.com/your-username/plotql.git
cd plotql && ./ctl.sh setup
source .venv/bin/activate

# Launch the TUI
plotql

Write queries like:

WITH source('docs/example.csv')
    PLOT price AGAINST received_at AS 'line'
    FORMAT color = 'peach'

Press F5 to execute. See TUI documentation for keyboard shortcuts and features.

If you don't have uv, install it from astral.sh/uv.

Python API

PlotQL's core is a standalone library, independent of the TUI. Use it in scripts, Jupyter notebooks, or embed it in your own applications:

from plotql.core import parse, execute, render

query = parse("WITH 'data.csv' PLOT revenue AGAINST month AS 'bar'")
data = execute(query)
result = render(data)

result.save("chart.png")     # Save to file
result.show()                # Display in Jupyter
result.figure                # Access matplotlib figure for customization

This separation means you can use PlotQL's query language in whatever context makes sense for your workflow.

Documentation

• Syntax & Python API — Full language reference, operators, aggregations, and Python usage
• Connectors — Data sources: files, folders, ClickHouse databases
• Engines — Rendering backends and customization
• TUI — Interactive terminal interface

Contributing

See CONTRIBUTING.md for:

• Development setup
• Architecture overview (core/engines/connectors/UI separation)
• Theme system
• Tree-sitter grammar workflow
• Feature checklist

License

MIT