Malloy Notebooks

<!--
Copyright (c) Credible Data Inc.
SPDX-License-Identifier: MIT
-->

Malloy Notebooks

Files: notebooks/<slug>.malloy. Author a notebook as a one-column layout of tiles (next section). Notebooks written as run: cells, and existing .malloynb files, are still read and served, but a new notebook is never a .malloynb.

Scope: when to use this skill vs skill:malloy-analysis-report

This skill is for curated notebooks that live in a package. Interactive parameter widgets render automatically from the given: declarations the notebook file declares or imports.

For ad-hoc reports generated by an analysis agent, combining queries into a quick narrative artifact, use skill:malloy-analysis-report instead. Ad-hoc reports also inherit whatever the source declares.

What makes a file a notebook

A notebook is a .malloy file directly under the package's top-level notebooks/ directory (not a subdirectory) whose model-level notes include ## artifact { kind=notebook … }. The artifact tag turns the file into a notebook. A .malloy file under notebooks/ with no artifact tag is a shared include, not a notebook, and is left out of the notebook list. Publisher serves the notebook at /<env>/<pkg>/notebooks/<slug> and lists it beside any .malloynb files. The tag's kind= decides the document's kind, not the folder.

The file is ordinary Malloy: it compiles as one model, it is validated by the same /compile call as any model, and its cells run against the whole file (every import and given: in scope).

Author a notebook as a layout of tiles

A notebook is a dashboard with one column. Its artifact tag lists the tiles in reading order, each either a query ("source -> view", always a quoted string) or a prose block (name { kind=text }, a bare name), and the file defines the views and the prose:

##! experimental.givens
##" One category at a time: how it sells across the year and which brands carry it.
##| artifact { kind=notebook title="Category review"
  tiles=[
    intro { kind=text },
    "category_tiles -> revenue_trend",
    "category_tiles -> brand_ranking"
  ]
}
|##
import { order_items, products } from "../storefront.malloy"

#(description="Narrow to one product category")
# label="Category" control=select suggest { source=products dimension=category }
given: CATEGORY :: filter<string> is f''

##|(markdown) intro
## Category review

Pick a **Category** in the controls above and every chart below re-runs for it.
|##

source: category_tiles is order_items extend {
  # line_chart
  # label="Revenue by month"
  view: revenue_trend is sales_by_month + { where: category ~ $CATEGORY }

  # bar_chart
  # label="Top brands"
  view: brand_ranking is top_brands + { where: category ~ $CATEGORY }
}

