SQLNB Format Specification

Overview

SQLNB is a SQL notebook format: plain .sql files with configuration in comments. Cells are delimited by semicolons.

Cell Structure

A notebook is a sequence of cells. Each cell is SQL terminated by a semicolon.

select 1;

select 2;

This produces two cells. Blank lines between cells are ignored.

Notebook Configuration

Configuration at the top of the file, before any SQL. A blank line separates notebook configuration from the first cell.

-- connection: analytics_warehouse
-- cache: 1h

select * from users;

Configuration syntax

Single-line: -- key: value

-- connection: warehouse
-- cache: 1h

Block (YAML): For complex configuration, use SQL block comments:

/*
connection: warehouse
cache: 1h
*/

Cell Configuration

Configuration immediately before a cell's SQL (no blank line).

-- connection: replica
select * from logs;

Naming cells

Format: -- @name or -- @name [Optional Title]

The name is used for dataset references. The display title defaults to the name transformed to title case with underscores replaced by spaces (@daily_revenue becomes "Daily Revenue"). Override with brackets: @daily_revenue [Revenue by Day].

Scope

Connection scope is determined by blank lines:

-- connection: warehouse

select * from users;

-- connection: replica
select * from logs;

The first connection is notebook-level (blank line before SQL). The second is cell-level (no blank line).

Directive syntax

Cell configuration also supports directives for visualization:

Single-line: -- directive { key: value, key: value }

-- bar { x: "month", y: "revenue" }
select * from orders;

Directive syntax uses comma-separated key: value pairs inside braces. String values use double quotes. Numbers, booleans, and arrays are unquoted:

-- line { x: "date", y: ["revenue", "profit"], stacked: true }

Block (YAML):

/*
@daily_revenue
bar:
  x: date
  y: revenue
  color: region
*/
select date, region, sum(amount) as revenue from orders group by 1, 2;

Visualization Directives

Directives control how cell results render. Without a directive, results render as a table.

table

-- table { freeze_columns: 2, freeze_rows: 1 }
select * from employees;

Charts

Types: bar, line, area, scatter, pie, donut

/*
line:
  x: date
  y: [revenue, profit]
  title: financial performance
  legend: right
  xFormat: "%Y-%m-%d"
  yFormat: ",.0f"
*/
select date, revenue, profit from financial_metrics;

ChartSeries

Chart-only cells

Reference a named cell's dataset without executing SQL:

/*
line:
  x: date
  y: revenue
  title: 30-day trend
dataset: daily_revenue
*/

• dataset references an upstream cell named with @name
• No SQL required; the cell renders the referenced dataset
• Chaining supported: cell C can reference cell B which references cell A

Complete Example

-- connection: analytics_warehouse
-- cache: 1h

/*
@daily_revenue
bar:
  x: date
  y: revenue
  title: daily revenue
*/
select
  date(order_timestamp) as date,
  sum(amount) as revenue
from orders
where order_timestamp >= current_date - interval '30 days'
group by 1
order by 1;

/*
line:
  x: date
  y: revenue
  title: 30-day revenue trend
dataset: daily_revenue
*/

Types Reference

duration

Format: <number><unit> where unit is s (seconds), m (minutes), h (hours), or d (days).

Examples: 30s, 5m, 1h, 7d