Canvas

Arrange result panes freely when the answer is easier to understand side by side.

Canvas lays result sets onto a grid you define with comments. It is for dashboard-style queries where a summary belongs in one place and detail sets belong somewhere else - and because the layout lives in the SQL, it travels with the file.

Declaring the grid

One directive sets the board size, rows × columns. Each placement directive then goes above a statement and claims a cell as row|column, both 1-based:

-- sqlly 2x2

-- sqlly result: 1|1
SELECT ...;   -- top-left cell

-- sqlly result: 1|2
SELECT ...;   -- next cell across

Spanning cells

Either side of the | can be a range, so a result set can occupy a block. A wide summary across the top of a four-column board, with detail beneath:

-- sqlly 2x4

-- sqlly result: 1|1-4
SELECT ...;   -- full-width banner row

-- sqlly result: 2|1-2
SELECT ...;   -- bottom-left half

You do not have to place everything

Any statement without a placement - and any extra result set a statement returns - is auto-placed into the next open cell, scanning left to right and top to bottom. So you can position the two sets that matter and let the rest fall in.

When the board does not work out

SQLly reports layout problems in the editor rather than silently doing something arbitrary:

• A malformed placement - not row|column, not positive integers, or a range that ends before it starts - is reported, and that result set is auto-placed instead.
• A cell claimed twice, or a placement outside the declared grid, is flagged.
• A placement comment not followed by a result-producing statement is flagged - the usual cause of a cell you expected to fill staying empty.
• No open cell left for a result set says exactly which one could not be placed, so you know to make the board bigger.

These are SQLly directives like any other - ordinary SQL comments, inert in every other tool.