• The tag is one line (## artifact { … }) or a ##| … |## block with the same text inside, the form to use once the list is long: one tile per line, } on its own line, |## closing at the opener's column. Both read, lint and edit the same, and the builder keeps whichever form the file has. tiles=[…] is the notebook: tiles render top to bottom in list order, one column wide. dashboard { columns } other than 1 has no effect on a notebook, and a colspan or break on a tile entry is ignored with a warning (notebook-tile-layout-ignored).
• Quote every query entry. "orders_tiles -> headline" is a string; orders_tiles -> headline unquoted does not parse, and the lint says so (notebook-artifact-unparsed) rather than reading the file as a cell notebook.
• A query tile is a view: on a source, named as "source -> view". Put the views on a <source>_tiles extension as thin wrappers (view: revenue_trend is sales_by_month + { where: … }): the modelled view keeps its chart tag, the wrapper says which controls the tile answers to and carries the tile's # label. A run: in a layout notebook is never shown, and the lint reports it (notebook-layout-run): define a view, list it in tiles, and delete the run:.
• A prose tile is a ##|(markdown) name block listed as name { kind=text }. The name is one bare word on the opener line, the body starts on the next line (a heading goes inside the block), and |## closes it at the opener's column. Every text entry needs its block, and every named block needs an entry written with { kind=text }: a bare intro without it is the query-tile form (it names a query: in the file), so a block of that name is not shown.
• Place the file in one order: header, imports and givens, then the prose blocks in tile order, then the <source>_tiles extension. Tiles read in tiles=[…] order wherever their blocks sit; grouping the blocks before the extension is the convention the builder writes, and it inserts a new block after the last one.
• Chart tags go on the view (# line_chart, # label="…"), as on a dashboard; the malloy-dashboards skill has the tag set and the lint.
• Givens work as in any notebook: declare given: above the view that reads it as $NAME, with the controls tags shown.
• Tiles run through the model query endpoint, and the notebook also carries cells made from its tiles, so cell runs, get_context and notebook chat work on it as on any notebook.
• The tag's kind= decides the document's kind, not the folder. Keep notebooks in notebooks/ and dashboards in dashboards/; a file in the other folder works, and the lint notes it (notebook-other-folder). An untagged .malloy file in notebooks/ is a shared include.

The rest of this skill (the header rules, given:, charts, style) applies to both forms. The sections on cells describe the older form, where the file is a sequence of run: statements and (markdown) notes: Publisher still reads it, and a person saving it in the Console converts it to a layout.

The five authoring rules (cell notebooks)

Rules 1 and 4 hold for both forms; rules 2, 3 and 5 are about run: cells and prose notes.

1. The header is ##! flags, // comments and unnamed " notes (the description), then ## artifact { kind=notebook … }. Nothing else goes above the tag. A statement or a tag above ## artifact is an error, and the notebook is served with that error instead of opening.
2. Prose is a (markdown) annotation, and the number of # says what it belongs to. Floating markdown is a cell of its own: ##(markdown) text (contiguous lines with no blank line between them merge into one cell) or a ##|(markdown) block, with the body starting on the next line and the |## closer at the opener's column. Attached markdown, #(markdown) text or a #|(markdown) … |# block, belongs to the statement below it and renders with that cell. Keep the parentheses: ##| markdown reads its prose as ordinary tags, and ##|markdown draws a malformed-route warning. No body line starts with |##, and a blank line follows the closer. A ## Heading line is model tags, not prose: write a heading inside a ##|(markdown) block.
3. Render tags sit directly above run:, with nothing between. A #" directly above the run: is its caption; # bar_chart, # label="..." and the other render tags go in the same block. Attached #(markdown) goes above the #" caption when both are present, and renders as a header above the result.
4. given: uses NAME :: filter<T> is f'', bound with ~, declared before first use. Put ##! experimental.givens at the top of the file.
5. Trailing prose is ##(markdown), never #(markdown) or #". Both belong to the statement below them, and at the end of a file there is none, so Malloy refuses a #" and the lint reports a #(markdown) as an error. An import or an export takes no annotation either, so prose above one is ##|(markdown).

How the file becomes cells

Cells come from the file's own notes and statements, in file order (imported files add none):

The unnamed " notes above ## artifact are the notebook's description. Definition cells render folded; only query cells run. Earlier spellings are still read: ##", ##|", ##(text) and ##|(text) notes below the tag are markdown cells, like (markdown). Write (markdown).

Compile errors and checking a notebook

Compile the file with /compile, at the path it will have and with "scope": "file". A file under notebooks/ also gets the notebook lint: a file that would not open (a statement above the tag, an ## artifact tag that does not parse, a prose line the reader cannot place) comes back as an error problem naming the line and the fix, and the package warnings carry the same finding after a reload. Read those before you call the notebook done, then open it and look.

Multiple Models & Cross-Model Joins

A notebook file compiles with all its imports in scope, so it can import several .malloy models, and a single cell can reference, and join, sources from different imported files. Import each model you need at the top; no "re-export" wrapper model is required.

When the package root holds an index.malloy, cells read only what it exports. A cell over a source index.malloy does not export answers 404, even when the notebook imports that source's file. A source the notebook derives from an exported one (source: mine is customers extend { ... }) still works. A cell's own source over a raw table (duckdb.table(...)) is refused. To use a source in a notebook, add it to the export { ... } in index.malloy. A package with no index.malloy and no legacy explores has no such limit.

import "flights.malloy"
import "carriers.malloy"

##(markdown) Flights joined to carriers, across two imported files.

run: flights extend {
  join_one: carriers on carrier = carriers.code
} -> {
  group_by: carriers.nickname
  aggregate: flight_count
}

Imports are file-wide: declare them at the top, before the cells that use them. A query cell runs as a restricted query against the already-compiled file, so an import inside a run: is rejected (file imports are not permitted in a restricted query).

No Data-Specific Insights in Markdown

Notebooks must NOT contain findings about current data values. Data refreshes will make these stale. Use markdown for framing questions and structural narrative, not for stating results.

##(markdown) WRONG: will become stale when data refreshes. Revenue spiked 23% in March.

##(markdown) RIGHT: frames the question and lets the query answer it. How is revenue trending?

A complete cell notebook

One notebook with all three prose forms: floating markdown cells, attached markdown headers, and a #" caption.

##! experimental.givens
##" One category at a time: how it sells across the year and which brands carry it.
## artifact { kind=notebook title="Category review" }
import { order_items, products } from "../storefront.malloy"

##|(markdown)
## Category review

Pick a **Category** in the controls above and every chart below re-runs for it.
Leave the control empty to read the whole catalog.
|##

#(description="Narrow to one product category")
# label="Category" control=select suggest { source=products dimension=category }
given: CATEGORY :: filter<string> is f''

##(markdown) How is revenue trending for the selected category?

#(markdown) ### Revenue by month
#" Revenue by month for the selected category
# line_chart
# label="Revenue by month"
run: order_items -> sales_by_month + { where: category ~ $CATEGORY }

##(markdown) Which brands are behind those numbers?

#" The eight brands with the most revenue in the selected category
# bar_chart
# label="Top brands"
run: order_items -> top_brands + { where: category ~ $CATEGORY }

##(markdown) Last, the best-selling products, defined once as a named query and then run.

query: top_products_in_category is order_items -> top_products + { where: category ~ $CATEGORY }

#(markdown) ### Best sellers
run: top_products_in_category

The ##|(markdown) block and each ##(markdown) line are floating markdown cells. The two #(markdown) lines are attached: each renders as a header with the run: below it, and on the first the header sits above the #" caption. The second run: has only a caption. The given: and the query: are definition cells, and each run: is a query cell. The header ends at ## artifact.

Interactive Parameters (given:)

Interactive parameters are common and important. Add them to most notebooks. Use given:. Never add a #(filter) annotation, even if the model you are extending already has some: it is deprecated and the notebook does not render it (see below).

A notebook's parameter surface comes from the given: declarations the file declares or imports. Publisher's notebook UI renders a Filters panel above the notebook: declared givens become parameter inputs, the values a user sets are forwarded to Malloy's runtime, and every query cell re-executes with those values applied. A given: is read by the cells below it, so declare it before the first cell that uses it.

The widget for each parameter follows the given's declared Malloy type (string, string[], number, boolean, date/timestamp, filter<T>); see docs/givens.md for the full type table. A #(description="...") annotation on the given renders as helper text under its input. It draws a cosmetic malformed-route warning that you can ignore; see docs/givens.md § Annotations. A control tag (control=select suggest { source=… dimension=… }) goes on the given: as shown in the complete notebook above.

malloy-model § Access Control covers the syntax and the #(authorize)/#(access_filter) gating story built on top of givens.