Reports

How dashboards and notebooks work as .malloy report files, how to build them with the agent, where they appear, and how to add filter controls with givens

A report is a dashboard or a notebook, saved as a Malloy file in a package or in a workspace. The file names the views to show, lays them out, and declares the filters a viewer can change.

Every viewer runs a report as themselves, so a source with access rules shows each person only the rows they may see.

The two kinds differ only in shape:

  • A dashboard is read at a glance: tiles on a grid.
  • A notebook is read top to bottom: text between the results.

Both get the same filter controls, shareable URLs, and click-through.

Where They Appear

  • A report saved in a package is listed in the Reports section of the package's page. It ships, and is versioned, with the package.
  • A report saved from a chat is listed in the Reports section of that workspace. It reads the published model and doesn't change the package.

Ask the Agent

You don't need to write a report by hand. Ask in a chat, for example "build me a dashboard of revenue by brand and by month, with a filter on product category".

  • In a draft package (a modeling chat), the agent writes the report as a .malloy file in the package, at the package root unless you ask for a folder. It ships with the package when you publish.
  • In an analysis chat, the agent saves the report to the chat's workspace. It reads a published model and doesn't change the package.

To change a report, ask again in a chat: "add a filter on brand", "add a tile with order count by month".

What the File Looks Like

A file is a report because of the artifact tag at the top of the file, not because of where it sits in the package. The tag's layout says which kind:

  • A dashboard is ## artifact { layout=grid tiles=[...] }.
  • A notebook is ## artifact { layout=linear tiles=[...] }, with text entries between the query tiles.

A dashboard lists its tiles, followed by the views those tiles name:

##! experimental.givens
## artifact { layout=grid title="Storefront overview" tiles=["overview -> revenue_trend", "overview -> revenue_by_brand"] } dashboard { columns=12 }
import { order_items, products } from 'storefront.malloy'

# label="Category" control=select suggest { source=products dimension=category }
given: CATEGORY :: filter<string> is f''

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

  # colspan=4
  # label="Revenue by brand"
  view: revenue_by_brand is sales_by_brand + { where: category ~ $CATEGORY }
}
  • tiles=[…] names each tile as source -> view, in order.
  • dashboard { columns=12 } sets the grid width, and # colspan=N on a view sets how wide its tile is.
  • ##! experimental.givens is required in any file that declares a given:.

The full format, including text tiles, grid layout and the checks Publisher runs when it loads a package, is in Publisher's reports reference (opens in a new tab).

Add Filter Controls with Givens

A filter control is a given: a named parameter declared with given: and read with $NAME.

  1. Declare the given with its control tags. control=select renders a dropdown, and suggest { … } fills it with a dimension's values. The default f'' matches every row.
  2. Bind it on each tile that should respond to it, with a refinement: + { where: category ~ $CATEGORY }. A filter<…> given binds with ~, and a plain date or number given binds with >=, <= or =. A date or number given always filters from its default value (for example SINCE :: date is @2023-01-01), because unlike f'' it has no default that matches every row.

Only givens that some tile reads become controls. A given the model already declares is imported by name rather than declared again.

The legacy #(filter) annotation is deprecated; use givens instead: a required filter becomes a given with no default, an implicit filter becomes #(access_filter), and a range becomes a filter<date> or filter<number> given. See Row and Column Access.

Givens in Workspace Reports

A report saved to a workspace from a chat may declare its own given: filters, and they render as controls, the same as in a package report. Two limits apply:

  • It may not import a file.
  • A given it declares may not reuse the name of a given the model declares, or a name Credible fills from the viewer (GROUPS, ORG_ROLES, CELL_ID).

A value a viewer picks only narrows what the model already lets that viewer read. It never widens access.

Legacy .malloynb Notebooks

The .malloynb notebook format is deprecated. Existing .malloynb files still open and run, read-only, as linear reports. Don't create new ones: write a .malloy report with layout=linear, or ask the agent to convert an existing notebook.

Next Steps

On this page