malloy-dashboards

Publisher Dashboards

A dashboards/*.malloy file is a dashboard. It imports the model, either declares one query and applies its own filtering or names views that already do, and tags the layout. Publisher discovers it at package load, renders the filter controls from the givens it references, offers # drill click-through between pages, and serves it at /<env>/<pkg>/dashboards/<name>. No code, no build step.

When this is the right tool

Notebooks and dashboards run the same engine, so interactivity is not the axis: both get filter controls, URL-addressable state, Apply batching, and # drill. Pick on the shape of the document. Scanned at a glance is a dashboard; read top to bottom is a notebook.

Build sequence

1. READ THE MODEL FIRST. Get the real source, view, dimension, and given names from the package: get_context if you have it, otherwise the REST model endpoint or the .malloy files. Never guess a name. A guessed field in a query fails the whole package load, not just that one dashboard; a guessed tile or suggest source is quieter, and only shows up in the package warnings.
2. PICK THE VIEWS TO SHOW. A dashboard is ## artifact { tiles=[…] } naming existing views, so this is the design step: which views, how wide each sits, what each is called. There is one form, so there is no form to choose.
3. DECLARE THE GIVENS the dashboard will filter by, in the model (usually givens.malloy), with their control tags: see "Filter controls" below for the syntax and what each tag renders as. Skip if they already exist, since a given is a model concern and dashboards share them.
4. COMPOSE THE FILE for dashboards/, following the template below, but do not save it yet. Import every given it filters by, and every source or query any of those givens names in a suggest. Both are per-file, and getting the suggest wrong does not error: the control still looks like a picker but has no options, and says so underneath, "Could not load the options for this control". The package warnings name it too. A suggest naming a query= needs that query's own source imported as well, because an import is not transitive: the query resolves by name, so the file compiles and the package loads, but running the picker fails with Undefined source '<name>'. The package warnings name this one too, saying which source to import. Import the source that suggest query reads, not just the query.
5. COMPILE IT with compile_model (or POST …/models/<path>/compile), against the source text, before you save, at the path the file will have. Editing one that already exists needs "scope": "file", which compiles your source AS that file; the default appends it instead, so every imported name and the query name collide with the saved copy and you get a wall of already-defined errors that reads as broken Malloy rather than a wrong scope. Editing a shared include wants "scope": "package", which recompiles every file as saved: file only checks the one you are editing, so renaming a source in _shared.malloy passes it while breaking every dashboard that imports it. A clean compile is not a working dashboard: some tag mistakes surface at step 6, and some only when you look at the page in step 7. (The third scope, append, is the default and is what a not-yet-saved file gets.)
6. SAVE IT, RELOAD, AND READ THE MANIFEST AND THE WARNINGS. reload_package, or GET …/packages/<pkg>?reload=true. Check the status the reload returns as well as the warnings: a 424 means the package did not load and your edit is not live. The warnings key is absent when there are none, so an empty response is the pass, not a sign you are reading the wrong field. Then read GET …/packages/<pkg>/dashboards/<name>: its givens are exactly the controls that will render, which catches a given you imported but never referenced before you open the page, and its query is the name to run in step 7. See "Read the lint" below.
7. OPEN IT AND LOOK. Not optional; see "What 'done' means".