ggsql Jupyter Kernel

A Jupyter kernel for executing ggsql queries with rich inline visualizations.

Overview

The ggsql Jupyter kernel enables you to run ggsql queries directly in Jupyter notebooks, with plots rendered in the kernel and delivered as images. It maintains a persistent DuckDB session across cells, allowing you to build up datasets and create visualizations interactively.

Features

• Execute ggsql queries in Jupyter notebooks
• Rich visualizations rendered in the kernel and shown inline
• Persistent DuckDB session across cells
• Pure SQL support with HTML table output
• Grammar of Graphics syntax for declarative visualization

Installation

Prerequisites

• Jupyter Lab or Notebook installed

Option 1: Install from PyPI (Recommended)

The easiest way to install the ggsql kernel is from PyPI. This provides pre-built binaries for Linux, macOS, and Windows.

Using pip:

pip install ggsql-jupyter
ggsql-jupyter --install

Using uv:

uv tool install ggsql-jupyter
ggsql-jupyter --install

The --install flag registers the kernel with Jupyter. It automatically detects and respects your current environment (virtualenv, conda, uv, etc.).

Option 2: Install from crates.io

Requires a Rust toolchain:

cargo install ggsql-jupyter
ggsql-jupyter --install

Option 3: Download Pre-built Binary

Pre-built binaries are available from GitHub Releases:

After downloading, make it executable and install:

chmod +x ggsql-jupyter-*
./ggsql-jupyter-linux-x64 --install

On Windows (PowerShell):

.\ggsql-jupyter-windows-x64.exe --install

Option 4: Build from Source

Requires a Rust toolchain. From the workspace root:

cargo build --release --package ggsql-jupyter
./target/release/ggsql-jupyter --install

Installation Flags

• --install: Install the kernel (default: user install)
• --install --user: Explicitly install for current user
• --install --sys-prefix: Install into sys.prefix (for conda envs)

Verify Installation

jupyter kernelspec list

You should see ggsql in the list of available kernels.

Usage

Start Jupyter

jupyter lab
# or
jupyter notebook

Create a ggsql Notebook

1. In Jupyter, click "New" and select "ggsql" from the dropdown
2. Start writing ggsql queries!

Example Queries

Simple Point Plot

SELECT 1 as x, 2 as y, 'A' as category
UNION ALL
SELECT 2, 4, 'A'
UNION ALL
SELECT 3, 3, 'B'

VISUALISE x, y, category AS color
DRAW point

Time Series

SELECT
    '2024-01-01'::DATE + INTERVAL (n) DAY as date,
    n * 10 as revenue
FROM generate_series(0, 30) as t(n)

VISUALISE date AS x, revenue AS y
DRAW line
SCALE x
  SETTING type => 'date'
LABEL title => 'Revenue Growth', x => 'Date', y => 'Revenue ($)'

Multi-Layer Plot with Global Mapping

SELECT x, x*x as y, x*x*x as z
FROM generate_series(1, 10) as t(x)

VISUALISE x AS x
DRAW line
  MAPPING y AS y
DRAW line
  MAPPING z AS y
LABEL title => 'Polynomial Functions'

Pure SQL (Data Tables)

SELECT * FROM (VALUES (1, 'a'), (2, 'b'), (3, 'c')) AS t(id, name)

This will display as an HTML table without visualization.

Building Up Data Across Cells

Cell 1:

CREATE TABLE products AS
SELECT * FROM (VALUES
  (1, 'Widget', 10.99),
  (2, 'Gadget', 24.99),
  (3, 'Doohickey', 5.99)
) AS t(id, name, price)

Cell 2:

SELECT * FROM products
VISUALISE name AS x, price AS y
DRAW bar
LABEL title => 'Product Prices', y => 'Price ($)'