JupyterLab
The Pivotal JupyterLab extension provides a cell magic, a live viewer panel, an object explorer sidebar, keyboard shortcuts, and notebook export tools.
Installation
Restart JupyterLab after installing.
Cell magic — %%pivotal
Write Pivotal DSL in a notebook cell by starting it with %%pivotal:
%%pivotal
load "data/sales.csv" as sales
with sales as summary
group by region
agg sum revenue as total
sort total desc
Run the cell normally (Shift+Enter). Results appear in the Pivotal Viewer panel.
Autocomplete
Pivotal cells provide context-aware completions for commands, tables, columns, functions, and Pivotal values. When the completion menu is open, use the up and down arrow keys to move through suggestions, then press Enter or Tab to accept one.
Per-cell options
Pass options on the magic line to override session settings for that cell only:
%%pivotal backend=duckdb output_code=true
with sales as summary
group by region
agg sum revenue as total
%pivotal_set — session settings
Set options that apply to all subsequent %%pivotal cells:
%pivotal_set backend=duckdb
%pivotal_set output_code=true viewer=false
%pivotal_set canvas=a4 margins=20
Run %pivotal_set with no arguments to display current settings.
All settings
| Setting | Values | Default | Description |
|---|---|---|---|
backend |
pandas, polars, duckdb, sql |
pandas |
Execution backend |
viewer |
true, false |
true |
Send results to the Viewer panel |
output_code |
true, false |
false |
Print generated Python code below each cell |
canvas |
none, a4, a4_landscape, a3, a3_landscape, letter, slide |
a4 |
Page size for table rendering |
margins |
float (mm) | 25.4 |
Page margins for table rendering |
chart_width |
full, half |
full |
Chart width as fraction of page |
viewer_font |
float (em) | 1.0 |
Font size in the Viewer panel |
viewer_num_format |
integer | 5 |
Significant digits for floats (0 = no formatting) |
use_visions |
true, false |
false |
Use the visions library for type inference |
Viewer panel
The Viewer panel opens on the right side of JupyterLab and displays DataFrames, charts, and tables as they are computed.
- Navigation: use the back/forward arrows or
Alt+←/Alt+→ - Zoom:
Alt+=/Alt+- - Delete object:
Alt+Delete - Focus table:
Alt+V
The viewer formats large DataFrames with configurable float precision (viewer_num_format) and font size (viewer_font).
Object Explorer
The Object Explorer sidebar lists all tables and charts currently in memory. Open it with Alt+E or from the left sidebar.
Click any object to load it in the Viewer.
Keyboard shortcuts
| Shortcut | Action |
|---|---|
Alt+P |
Insert a new Pivotal cell below |
Alt+L |
Insert a load-data cell |
Alt+T |
Insert a pivot table cell |
Alt+C |
Insert a pivot chart cell |
Alt+S |
Insert a save cell |
Alt+V |
Focus Viewer panel |
Alt+E |
Open Object Explorer |
Alt+N |
Focus notebook |
Alt+← |
Viewer: back |
Alt+→ |
Viewer: forward |
Alt+= |
Viewer: zoom in |
Alt+- |
Viewer: zoom out |
Alt+Delete |
Delete selected object from Viewer |
Export to Code File
Convert the current notebook to a Python or SQL file via the Pivotal menu → Export to Code File.
A dialog lets you choose the format:
| Option | Output | Description |
|---|---|---|
| Pandas (.py) | .py |
Each %%pivotal cell compiled to pandas Python |
| DuckDB (.py) | .py |
Each %%pivotal cell compiled to DuckDB Python |
| SQL (.sql) | .sql |
Each %%pivotal cell as a SQL CTE chain |
| Pivotal (.pivotal) | .pivotal |
DSL cells as-is; Python cells wrapped in python...end |
The file is created in the same directory as the notebook.
GUI tools
Pivotal provides interactive GUI helpers accessible from Python cells:
import pivotal
pivotal.load_gui() # file chooser to load data
pivotal.pivot_gui() # visual pivot table builder
pivotal.plot_gui() # visual chart builder
pivotal.save_gui() # save data package
pivotal.settings_gui() # Pivotal settings panel
These launch widget-based dialogs and generate the corresponding Pivotal code into a new cell.
Accessing results in Python
Tables computed in %%pivotal cells are available as regular Python variables in subsequent cells: