Jupyter notebooks

Open .ipynb notebooks as SQLly notebooks and save SQLly notebooks back out in the standard Jupyter format.

Jupyter's notebook format, .ipynb, is specified by the nbformat project and used unchanged by JupyterLab, VS Code, and Azure Data Studio's SQL notebooks. SQLly opens those files as SQLly notebooks and writes them back out, so a notebook can move between SQLly and those tools without a copy-and-paste session.

Opening an .ipynb

Use File → Open Notebook…, the Open SQL dialog, or a recent file, then pick the connection to run against: an Azure Data Studio notebook's saved connection does not come along. Code cells become SQL cells and Markdown cells stay Markdown; a cell that was collapsed stays collapsed. Cells written for Jupyter's SQL magics have the leading %%sql line (or %sql prefix) removed, so the SQL runs as written. Raw cells come in as Markdown so their text is not lost. Files older than nbformat 4 are refused with a message; open and save them once in Jupyter to upgrade them. Stored outputs are not imported: a notebook's saved results came from someone else's connection at some other time, so you run the cells against your own.

Saving as .ipynb

Save a notebook under a name ending in .ipynb and SQLly writes a standard nbformat 4 notebook with a SQL kernel, the same shape Azure Data Studio writes, which VS Code and JupyterLab open as well. A notebook opened from an .ipynb keeps saving in that format, and Export Jupyter in the notebook toolbar writes an .ipynb copy of any notebook while the tab keeps its own file. SQLly's @name parameters ride along in the notebook's metadata, where other tools ignore them and SQLly picks them up again. Results are not saved into the file, just as with SQLly's own .sqlnb.json notebooks; to share results, use Export Markdown.

SQLly notebooks can refer to an earlier cell as {{cell_2}}. Other tools see that text as written, so a notebook that leans on cell references runs fully only in SQLly.