Malloy Analysis Report

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

Creating Reports

An ad-hoc report is a .malloy notebook, notebooks/<slug>.malloy, that combines markdown narrative with live Malloy queries. An ad-hoc report is written as run: cells, which Publisher still reads and which convert to the one-column tile layout when saved in the Console; when the queries are views on a source, skill:malloy-notebooks describes the layout form (tiles=[…]) to author instead. Load skill:malloy-notebooks for the full format and authoring rules; this skill covers when to build one and how to design good report content (cells, chart annotations, narrative structure). Never write a new .malloynb.

Tool names are written bare here - get_context, execute_query, search_malloy_docs. The exact prefixed name depends on the host surface; match each against the tools you actually have.

Before building a report

1. Run each query first via execute_query to verify it works and returns expected results.
2. Explain the results to the user as you go: walk through the analysis step by step.
3. Then assemble the notebook once the analysis is validated.

Do NOT build the notebook in the same turn as execute_query. Explain first, then build.

Filters are inherited from the model, don't declare them in the report

Do not declare filters in an ad-hoc report. If the source declares given: parameters (or legacy #(filter) annotations), Publisher renders the controls, parses caller parameters, and applies them server-side automatically: the report inherits and displays them with no extra work. If the analysis needs a knob the source doesn't expose, the right move is to add a given: to the source itself, not to wedge a filter widget into the report. #(filter) is deprecated in favour of native Malloy given: parameters. Never add a #(filter) annotation: every use, including required, implicit, and date/number ranges, has a given: form. The malloy-model skill covers this under § Legacy: Parameterizable Filters. For curated notebooks with their own per-notebook filter UI on top of the model, see skill:malloy-notebooks instead.

What goes in the report

Do NOT add an H1 heading in any markdown (use H2 and below for sections); the title in the ## artifact tag serves as the title. To redo the structure rather than tweak one cell, rewrite the notebook file end-to-end.

Markdown cells own narrative; query cells own a single Malloy query whose chart annotation tells the renderer how to display the result. Markdown supports H2 headings, lists, bold, and inline code. Keep narrative cells short, one idea per cell, so the rendered output reads as a story instead of a wall of text.

The file starts with ## artifact { kind=notebook title="..." }, then the import for the model file. Definitions (import, source:, query:, given:) come before the first markdown or run:. Prose is ##|(markdown) ... |## for a block (body on the lines between) or ##(markdown) text for one line. Each run: is a query cell, and its tags sit directly above it with nothing between. A #" directly above the run: is its caption. Trailing prose is ##(markdown), never #(markdown) or #".

This is the cell format, the quick form for an ad-hoc report; for a notebook that will be kept and edited, write the layout form in skill:malloy-notebooks (## artifact { kind=notebook tiles=[…] }) instead.

Each run: must be a standalone query (for example run: source -> { ... }). The import is file-wide: query cells never repeat it. Compile the file with /compile ("scope": "file", at the path notebooks/<slug>.malloy) before saving; a .malloy notebook compiles as a model, so its errors come back there. A complete report:

## artifact { kind=notebook title="Sales report" }
import "../order_analysis.malloy"

##|(markdown)
## Overview
What is driving sales, and which categories carry it? The queries below cover every order in the model.
|##

# big_value
run: order_analysis -> {
  aggregate:
    # label="Revenue"
    # currency
    total_revenue

    # label="Orders"
    # number=auto
    order_count
}

##(markdown) ## Trend: how does revenue move over time?

#" Revenue by month
# line_chart
run: order_analysis -> {
  group_by: order_date.month
  aggregate: total_revenue
  order_by: 1
}

##|(markdown)
## Breakdown
Which categories account for the most revenue?
|##

#" Top ten categories by revenue
# bar_chart
run: order_analysis -> {
  group_by: category
  aggregate: total_revenue
  order_by: total_revenue desc
  limit: 10
}

##(markdown) ## Key takeaways: what to look at next.

A well-structured report typically follows this pattern:

[Markdown]  ## Overview: what question are we answering, what data is in scope (date range, entity count)
[Malloy]    KPI cell: headline numbers (e.g., # big_value, or # dashboard with nested # big_value cells)
[Markdown]  ## Trend: describe what we should look for over time
[Malloy]    Time-series cell (e.g., # line_chart on a date dimension)
[Markdown]  ## Breakdown: where the signal is
[Malloy]    Categorical cell (e.g., # bar_chart on a categorical dimension)
[Markdown]  ## Key takeaways: what the user should walk away with

Use this as a default; deviate when the analysis warrants. A grounded report names the time range and entity count up front so every number that follows has context.